Writing Clear Acceptance Criteria | BDD Format Guide
Write acceptance criteria that eliminate ambiguity. Learn Given-When-Then, checklist, and rules formats. GitScrum stores criteria in task checklists.
7 min read
Acceptance criteria define when a user story is complete. Clear criteria prevent "I thought it meant..." conversations, reduce rework, and help testers know what to verify. Good acceptance criteria are specific, testable, and agreed upon before development starts.
Criteria Formats
| Format | Best For | Example |
|---|---|---|
| Given-When-Then | Behavior scenarios | Login flows |
| Checklist | Simple features | Form fields |
| Rules | Constraints | Validation |
Given-When-Then
Scenario Format
GIVEN-WHEN-THEN FORMAT
══════════════════════
STRUCTURE:
─────────────────────────────────────
GIVEN: Starting state/context
WHEN: Action taken
THEN: Expected outcome
EXAMPLE - Login:
─────────────────────────────────────
Story: As a user, I want to log in
so I can access my account.
Criteria:
GIVEN a registered user
WHEN they enter valid email and password
THEN they are logged in and see dashboard
GIVEN a registered user
WHEN they enter wrong password
THEN they see "Invalid credentials" error
AND they remain on login page
GIVEN a registered user
WHEN they enter wrong password 5 times
THEN their account is locked for 15 minutes
AND they see lockout message
GIVEN a user on login page
WHEN they click "Forgot password"
THEN they see password reset form
BENEFITS:
─────────────────────────────────────
├── Behavior-focused
├── Easy to convert to tests
├── Covers happy and sad paths
├── Clear cause and effect
├── Reduces ambiguity
└── QA can automate directly
Writing Good Scenarios
SCENARIO BEST PRACTICES
═══════════════════════
SPECIFIC OUTCOMES:
─────────────────────────────────────
❌ Vague:
THEN the user is notified
✅ Specific:
THEN user sees toast: "Payment successful"
AND confirmation email is sent
AND order appears in order history
COVER EDGE CASES:
─────────────────────────────────────
Don't just write happy path.
Ask: What could go wrong?
├── Invalid input
├── Empty state
├── Network error
├── Permission denied
├── Concurrent access
├── Boundary values
└── Each deserves scenario
EXAMPLE - FILE UPLOAD:
─────────────────────────────────────
Happy path:
GIVEN user on upload page
WHEN they select valid PDF under 10MB
THEN file uploads successfully
AND filename appears in list
Edge cases:
GIVEN user selects file over 10MB
WHEN they click upload
THEN they see "File too large" error
AND upload does not proceed
GIVEN user selects .exe file
WHEN they click upload
THEN they see "Invalid file type" error
GIVEN upload is in progress
WHEN network disconnects
THEN they see "Upload failed. Retry?"
AND can retry without reselecting file
Checklist Format
Simple Requirements
CHECKLIST FORMAT
════════════════
WHEN TO USE:
─────────────────────────────────────
├── Simple features
├── CRUD operations
├── Form requirements
├── When scenarios are overkill
└── Quick validation list
STRUCTURE:
─────────────────────────────────────
☐ Requirement 1
☐ Requirement 2
☐ Requirement 3
...
EXAMPLE - USER PROFILE:
─────────────────────────────────────
Story: As a user, I want to edit my profile.
Acceptance Criteria:
☐ Display name field (max 50 chars)
☐ Bio field (max 500 chars)
☐ Avatar upload (JPEG/PNG, max 2MB)
☐ Save button updates profile
☐ Success message on save
☐ Cancel discards changes
☐ Validation errors shown inline
☐ Profile URL shows updated info
EXAMPLE - SEARCH:
─────────────────────────────────────
Story: As a user, I want to search products.
Acceptance Criteria:
☐ Search input in header
☐ Minimum 2 characters to search
☐ Results update as user types (debounced)
☐ Show "No results" for empty results
☐ Results show: image, name, price
☐ Click result goes to product page
☐ Clear button resets search
☐ Search term highlighted in results
Rules-Based Criteria
Business Constraints
RULES FORMAT
════════════
WHEN TO USE:
─────────────────────────────────────
├── Business rules
├── Validation logic
├── Calculations
├── Constraints
└── Regulatory requirements
STRUCTURE:
─────────────────────────────────────
Rule 1: [condition] → [behavior]
Rule 2: [condition] → [behavior]
...
EXAMPLE - PRICING:
─────────────────────────────────────
Story: As a customer, I want accurate pricing.
Rules:
1. Base price × quantity = subtotal
2. Orders > $100 get free shipping
3. Premium members get 10% discount
4. Discount applies before shipping
5. Sales tax applies based on state
6. Tax calculated on (subtotal - discount)
7. Minimum order: $5
EXAMPLE - PASSWORD:
─────────────────────────────────────
Story: As a user, I want secure passwords.
Rules:
1. Minimum 8 characters
2. Must contain uppercase letter
3. Must contain lowercase letter
4. Must contain number
5. Must contain special character (!@#$%^&*)
6. Cannot contain username
7. Cannot match last 5 passwords
8. Show strength indicator as user types
Writing Process
Collaborative Refinement
ACCEPTANCE CRITERIA PROCESS
═══════════════════════════
STEP 1: PO DRAFTS
─────────────────────────────────────
Product Owner writes initial criteria.
├── Based on requirements
├── User perspective
├── Main scenarios
├── Known constraints
└── Draft, not final
STEP 2: TEAM REVIEWS
─────────────────────────────────────
In grooming session:
├── Developers review for feasibility
├── QA reviews for testability
├── Questions surface gaps
├── Edge cases added
└── Refinement discussion
Questions to ask:
├── "What if the user does X?"
├── "What happens when Y fails?"
├── "Is this testable as written?"
├── "What's the boundary here?"
├── "How do we know this works?"
└── Challenge assumptions
STEP 3: AGREEMENT
─────────────────────────────────────
Team agrees on final criteria.
├── Everyone understands meaning
├── PO confirms intent
├── Developers can build
├── QA can verify
└── Documented in story
STEP 4: REFERENCE
─────────────────────────────────────
During development:
├── Build to criteria
├── Test against criteria
├── Demo matches criteria
├── Done when criteria pass
└── Source of truth
Common Mistakes
What to Avoid
ACCEPTANCE CRITERIA ANTI-PATTERNS
═════════════════════════════════
VAGUE CRITERIA:
─────────────────────────────────────
❌ "System should be fast"
❌ "User gets feedback"
❌ "Data is displayed nicely"
❌ "Works on mobile"
✅ "Page loads in < 2 seconds"
✅ "Toast notification for 3 seconds"
✅ "Table with sortable columns"
✅ "Responsive down to 375px width"
TOO DETAILED:
─────────────────────────────────────
❌ "Button is #238636 with 4px radius"
❌ "Use React useState for form"
This is implementation, not criteria.
Let developers decide how.
TOO FEW:
─────────────────────────────────────
❌ "User can create account"
Missing: Validation? Error handling?
Email confirmation? Password rules?
Ask: "What else must work?"
UNTESTABLE:
─────────────────────────────────────
❌ "User experience is good"
❌ "System is secure"
❌ "Performance is acceptable"
How do you verify? If you can't test,
you can't know it's done.
NOT AGREED:
─────────────────────────────────────
❌ PO writes, team never sees
❌ Different interpretations
❌ Arguments at demo time
Everyone must agree before building.
GitScrum Integration
Storing Criteria
ACCEPTANCE CRITERIA IN GITSCRUM
═══════════════════════════════
TASK DESCRIPTION:
─────────────────────────────────────
Story: As a user, I want to...
Acceptance Criteria:
☐ Criterion 1
☐ Criterion 2
☐ Criterion 3
[Markdown formatting supported]
CHECKLIST FEATURE:
─────────────────────────────────────
Task → Checklist
├── Add criteria as checklist items
├── Check off during development
├── Progress visible
├── Done when all checked
└── Visual completion indicator
CUSTOM FIELD:
─────────────────────────────────────
Custom field: "Acceptance Criteria"
├── Text area for criteria
├── Visible in task detail
├── Template available
└── Consistent location
VERIFICATION:
─────────────────────────────────────
During code review / QA:
├── Reference criteria
├── Verify each point
├── Comments if issues
├── Complete when verified
└── Criteria = checklist
Best Practices
For Acceptance Criteria
Anti-Patterns
CRITERIA MISTAKES:
✗ Vague language
✗ Too implementation-focused
✗ Only happy path
✗ Not reviewed by team
✗ Changed during development
✗ Too few or too many
✗ Untestable conditions
✗ Written after development