ccs/tests/README.md

CCS Test Suite

Root TypeScript and JavaScript tests run with Bun's test runner. Native shell, PowerShell, Docker, and standalone probes cover contracts that need a real platform or process boundary.

Ownership

Area	Path	Use for
Unit	unit/	Focused module and command behavior
Integration	integration/	Cross-module, process, proxy, auth, and web-server behavior
End to end	e2e/	Packaged CLI workflows
npm package	npm/	Installation, exports, and package behavior
Native	native/	Unix and Windows shell behavior
Docker	docker/	Compose and stable network/service contracts
Documentation	docs/	Repository documentation invariants
Shared support	shared/	Fixtures and helpers reused by suites
Mocks	mocks/	Bounded test doubles and fixtures

Some source domains also keep focused tests in src/**/__tests__/. Follow the nearest established pattern and avoid moving tests solely for taxonomy.

Commands

Commands are defined in ../package.json. Bucket membership and execution live in ../scripts/run-test-bucket.js.

bun run test:fast      # Fast Bun test bucket
bun run test:slow      # Slow Bun test bucket
bun run test:all       # All root non-e2e Bun test buckets
bun run test:unit      # tests/unit
bun run test:npm       # tests/npm
bun run test:native    # Native Unix edge-case script
bun run test:e2e       # tests/e2e with fail-fast and extended timeout
bun run test           # Build, then test:all

For the normal contributor gate:

bun run format
bun run lint:fix
bun run validate

For the closest local equivalent to PR CI:

bun run validate:ci-parity

Dashboard tests use Vitest and are documented in ../ui/README.md.

Test Isolation

• Set CCS_HOME to a temporary directory.
• Never read or modify a contributor's real ~/.ccs/ or ~/.claude/.
• Use getCcsDir() from ../src/utils/config-manager.ts for CCS paths.
• Keep fixtures deterministic and free of credentials or private account data.
• Use real behavior at the boundary under test; do not weaken assertions to hide regressions.

Adding Coverage

• Add a focused unit test for isolated logic.
• Add integration coverage when behavior crosses modules, processes, HTTP, or persistence boundaries.
• Add e2e coverage when command routing or packaged CLI behavior is the contract.
• Add native or Docker coverage only when platform/runtime behavior cannot be represented faithfully in Bun tests.
• Run the smallest relevant command first, then broaden to the contributor or CI-parity gate when shared contracts changed.