Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The CCS project employs a multi-layered testing strategy designed to ensure the reliability of its CLI runtime, dashboard UI, and infrastructure. The strategy spans from isolated module-level unit tests to complex end-to-end (E2E) integration scenarios, emphasizing platform consistency across Unix and Windows environments.
Sources: tests/README.md:1-25, CONTRIBUTING.md:20-35
Test Hierarchy and Organization
The test suite is organized into specific categories based on the scope and technology stack being validated.
| Category | Location | Description |
|---|---|---|
| Unit Tests | tests/unit/ | Focused logic tests for individual modules (Mocha/Bun). |
| Integration Tests | tests/integration/ | Cross-module behavior and automated smoke coverage. |
| NPM Tests | tests/npm/ | Packaging checks and postinstall behavior. |
| Native Tests | tests/native/ | Shell and platform coverage for installation scripts. |
| UI Tests | ui/src/ | React dashboard validation using Bun. |
Sources: tests/README.md:3-17, CONTRIBUTING.md:25-30
Test Execution Flow
The following diagram illustrates the progression of testing from local developer gates to CI/CD release signals.
Unit Testing Strategy
Unit tests focus on isolated logic within the TypeScript/Bun CLI and web server components. They leverage mocks for filesystem and network operations to ensure speed and isolation.
Key Validation Areas:
- Update Logic: Validating version comparisons (e.g., comparing
5.0.2with5.1.0-dev.3), beta channel logic, and NPM registry fetching. - Command Parity: Ensuring
--helpoutput remains within line budgets and documents all visible root commands. - Web Services: Testing the
codex-dashboard-servicefor config parsing, diagnostics, and structured patching ofconfig.toml. - Auth Resources: Managing profile-local resource links and repair idempotency for shared agent/skill directories.
Sources: tests/unit/utils/update-checker-beta-channel.test.js:15-50, tests/unit/commands/help-command-parity.test.ts:25-45, tests/unit/web-server/codex-dashboard-service.test.ts:70-100, tests/unit/codex-auth/codex-profile-resources.test.ts:35-60
Integration and UX Testing
Integration tests verify scenarios that exercise multiple layers of the system, including process lifecycles and user experience improvements.
CLI UX Integration
A dedicated Bash script (ux-integration-test.sh) validates "6 phases" of CLI improvements, focusing on user interaction and output consistency.
Infrastructure and Workflow Testing
The project includes specific tests to enforce infrastructure policies, such as the Self-Hosted Runner Policy. These tests ensure that active workflows target specific local runners (e.g., linux, x64) and that PR checkouts are gated to trusted authors (Collaborators, Members, Owners).
Sources: tests/unit/scripts/github/self-hosted-runner-policy.test.ts:20-60
Environment Isolation and Safety
A critical non-negotiable in the testing strategy is the protection of the user's real configuration data.
- Isolation: Tests MUST NOT touch
~/.ccs/or~/.claude/. - Mechanism: Development and testing utilize the
getCcsDir()utility, which respects theCCS_HOMEenvironment variable. - Mocking: Unit tests utilize extensive mocking of the
node:fsandhttpsmodules to simulate filesystem states and registry responses.
Sources: CONTRIBUTING.md:150-165, tests/unit/utils/update-checker-beta-channel.test.js:55-100, AGENTS.md:15-20
Validation Commands
| Command | Purpose |
|---|---|
bun run validate | Fast local gate (typecheck, lint, format, fast tests). |
bun run validate:ci-parity | Full non-E2E suite, build checks, and branch freshness. |
bun run test:native | Native Unix installation tests (Bash). |
bun run test:e2e | End-to-end routing and workflow wiring validation. |
Sources: CONTRIBUTING.md:105-125, tests/README.md:20-25
Conclusion
The CCS testing strategy ensures high code quality through a rigorous validation pipeline. By combining isolated unit tests with platform-specific native scripts and cross-module integration tests, the project maintains stability across its diverse CLI and dashboard components while protecting user environments through strict home-directory isolation.