ccs/docs/testing-requirements.md

CCS Testing Requirements & Procedures

Version: 2.1.4 Last Updated: 2025-11-03 Status: Active

Overview

This document outlines the comprehensive testing requirements and procedures for the CCS (Claude Code Switch) project. Following these guidelines ensures consistent, reliable, and cross-platform compatible releases.

Test Suite Structure

Core Test Files

Test File	Purpose	Coverage	Platforms
tests/uninstall-test.sh	Uninstall functionality validation	20 tests	Unix/Linux/macOS
tests/uninstall-test.ps1	Uninstall functionality validation	20 tests	Windows
tests/edge-cases.sh	Comprehensive edge case testing	37 tests	Unix/Linux/macOS
tests/edge-cases.ps1	Comprehensive edge case testing	37 tests	Windows

Test Categories

1. Uninstall Functionality Tests (20 tests)

File: tests/uninstall-test.sh / tests/uninstall-test.ps1

Sections:

1. Empty Uninstall (3 tests)

   • Command executes without error
   • Appropriate "nothing to uninstall" messaging
   • Reports 0 items removed correctly

2. Install/Uninstall Cycle (5 tests)

   • Clean uninstall execution
   • Removes ccs.md command file
   • Removes ccs-delegation skill directory
   • Preserves other commands (non-invasive)
   • Preserves other skills (non-invasive)

3. Idempotency (2 tests)

   • Second uninstall succeeds
   • Reports nothing found on subsequent runs

4. Output Formatting (4 tests)

   • Contains box-drawing headers
   • Shows success messages
   • Provides reinstallation instructions

5. Integration Tests (3 tests)

   • No profile errors on uninstall
   • Version command still works
   • Help command still works

6. Edge Cases (3 tests)

   • Partial installations handled
   • Missing directories handled
   • Error scenarios managed gracefully

2. Comprehensive Edge Cases (37 tests)

File: tests/edge-cases.sh / tests/edge-cases.ps1

Coverage Areas:

• Version Commands (3 tests)
• Help Commands (2 tests)
• Argument Parsing (6 tests)
• Profile Commands (4 tests)
• Error Handling (3 tests)
• Edge Cases (6 tests)
• Configuration Validation (6 tests)
• Real Usage Simulation (3 tests)
• Platform-Specific Tests (4 tests)

Testing Environment Requirements

Environment Variable Isolation

Critical Requirement: All tests must use isolated HOME directories to prevent impact on user data.

Implementation Pattern:

# Unix/Linux/macOS
HOME=/tmp/test-ccs-home ./ccs --install
HOME=/tmp/test-ccs-home ./ccs --uninstall

# Windows PowerShell
$env:HOME = "C:\temp\test-ccs-home"
.\ccs.ps1 --install
.\ccs.ps1 --uninstall

Validation Requirements:

• ✅ Install uses test directory (not ~/.claude)
• ✅ Uninstall removes files from test directory only
• ✅ Real user directories completely unaffected
• ✅ Perfect test isolation achieved

Cross-Platform Compatibility

Platform-Specific Patterns:

• Bash Version: Uses $HOME/.claude directly
• PowerShell Version: Uses HOME-first pattern with USERPROFILE fallback

PowerShell Pattern:

$HomeDir = if ($env:HOME) { $env:HOME } else { $env:USERPROFILE }

Test Execution Procedures

Prerequisites

1. Clean Test Environment

   # Remove any existing CCS installation
   rm -rf ~/.ccs ~/.local/bin/ccs
   

2. Required Tools

   • bash 3.2+ (Unix/Linux/macOS)
   • PowerShell 5.1+ (Windows)
   • Claude CLI 2.0.31+
   • jq 1.6+ (optional, for JSON validation)

Running Tests

Unix/Linux/macOS

# Navigate to CCS directory
cd /path/to/ccs

# Run uninstall tests
./tests/uninstall-test.sh

# Run edge case tests
./tests/edge-cases.sh

# Run all tests (full suite)
./tests/uninstall-test.sh && ./tests/edge-cases.sh

Windows

# Navigate to CCS directory
cd C:\path\to\ccs

# Run uninstall tests
.\tests\uninstall-test.ps1

# Run edge case tests
.\tests\edge-cases.ps1

# Run all tests (full suite)
.\tests\uninstall-test.ps1; .\tests\edge-cases.ps1

Expected Results

Success Criteria:

• Total Test Pass Rate: 100%
• Individual Test Suites: Each must pass 100%
• Environment Isolation: No impact on user data
• Cross-Platform Consistency: Identical behavior across platforms

Sample Output:

=== CCS Uninstall Test Results ===
Total Tests: 20
Passed: 20 (100%)
Failed: 0 (0%)
Status: ✅ ALL TESTS PASSED

Quality Assurance Standards

Code Quality Requirements

1. Syntax Validation

   # Bash syntax check
   bash -n ccs
   bash -n install.sh
   bash -n uninstall.sh
   
   # PowerShell syntax check
   Get-Command Test-Path -Syntax ccs.ps1
   

2. Pattern Consistency

   • HOME-first environment variable pattern
   • Consistent error handling
   • Uniform output formatting

3. Security Validation

   • No impact on user data
   • Proper file permissions
   • No unauthorized directory access

Functional Testing Requirements

1. Happy Path Testing

   • Standard operations work perfectly
   • Default behaviors function as expected
   • User workflows complete successfully

2. Edge Case Handling

   • Robust handling of unexpected inputs
   • Graceful failure modes
   • Clear error messages with actionable solutions

3. Integration Testing

   • CLI integration with all commands
   • Path operations work correctly
   • Environment variable handling is reliable

Test Coverage Metrics

Current Coverage (v2.1.4)

Test Category	Tests	Pass Rate	Status
Uninstall Functionality	20	100%	✅ Complete
Edge Cases	37	100%	✅ Complete
Cross-Platform Validation	57	100%	✅ Complete
Environment Isolation	57	100%	✅ Complete
Total Coverage	57	100%	✅ Complete

Coverage Goals for Future Releases

Metric	Target	Current Status
Test Pass Rate	>95%	100% ✅
Cross-Platform Coverage	100%	100% ✅
Edge Case Coverage	>90%	100% ✅
Environment Isolation	100%	100% ✅
Security Validation	100%	100% ✅

Automated Testing Integration

CI/CD Pipeline Requirements

Recommended Integration:

# GitHub Actions example
- name: Run CCS Tests
  run: |
    ./tests/uninstall-test.sh
    ./tests/edge-cases.sh

Test Automation Benefits:

• Consistent test execution
• Early detection of regressions
• Cross-platform validation
• Automated quality gates

Performance Testing

Test Execution Benchmarks:

• Uninstall Tests: ~15 seconds
• Edge Case Tests: ~45 seconds
• Total Suite: ~60 seconds
• Memory Usage: Minimal
• Disk I/O: Controlled and temporary

Test Maintenance Procedures

When to Update Tests

1. New Features Added

   • Add corresponding test cases
   • Update test documentation
   • Validate cross-platform compatibility

2. Bug Fixes Implemented

   • Add regression tests for fixed bugs
   • Verify fix doesn't break existing functionality
   • Update test coverage metrics

3. Platform Changes

   • Test on new platform versions
   • Update platform-specific test cases
   • Validate compatibility

Test Review Process

1. Code Review Integration

   • Tests reviewed alongside code changes
   • Ensure test coverage for new functionality
   • Validate test quality and effectiveness

2. Release Validation

   • Full test suite execution before releases
   • Cross-platform validation
   • Performance benchmarking

Troubleshooting Test Failures

Common Issues

1. Environment Variable Conflicts

   • Symptom: Tests affecting user directories
   • Solution: Verify HOME isolation pattern
   • Prevention: Always use isolated test environments

2. Permission Issues

   • Symptom: File operation failures
   • Solution: Check file permissions and paths
   • Prevention: Validate prerequisites before testing

3. Platform-Specific Failures

   • Symptom: Tests pass on one platform, fail on another
   • Solution: Review platform-specific code paths
   • Prevention: Test on all supported platforms

Debug Procedures

1. Enable Verbose Output

   # Add debug flags to test scripts
   ./tests/uninstall-test.sh --verbose
   

2. Isolate Failing Tests

   # Run individual test sections
   ./tests/uninstall-test.sh --section=empty-uninstall
   

3. Validate Environment

   # Check environment variables
   echo "HOME: $HOME"
   echo "USERPROFILE: $USERPROFILE"
   

Best Practices

Test Development Guidelines

1. Test Isolation

   • Never modify user data during tests
   • Use temporary directories for all file operations
   • Clean up all test artifacts

2. Cross-Platform Considerations

   • Test on all supported platforms
   • Use platform-agnostic patterns where possible
   • Handle platform-specific differences explicitly

3. Maintainability

   • Clear test documentation
   • Consistent test structure
   • Reusable test utilities

Continuous Improvement

1. Test Coverage Analysis

   • Regular coverage assessment
   • Identify untested code paths
   • Prioritize high-risk areas

2. Performance Monitoring

   • Track test execution times
   • Identify performance regressions
   • Optimize slow test cases

3. Quality Metrics

   • Monitor test pass rates
   • Track bug detection rates
   • Measure test effectiveness

References

Related Documentation

• Project Roadmap: /docs/project-roadmap.md
• Implementation Plans: /plans/
• Code Standards: /docs/code-standards.md
• System Architecture: /docs/system-architecture.md

Test Reports

• Uninstall Test Report: /plans/reports/241103-from-qa-engineer-to-development-team-ccs-uninstall-testing-report.md
• Code Review Reports: /plans/reports/251103-code-review-phase1-phase2.md

External Resources

• Claude CLI Documentation: https://docs.anthropic.com/claude/reference/claude-cli
• PowerShell Best Practices: https://docs.microsoft.com/en-us/powershell/scripting/dev-cross-plat/writing-portable-cmdlets

---

Maintained By: QA Engineer & Development Team Review Frequency: Monthly or after major releases Last Updated: 2025-11-03

Unresolved Questions: None Blockers: None Next Review: Post v2.1.4 release