| name | spec-writing-tests |
| description | Defines test scenarios using Given-When-Then format and maps tests to acceptance criteria. Use when writing technical specifications, defining unit and integration test requirements, or ensuring test coverage for acceptance criteria. |
Test Scenarios
Define test scenarios that validate the technical implementation. Use Given-When-Then format and map tests to acceptance criteria:
## Testing Requirements
### Unit Test Scenarios
#### Domain Layer
- [ ] GivenNewEntity_WhenCreated_ThenPropertiesInitialized
- [ ] GivenEntity_WhenChecked_ThenInheritsFromCorrectBaseClass
- [List domain entity tests following project patterns]
#### Application Layer (DTO Validation)
- [ ] GivenDto_WhenRequiredFieldMissing_ThenValidationFails
- [ ] GivenDto_WhenFieldExceedsMaxLength_ThenValidationFails
- [List DTO validation tests]
### Integration Test Scenarios
#### Service Layer
- [ ] CreateEntity_WithValidData_CreatesInDatabase (validates AC: X)
- [ ] CreateEntity_SetsCorrectTenantId (validates AC: Y)
- [Map each test to relevant acceptance criteria]
#### API Endpoints
- [ ] PostEntity_WithValidData_Returns201Created (validates AC: Z)
- [ ] PostEntity_WithoutAuthentication_Returns401Unauthorized
- [Include tests for all HTTP status codes in OpenAPI spec]
#### Multi-Tenancy
- [ ] CreateEntity_InTenantA_NotVisibleToTenantB
- [ ] GetAllEntities_ReturnsOnlyCurrentTenantEntities
Test Naming Convention: Use Given{State}_When{Action}_Then{Result} format consistently throughout.
Coverage Requirement: Each acceptance criterion should be validated by at least one test scenario.
Quality Standards
Your specifications must:
- Be Complete: Address every acceptance criterion through technical implementation details
- Avoid Redundancy: Never duplicate the user story or acceptance criteria; reference them instead
- Consolidate Information: Define concepts once, reference them elsewhere (e.g., validation rules in one place)
- Be Precise: Include exact property names, data types, constraints
- Follow Conventions: Match existing codebase patterns (CLAUDE.md, .cursor/rules/)
- Be Implementation-Ready: Developer can build directly from spec
- Consider Edge Cases: Handle errors, validation, null values
- Respect Architecture: Maintain Clean Architecture layer separation
- Ensure Multi-Tenancy: Properly implement tenant isolation
- Document Decisions: Explain why choices were made
- Be Testable: Include clear testing requirements that map to acceptance criteria
- Be Maintainable: Consider long-term code health
Internal Redundancy Prevention
Avoid repeating the same information in multiple sections:
- Validation Rules: Define once in OpenAPI schema or UI component section, reference elsewhere
- Error Messages: List in one centralized location
- Navigation Flows: Choose either acceptance-criteria format OR detailed flow diagrams, not both
- Multi-Tenancy Details: Technical implementation in one section, testing implications reference it
- API Contracts: Full OpenAPI spec is sufficient; don't restate in prose
Cross-Reference Pattern: "See Validation Rules for field constraints" instead of repeating the rules.
Output Format
Your specification should be:
- Written in clear, technical markdown
- Saved to
docs/specs/{feature-name}.md
- Structured exactly as outlined above
- Complete enough for immediate implementation
- Reviewable by both technical and non-technical stakeholders
