tiennm99/ccs
1
0 Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-10-03 20:13:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(contributing): align test and UI guidance

Browse Source
This commit is contained in:
Tam Nhu Tran committed 2026-07-26 09:34:18 -04:00
1 parent 721ca5fc33
commit 1e11335348
2 files changed
+101 -85
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

tests/README.md
+65 -51
View File
@@ -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/<module>/` 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.
ui/README.md
+36 -34
View File
@@ -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.