testing-and-quality

Testing Conventions & Quality Checklist

Progressive Testing

During development, use npm run test:dev instead of npm test. This runs:

1. Affected tests — tests co-located with files you've changed (uncommitted + staged)
2. Smoke tests — a small set of critical-path tests that always run

The full suite (npm test) runs in CI on every PR. Only run it locally if you suspect wide-reaching breakage.

Command	When to use
npm run test:dev	Default for development — fast, targeted
npm run test:dev -- --list	Dry run — see which files would run
npm run test:smoke	Smoke tests only
npm test	Full suite — CI runs this, rarely needed locally
npx vitest run path/to/file.test.ts	Run a single specific test file

Smoke tests are defined in scripts/test-dev.ts (the SMOKE_TESTS array). Keep the list small (~4-6 files).

Test Configuration

Tests use Vitest with two project configs in vitest.config.ts:

• Server tests (src/server/**/*.test.ts) — Node environment
• Client tests (src/client/**/*.test.{ts,tsx}) — jsdom environment with React Testing Library

Server Tests

• Use temp directories (fs.mkdtempSync) cleaned up in afterEach with fs.rmSync(tmpDir, { recursive: true, force: true }).
• A server test starts with no credential configured. server-test-setup.ts strips every catalogue storageEnv name and every SHIPIT_CREDENTIAL_* variable — eagerly, and again before every test. That covers both sources: the ambient environment (a session container exports the user's real keys into the test process, a CI runner has none — the divergence is invisible in CI, which is why test-env-hermeticity.test.ts pins it against an injected sentinel), and the suite's own writes (storing a credential through the API assigns its mode's variable in-process, so it would otherwise leak into the next test in the file). A test that wants a credential sets it per test or with vi.stubEnv — not in beforeAll, which the strip runs after.
• A shipit.yaml fixture that does not parse fails the test that wrote it. server-test-setup.ts installs a write hook (shared/shipit-config-test-guard.ts) that validates any file named shipit.yaml with the product's own parser. The reason is that every opportunistic reader — classifyEmptyDepDirs, staleDepDirs, computeDepsHash, warnOnSkippedInstallOutput — deliberately catches a ShipitConfigError and returns a conservative empty result, so a malformed fixture makes the check under test evaluate nothing while the assertion still passes. Three dep-dir tests were green that way (planning#480). The classic trap: YAML parses a bare true as a BOOLEAN, so an install command must be quoted — - "true", never - true. A test that writes an invalid config on purpose wraps the write in expectInvalidShipitConfig(() => ...), which is also the readable marker that the invalidity is the point.
• Testability is built in. Store-backed managers take a DatabaseManager — SessionManager(dbManager), UsageManager(dbManager), RepoStore(dbManager) — so a test passes an isolated database rather than a temp file path. Filesystem-backed ones still take a directory: GitManager(workspaceDir?). (The older sessionsFile? / usageFile? / ThreadManager / DeploymentStore signatures are gone — persistence moved to SQLite.)