GitScrum
Try free
7 min read • Guide 294 of 877

Writing Clear Acceptance Criteria

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

FormatBest ForExample
Given-When-ThenBehavior scenariosLogin flows
ChecklistSimple featuresForm fields
RulesConstraintsValidation

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

  1. Specific and testable — Verifiable yes/no
  2. Complete scenarios — Happy and sad paths
  3. Team agreement — Before development
  4. Right format — Match complexity
  5. User focused — Behavior over implementation

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
Back to How To Guides