By 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