Writing Tips for Better AI Understanding

Product Name: Treeify Version: 0.2-beta Date: 2025.07.10

Writing clear, detailed, and structured requirements helps Treeify generate high-quality test objects and test scenarios. Use the guide and examples below to improve your inputs.

✅ 1. Be Specific and Actionable

Bad Example:

The user can do login.

Good Example:

Users can log in using their registered email and password.

If the login fails, display an error message: "Incorrect email or password."

Lock the account after 5 consecutive failed attempts.

✅ 2. Include Preconditions and Outcomes

Why: Helps Treeify identify test boundaries and expected results.

Example:

When a user has unpaid invoices, they cannot make new purchases.

After successful payment, redirect to the “Order Confirmation” page.

✅ 3. Describe Variations and Roles

Why: Functional differences based on user roles or input values lead to different test paths.

Example:

Admin users can access the "User Management" panel.

Regular users should receive a “Permission Denied” error when trying to access the same.

✅ 4. Include UI Triggers and Interactions

Why: Important for generating interactive and interface-related test cases.

Example:

Clicking the “Download” button should open the file in a new browser tab.

When hovering over a product image, show the zoom-in preview.

✅ 5. Write One Requirement per Line

Why: Makes it easier for the AI to isolate and analyze each intent.

Example:

Users can submit the form only after filling all required fields.

If any required field is empty, show a red border and inline warning message.

After submission, display a toast message: "Form submitted successfully."

🧠 Tip: Use Rich Text Editor Tools

Use:

Headings to organize
Bold text for emphasis
📝 Bullet and numbered lists to break up requirements

🚫 Common Pitfalls to Avoid

❌ Too vague (e.g., "Users can update info")
❌ Mixed multiple behaviors in one line
❌ Describing implementation instead of behavior
❌ Skipping key conditions, roles, or outcomes

📋 Full Example

Checkout & Order Placement – Requirement Specification (Example)

1. Overview

Enable authenticated customers to place an order from the shopping cart, select shipping & payment, review totals (items, tax, shipping, discounts), and receive an order confirmation. Business goals

Increase successful checkouts

Provide clear pricing and taxes

Support promo codes and gift cards

Generate auditable, compliant orders In scope

Cart review, shipping address, shipping method

Payment selection (Credit Card, PayPal)

Promotions/discounts, tax calculation

Order confirmation (page + email) Out of scope

Subscriptions, store credit refunds, loyalty points earning

2. Actors & Roles

Customer (ROLE_CUSTOMER): Can checkout their own cart only

Support Agent (ROLE_SUPPORT): Can view orders; cannot place for customer

System: Payment gateway, Tax service, Email service Access Control

Checkout endpoints require authenticated user with ROLE_CUSTOMER

Admin/Support cannot modify a customer’s cart during checkout

3. Definitions

Cart: Customer’s selected items prior to order

Order: Immutable record created after successful payment authorization

Grand Total: Subtotal + shipping + tax − discounts

4. Preconditions & Assumptions

Customer is logged in

Cart has ≥ 1 item in stock

Billing address = shipping address unless provided

Payment gateway available; fallback retry 3 times with exponential backoff

5. User Stories

US-1: Review Cart

As a customer, I can review items (name, qty, price), apply a promo code, and see updated totals.

US-2: Provide Shipping

As a customer, I can enter/select a shipping address and choose a shipping method (Standard/Express).

US-3: Select Payment

As a customer, I can pay by Credit Card (Visa/Mastercard) or PayPal.

US-4: Place Order

As a customer, I can confirm the order and receive a confirmation page and email with order details.

6. Main Flows

6.1 Checkout Flow (Happy Path)

Customer opens /checkout.

System loads cart, default address, and shipping methods.

Customer applies promo code (optional).

Customer confirms shipping address & selects shipping method.

Customer selects payment method:

Credit Card → enter card details (masked), billing address auto-filled.

PayPal → redirect to PayPal, approve, return with token.

System calculates Grand Total (tax via external service).

Customer clicks Place Order.

System authorizes payment, creates Order, decrements inventory, clears cart.

System shows Order Confirmation page and sends email.

6.2 Alternative/Edge Flows

A1: Promo code invalid/expired → display error, keep prior totals.

A2: No shipping method for address → show guidance & disallow continue.

A3: Payment authorization soft decline → allow retry or select different payment.

A4: Race condition: item goes out of stock at submit → show out-of-stock error, adjust cart.

7. Input / Output (Field-Level)

7.1 Inputs (Forms & APIs)

Promo Code (string, optional): ^[A-Z0-9]{5,10}$

Shipping Address (object): name, line1, line2?, city, state, postal_code (country-validated), country

Shipping Method (enum): STANDARD, EXPRESS

Payment Method (enum): CARD, PAYPAL

Card Details (when CARD):

card_number: tokenized, Luhn valid

exp_month: 1–12

exp_year: >= current year

cvv: 3–4 digits

PayPal Token (when PAYPAL): non-empty string, expires in 10 min

7.2 Outputs

Order Confirmation: order_id, items[], shipping, tax, discounts[], totals (subtotal, shipping, tax, grand_total), payment_status

Errors: code + message (see §10)

8. Validation Rules

Required fields must be present and non-blank.

Postal code must match selected country format.

Only one active promo code at a time.

If PAYPAL, token must be valid (status=APPROVED).

If CARD, card passes Luhn + not expired + CVV format.

9. Business Rules

Taxes computed by external service based on address & items.

Promotions can be percentage or amount; cannot reduce below zero.

Shipping cost: Standard = $5, Express = $15; free shipping if subtotal > $100 after discounts.

Inventory is decremented only after payment authorization succeeds.

10. Exceptions & Error Handling

E001 INVALID_PROMO: “Promo code invalid or expired.”

E002 SHIPPING_UNAVAILABLE: “No shipping method available for this address.”

E003 PAYMENT_DECLINED: “Payment authorization failed. Try again or use another method.”

E004 OUT_OF_STOCK: “One or more items are out of stock.”

E005 TAX_SERVICE_UNAVAILABLE: “We can’t calculate tax right now. Please try again.” Error surfacing:

UI toast + inline field hint where applicable

API response with error.code, error.message

11. UI Requirements

Checkout is a 3-step wizard: Cart → Shipping → Payment → Review & Place

Disable Place Order until all validations pass

Mask card fields; never display full PAN

Show price breakdown and updated totals after each change

12. API Contracts (abridged)

POST /api/checkout/apply-promo

Request:
{ "promo_code": "SAVE10" }
Response:
{ "valid": true, "discount_amount": 10.00, "new_totals": { "subtotal": 90.00, "tax": 8.10, "grand_total": 93.10 } }
POST /api/checkout/place-order

Request:
{
  "shipping_address": { "line1": "123 King St", "city": "Singapore", "postal_code": "049483", "country": "SG" },
  "shipping_method": "STANDARD",
  "payment_method": "CARD",
  "card": { "token": "tok_abc", "exp_month": 12, "exp_year": 2030, "cvv": "123" }
}
Response (success):
{
  "order_id": "ORD-2025-000123",
  "payment_status": "AUTHORIZED",
  "totals": { "subtotal": 90.00, "shipping": 5.00, "tax": 8.10, "grand_total": 103.10 }
}
13. Non-Functional Requirements

Performance: Place Order average ≤ 2s; P95 ≤ 4s; support 500 concurrent checkouts

Availability: 99.9% monthly for checkout APIs

Security: PCI-DSS alignment; tokenize cards; TLS 1.2+

Compatibility: Chrome/Firefox/Safari/Edge (last 2 versions); Mobile Safari/Chrome latest

📘 Learn More

Need formatting help? See Formatting Tips

Writing Tips for Better AI Understanding

On this page