spec-writing-tests
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.
When & Why to Use This Skill
This Claude skill streamlines the transition from requirements to implementation by generating structured test scenarios using the Given-When-Then (BDD) format. It ensures high-quality technical specifications by mapping unit and integration tests directly to acceptance criteria, preventing redundancy and ensuring 100% coverage for complex software features.
Use Cases
- Technical Specification Authoring: Automatically generate implementation-ready test requirements for new features, ensuring developers have a clear roadmap for coding.
- BDD Framework Standardization: Establish a consistent 'Given-When-Then' naming convention across the codebase to improve readability and collaboration between technical and non-technical stakeholders.
- Acceptance Criteria Mapping: Audit feature documentation to ensure every business requirement is validated by at least one specific unit or integration test scenario.
- API & Integration Testing: Define comprehensive test cases for API endpoints, including authentication, multi-tenancy isolation, and HTTP status code validation based on OpenAPI specs.
- Architecture Layer Validation: Create specific test scenarios for different layers (Domain, Application, Service) to maintain Clean Architecture principles and data integrity.
| 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