diff --git a/tests/README.md b/tests/README.md index c5e4acf4..232058c6 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,65 +1,79 @@ # CCS Test Suite -## Organization +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. -``` -tests/ -├── unit/ # Module unit tests (Mocha) -│ ├── glmt/ # Legacy GLMT transformer/internal compatibility tests -│ └── delegation/ # Delegation module tests -├── npm/ # npm package tests (Mocha) -├── native/ # Native installation tests (bash/PowerShell) -│ ├── unix/ # Unix/Linux/macOS tests -│ └── windows/ # Windows PowerShell tests -├── integration/ # Integration + smoke tests -└── shared/ # Shared utilities - ├── fixtures/ # Test configuration and environment - ├── unit/ # Helper function tests - ├── helpers.sh # Bash test utilities - └── test-data.js # Test data for npm tests -``` +## Ownership -## Running Tests +| Area | Path | Use for | +| --- | --- | --- | +| Unit | [`unit/`](./unit/) | Focused module and command behavior | +| Integration | [`integration/`](./integration/) | Cross-module, process, proxy, auth, and web-server behavior | +| End to end | [`e2e/`](./e2e/) | Packaged CLI workflows | +| npm package | [`npm/`](./npm/) | Installation, exports, and package behavior | +| Native | [`native/`](./native/) | Unix and Windows shell behavior | +| Docker | [`docker/`](./docker/) | Compose and stable network/service contracts | +| Documentation | [`docs/`](./docs/) | Repository documentation invariants | +| Shared support | [`shared/`](./shared/) | Fixtures and helpers reused by suites | +| Mocks | [`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`](../package.json). Bucket membership +and execution live in +[`../scripts/run-test-bucket.js`](../scripts/run-test-bucket.js). ```bash -bun run test # All automated tests (unit + integration + npm) -bun run test:unit # Unit tests only -bun run test:npm # npm package tests -bun run test:native # Native Unix tests (bash) +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 ``` -## Test Categories +For the normal contributor gate: -### Unit Tests (`unit/`) -Module-level tests using Mocha framework: -- `unit/glmt/` - Legacy transformer internals kept for Cursor translation compatibility -- `unit/delegation/` - Permission mode, session manager, result formatter +```bash +bun run format +bun run lint:fix +bun run validate +``` -### npm Tests (`npm/`) -npm package functionality tests using Mocha: -- `postinstall.test.js` - Postinstall behavior -- `cli.test.js` - CLI argument parsing -- `cross-platform.test.js` - Cross-platform compatibility -- `special-commands.test.js` - Integration tests +For the closest local equivalent to PR CI: -### Native Tests (`native/`) -Installation tests for curl|bash (Unix) and irm|iex (Windows): -- `native/unix/edge-cases.sh` - Unix edge case tests -- `native/windows/edge-cases.ps1` - Windows edge case tests +```bash +bun run validate:ci-parity +``` -### Integration Tests (`integration/`) -Integration and smoke coverage for scenarios that exercise multiple layers: -- Automated `*.test.ts` files run as part of `bun run test:all` and CI -- Shell and standalone probe scripts remain on-demand for targeted debugging -- `cursor-daemon-lifecycle.test.ts` - local daemon process + HTTP smoke coverage -- `image-analyzer-hook.test.ts` - hook integration coverage -- `glmt-integration-test.sh` - legacy GLMT compatibility smoke probe -- `symlink-chain-test.sh` - Symlink chain handling -- `ux-integration-test.sh` - CLI UX integration +Dashboard tests use Vitest and are documented in +[`../ui/README.md`](../ui/README.md). -## Adding New Tests +## Test Isolation -- **Unit tests**: Add to `unit//` for isolated module behavior -- **npm tests**: Add to `npm/` for package behavior -- **Native tests**: Add to `native/unix/` or `native/windows/` -- **Integration tests**: Add automated cross-layer smoke coverage to `integration/*.test.ts` +- 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`](../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. diff --git a/ui/README.md b/ui/README.md index 5c395658..454e96c6 100644 --- a/ui/README.md +++ b/ui/README.md @@ -1,76 +1,78 @@ # CCS Dashboard UI -React + TypeScript + Vite frontend for the CCS local dashboard. - -This UI is served by the CCS web server and is accessed via: +React, TypeScript, and Vite frontend for the local dashboard served by the CCS +web server through: ```bash ccs config ``` ---- - ## Development -From project root: +From the repository root, build the server and open the integrated dashboard: ```bash bun run dev ``` -This starts the CCS server, opens a local browser URL, and prints bind/network details for the dashboard. -If the runtime bind is reachable beyond loopback, CCS also prints an auth reminder. - -For remote device access during development, run: +Pass a host explicitly when testing network access: ```bash bun run dev -- --host 0.0.0.0 -``` - -For local-only development, run: - -```bash bun run dev -- --host 127.0.0.1 ``` -From `ui/` only (frontend dev server): +For the frontend-only Vite server: ```bash cd ui bun run dev ``` ---- +Root and UI scripts are defined in +[`../package.json`](../package.json) and [`package.json`](./package.json). + +## Source Ownership + +| Area | Path | +| --- | --- | +| Route-level pages | [`src/pages/`](./src/pages/) | +| Domain and shared components | [`src/components/`](./src/components/) | +| Server-state hooks | [`src/hooks/`](./src/hooks/) | +| Cross-page context/providers | [`src/contexts/`](./src/contexts/) and [`src/providers/`](./src/providers/) | +| API, localization, catalogs, helpers | [`src/lib/`](./src/lib/) | +| UI tests | [`tests/`](./tests/) and colocated tests | + +Follow the owning domain's existing import pattern. Barrel exports are optional, +not required at every directory level. ## Quality Commands ```bash cd ui +bun run format bun run typecheck bun run lint bun run validate bun run test:run ``` ---- +`bun run validate` currently runs typecheck, lint with fixes, and the format +check. UI tests run with Vitest; use `test`, `test:run`, `test:coverage`, or +`test:ui` as defined in [`package.json`](./package.json). -## i18n +## Localization Dashboard localization uses `react-i18next`. -- Main setup: `ui/src/lib/i18n.ts` -- Locale helpers: `ui/src/lib/locales.ts` -- Language switcher: `ui/src/components/layout/language-switcher.tsx` +| Concern | Source | +| --- | --- | +| Supported locales, normalization, fallback, persistence | [`src/lib/locales.ts`](./src/lib/locales.ts) | +| i18next setup and translation resources | [`src/lib/i18n.ts`](./src/lib/i18n.ts) | +| Language switcher | [`src/components/layout/language-switcher.tsx`](./src/components/layout/language-switcher.tsx) | -For full architecture, conventions, and locale onboarding, see: - -- [`../docs/i18n-dashboard.md`](../docs/i18n-dashboard.md) - ---- - -## Notes - -- UI locale persistence uses browser localStorage key `ccs-ui-locale`. -- Current supported locales are managed in `ui/src/lib/locales.ts`. -- Current locales: `en`, `zh-CN`, `vi`. -- Fallback locale is English (`en`). +English is the fallback. The selected locale is stored in browser local storage +under `ccs-ui-locale`. Treat `src/lib/locales.ts` as the complete source of +truth for supported locale codes. When adding or removing a locale, update the +translation resources, switcher, tests, and +[dashboard i18n guide](../docs/i18n-dashboard.md) in the same change.