Acceptance Test Skill Skill

Acceptance Test Skill

This skill defines how to write acceptance tests and scenarios that validate end-to-end feature behavior.

When to Write Acceptance Tests

Write acceptance tests when the feature requires end-to-end testing across multiple modules or external dependencies.

Testing complete user workflows that involve external APIs, databases, or services
Verifying business requirements are satisfied across module boundaries
Testing features that span multiple units within the feature
When a test requires mocking dependencies, it should be an acceptance test

If the feature only involves isolated logic within a single module, use unit tests instead.

Scenarios in spec.yaml

Scenarios live in the scenarios section of spec.yaml. Only add scenarios when the feature requires end-to-end testing with other modules. Ask the user if scenarios apply before adding them.

scenarios:
  - name: Descriptive scenario name
    given: Setup/preconditions
    when: User action/trigger
    then: Expected outcome/verification

Describe WHAT, not HOW:

Focus on user behavior and system outcomes
Avoid implementation details (field names, status codes, internal states)
Describe the value and intent, not the mechanics
Keep scenarios at a high level of abstraction

Cover end-to-end flows:

Start with user perspective
Verify final state

Acceptance Test Structure

Acceptance tests follow the Given/When/Then pattern from scenarios:

Given — Setup/preconditions
When — User action/trigger
Then — Expected outcome/verification

Each acceptance test should map to a scenario in spec.yaml.

Acceptance Tests vs Unit Tests vs Integration Tests

Unit Tests:

Test individual functions/classes in isolation
Fast, focused, and run frequently
Marked with test: unit in spec.yaml

Acceptance Tests:

Test complete features from a user/business perspective
Verify requirements are met end-to-end within a feature
Test scenarios from the spec (Given/When/Then)
May involve multiple units working together
Marked with test: acceptance in spec.yaml

Integration Tests:

Test interactions between multiple modules or external systems
Use sparingly and only for tactical purposes
Located in tests/ directory at project root

Test hierarchy: Default to unit tests. Use acceptance tests when you need end-to-end feature validation. Use integration tests sparingly for tactical external integration needs.

Updating spec.yaml Markers

After writing acceptance test that passes: test: to-implement → test: acceptance
After code passes acceptance test: code: to-implement → code: done
When acceptance test passes, mark related unit-tested features as implemented: code: to-implement → code: done

Agent Skills: Acceptance Test Skill

Install this agent skill to your local

Skill Files