EasyPlatform Test Specifications Documentation

Generate comprehensive test specifications following EasyPlatform conventions with Given-When-Then format and code evidence.

Output Structure

All test specifications MUST be placed in the correct folder structure:

docs/
└── test-specs/
    ├── README.md                     # Master index with format spec
    ├── PRIORITY-INDEX.md             # All tests organized by P0-P3
    ├── INTEGRATION-TESTS.md          # Cross-module test scenarios
    ├── VERIFICATION-REPORT.md        # Test verification status
    └── {Module}/
        └── README.md                 # Module test specifications

Module Codes & Naming Convention

Test Case ID Format

TC-[MODULE]-[FEATURE]-[NUM]

Examples:

• TC-TXT-SNP-001 = TextSnippet > Snippet > Test 001
• TC-TXT-CAT-001 = TextSnippet > Category > Test 001
• TC-ACC-AUTH-001 = Accounts > Authentication > Test 001

Module Codes

Feature Codes (Common)

Priority Classification

Priority Guidelines

• P0: If this fails, users cannot work or data is at risk
• P1: Core happy-path functionality for business operations
• P2: Features that enhance but don't block core workflows
• P3: Nice-to-have polish and non-critical features

Phase 1: Context Gathering

Step 1.1: Identify Target Module

Determine module from:

1. User specifies module/feature
2. Feature domain implies module
3. Search codebase for related code

Step 1.2: Read Existing Test Specs

Before creating new specs:

1. Read docs/test-specs/README.md (format reference)
2. Read docs/test-specs/{Module}/README.md (if exists)
3. Read docs/test-specs/PRIORITY-INDEX.md (avoid duplicate IDs)
4. Identify existing test case IDs to continue numbering

Step 1.3: Code Evidence Gathering

For each test case, gather evidence from:

• Validation logic: Command Validate() methods
• Business rules: Entity methods, domain services
• Authorization: Controller [PlatformAuthorize] attributes
• Edge cases: Conditional logic in handlers

Phase 2: Test Specification Template

Template: Module Test Specs (README.md)

Reference: docs/test-specs/{Module}/README.md

# {Module} - Comprehensive Test Specifications

**Module**: {Module} ([Description])
**Generated**: {Date}
**Coverage**: [Feature list]

---

## Table of Contents

1. [Feature 1 Test Specs](#1-feature-1-test-specs)
2. [Feature 2 Test Specs](#2-feature-2-test-specs)
...

---

## 1. [Feature Name] Test Specs

### 1.1 [Sub-Feature] Tests

#### TC-{MOD}-{FEAT}-001: [Descriptive Test Name]

**Priority**: P0-Critical | P1-High | P2-Medium | P3-Low

**Preconditions**:
- User has `{Policy}` authorization
- Company has active {Feature} subscription
- [Other setup requirements]

**Test Steps** (Given-When-Then):
```gherkin
Given [initial context/state]
  And [additional context if needed]
When [action performed]
  And [additional action if needed]
Then [expected outcome]
  And [additional verification]

Acceptance Criteria:

• ✅ [Expected success behavior]
• ✅ [Another success case]
• ❌ [Expected failure behavior]
• ❌ [Another failure case]

Test Data:

{
  "field": "value",
  "required": true
}

Edge Cases:

• ❌ [Boundary condition 1] → [Expected error]
• ❌ [Boundary condition 2] → [Expected error]
• ✅ [Edge case that should succeed] → Success

Evidence:

• Controller: {Module}.Service/Controllers/{Controller}.cs:L{lines}

  • Authorization: {Policies}
  • Endpoint: {Method} /api/{path}

• Command Handler: {Module}.Application/UseCaseCommands/{Feature}/{Command}.cs:L{lines}

// {File}:L{lines}
[actual code snippet]

Related Files:

TC-{MOD}-{FEAT}-002: [Next Test Name]

[Continue with same format...]

Cross-Module Integration Tests

See INTEGRATION-TESTS.md for cross-module scenarios.

Related Documentation

• Business Features: docs/business-features/{Module}/README.md
• Backend Patterns: docs/claude/backend-patterns.md

Last Updated: {Date}

---

## Test Case Writing Guidelines

### Given-When-Then Best Practices

```gherkin
# GOOD - Specific and actionable
Given user is authenticated with EmployeePolicy role
  And company subscription includes Goal feature
  And goal creation form is displayed
When user fills required fields:
  - Title: "Reduce churn by 15%"
  - GoalType: "Smart"
  - TargetDate: "2025-12-31"
  And user clicks Submit
Then goal is created with status "Draft"
  And success notification is displayed
  And goal appears in dashboard list

# BAD - Vague and unmeasurable
Given user is logged in
When user creates a goal
Then it works

Acceptance Criteria Format

**Acceptance Criteria**:
- ✅ Form validates all required fields (Title, GoalType, TargetDate)
- ✅ Backend creates Goal entity in database
- ✅ Goal assigned to current employee as owner
- ✅ Notification event triggered via entity event handler
- ❌ External users cannot create goals (returns validation error)
- ❌ Missing required fields shows validation error
- ❌ Invalid date range shows "Target date must be after start date"

Evidence Requirements

Every test case MUST include:

1. Controller reference: File path + line numbers + authorization policies
2. Handler/Command reference: File path + line numbers for business logic
3. Code snippet: Actual code in <details> block for key validation/logic
4. Related files table: All relevant source files

Phase 3: Index Updates

After creating/updating test specs:

Update PRIORITY-INDEX.md

Add new test cases to appropriate priority section:

### P0 - Critical

| ID | Module | Feature | Test Name |
|----|--------|---------|-----------|
| TC-TXT-GOL-001 | TextSnippet | Goal | Create SMART Goal Successfully |
| TC-{NEW-ID} | {Module} | {Feature} | {Test Name} |

Update Module Section in README.md

Ensure master test-specs README.md links to module:

| **[{Module}](./{Module}/README.md)** | {Description} | {Feature list} | P1: {Focus} |

Anti-Hallucination Protocols

EVIDENCE_CHAIN_VALIDATION

• Every test case MUST reference actual source code
• Read validation logic before writing acceptance criteria
• Verify authorization policies from controller attributes
• Never assume behavior without code evidence

LINE_NUMBER_ACCURACY

• Always verify line numbers are current
• Use Grep to find exact locations
• Include code snippets for complex logic

TEST_ID_UNIQUENESS

• Read PRIORITY-INDEX.md before assigning new IDs
• Continue numbering sequence within feature
• Never duplicate existing TC-XXX-XXX-NNN IDs

Quality Checklist

• Test case IDs follow TC-[MODULE]-[FEATURE]-[NUM] format
• All IDs are unique (verified against PRIORITY-INDEX.md)
• Priority assigned based on classification guidelines
• Given-When-Then format used for all test steps
• Acceptance criteria include both ✅ success and ❌ failure cases
• Test data examples provided in JSON format
• Edge cases documented with expected outcomes
• Code evidence with file paths and line numbers
• Code snippets in <details> blocks for key logic
• Related files table with all layers (Backend/Frontend)
• PRIORITY-INDEX.md updated with new test cases
• Links to business-features docs included

Example: Complete Test Case

#### TC-TXT-SNP-001: Create Text Snippet Successfully

**Priority**: P1-High

**Preconditions**:
- User has `UserPolicy` authorization
- User is authenticated with valid session
- Category exists in the system

**Test Steps** (Given-When-Then):
```gherkin
Given user is authenticated with UserPolicy role
  And snippet creation form is displayed
  And category "Development" exists
When user fills required fields:
  - Title: "Docker Compose Example"
  - Content: "version: '3.8'\nservices:..."
  - Category: "Development"
  And user clicks Save
Then snippet is created with status "Active"
  And success notification is displayed
  And snippet appears in the list

Acceptance Criteria:

• ✅ Snippet created with title, content, category
• ✅ Snippet assigned to current user as owner
• ✅ Created date and modified date set
• ✅ Snippet visible in user's snippet list
• ❌ Missing required fields shows validation error
• ❌ Invalid category returns "Category not found"
• ❌ Duplicate title in same category returns "Title already exists"

Test Data:

{
  "title": "Docker Compose Example",
  "content": "version: '3.8'\nservices:...",
  "categoryId": "cat-12345",
  "tags": ["docker", "devops"]
}

Edge Cases:

• ❌ Empty title → Validation error
• ❌ Content > max length → Validation error
• ✅ Content with special characters → Success
• ❌ Invalid categoryId → Validation error

Evidence:

• Controller: PlatformExampleApp.TextSnippet.Api/Controllers/TextSnippetController.cs:L25-28

  • Authorization: UserPolicy
  • Endpoint: POST /api/TextSnippet

• Command Handler: PlatformExampleApp.TextSnippet.Application/UseCaseCommands/TextSnippet/SaveTextSnippetCommand.cs:L45-89

// SaveTextSnippetCommandHandler.cs:L52-58
return await requestSelfValidation
    .AndAsync(
        r => categoryRepository.AnyAsync(c =>
            c.Id == r.CategoryId),
        "Category not found"
    );

Related Files: