Refactor testing documentation structure

[josecelano]

Parent Epic: #85

Overview

Refactor the testing documentation from a single large testing.md file (652 lines) into a well-organized testing/ folder structure with separate files for different concerns. This refactoring improves maintainability, discoverability, and sets the stage for adding new coverage documentation without mixing concerns.

Why This Matters: The current testing.md file has grown to over 650 lines and covers multiple distinct topics (unit testing, commands testing, E2E testing, pre-commit integration, etc.). Splitting this into separate focused files makes the documentation easier to navigate, maintain, and extend.

Goals

• Create docs/contributing/testing/ directory structure
• Split testing.md into focused, single-concern documents
• Create a main README.md as the testing documentation entry point
• Update all links referencing testing.md throughout the project
• Preserve all existing content without modification (pure refactoring)
• Prepare structure for adding new coverage documentation

Proposed Structure

docs/contributing/testing/
  ├── README.md                    # Main entry point, overview, and quick start
  ├── unit-testing.md              # Unit test naming, AAA pattern, parameterized tests
  ├── resource-management.md       # TempDir usage, test isolation, cleanup
  ├── testing-commands.md          # Command test patterns, builders, mocks, E2E
  ├── clock-service.md             # MockClock usage for deterministic time tests
  └── pre-commit-integration.md    # AI enforcement tests, SKIP_AI_ENFORCEMENT flag

Content Mapping

README.md (Main Entry Point)

• Overview of testing philosophy
• Quick links to specialized docs
• "Getting Started" section
• Links to related documentation

unit-testing.md

• Unit Test Naming Style (it_should_ prefix)
• Naming Convention and Examples
• Benefits section

resource-management.md

• Resource Management principles
• Key Rules (TempDir usage, avoiding production data)
• Good and bad examples

testing-commands.md

• Testing Commands section
• Command Test Patterns
• Unit Tests with Test Builders
• Mock Strategies for Commands
• Integration Tests with E2E Infrastructure
• Testing Destroy Command (all subsections)
• E2E Test Integration

clock-service.md

• Using the Clock Service for Deterministic Time Tests
• Why Use Clock Service, Production Code, Test Code examples
• Key Benefits and When to Use

pre-commit-integration.md

• Pre-commit Integration Testing
• How It Works, Skipping Expensive Tests
• Why This Approach, Running Tests
• AI Assistant Integration

Implementation Plan

Phase 1: Create Directory Structure (5 minutes)

• Create docs/contributing/testing/ directory

Phase 2: Create README.md Entry Point (20 minutes)

• Create docs/contributing/testing/README.md
• Copy overview, principles, and getting started sections
• Add "Documentation Index" with links to specialized docs

Phase 3: Create Specialized Documentation Files (60 minutes)

• unit-testing.md (lines ~5-60 from testing.md)
• resource-management.md (lines ~61-105)
• testing-commands.md (lines ~368-572)
• clock-service.md (lines ~258-367)
• pre-commit-integration.md (lines ~584-652)

Phase 4: Update Cross-References (30 minutes)

• Search project for testing.md references
• Update references in contributing docs and copilot instructions

Phase 5: Remove Old File (5 minutes)

• Delete docs/contributing/testing.md

Phase 6: Validation (20 minutes)

• Run markdown linter
• Check all links work
• Verify no content was lost

Acceptance Criteria

• docs/contributing/testing/ directory exists with 6 files total
• All content from original testing.md is preserved (no deletions)
• README.md serves as clear entry point with navigation
• Each specialized file has clear introduction and context
• All cross-references between files work correctly
• Original docs/contributing/testing.md is removed
• All markdown files pass linting
• All internal and external links work

Notes

• Pure Refactoring: This issue is ONLY about restructuring - no content changes
• Preserve Everything: All information must be retained exactly as-is
• Link Integrity: Critical to update all references to avoid broken links
• Prepare for Coverage: Sets up structure for coverage documentation in issue #TBD