Testing — GitNexus

How we structure tests and which commands to run locally and in CI.

Packages

Package	Path	Runner	Notes
CLI + MCP core	`gitnexus/`	Vitest	Primary test surface in CI
Web UI	`gitnexus-web/`	Vitest	Unit/component tests
Web UI E2E	`gitnexus-web/`	Playwright	Run when changing UI flows

Commands (local)

From repository root, unless noted:

gitnexus (CLI / library)

bash

cd gitnexus
npm install
npm run build
npm test                    # full suite: vitest run
npm run test:unit           # unit only: vitest run test/unit
npm run test:integration    # integration suite
npm run test:coverage
npx tsc --noEmit            # typecheck (matches CI)

gitnexus-web

bash

cd gitnexus-web
npm install
npm test                    # unit tests (vitest)
npx tsc -b --noEmit         # typecheck (matches CI)
npm run test:coverage
npm run test:e2e            # Playwright (requires gitnexus serve + npm run dev)

Pre-commit hook

A husky pre-commit hook (.husky/pre-commit) runs automatically on every git commit:

Formatting — lint-staged runs prettier on staged files
gitnexus-web/ files staged → tsc -b --noEmit
gitnexus/ files staged → tsc --noEmit

Tests do not run in the pre-commit hook — they run in CI (ci-tests.yml) only.

Skip with git commit --no-verify (use sparingly).

Test categories

Unit — Pure logic, parsers, graph/query helpers; fast; no network.
Integration — Real combinations (filesystem, MCP wiring, larger pipelines) as already organized under gitnexus/test/integration.
Eval-style / golden sets — For agent- or classification-style behavior, keep labeled inputs and expected outputs (JSON or table-driven tests) and run them in CI when relevant.
E2E (web) — Critical user paths only; prefer data-testid attributes for stable selectors. Tests run against real backend (gitnexus serve) and Vite dev server.

Performance metrics (targets)

Set targets to match team expectations, then tune to this repo’s CI reality:

Metric	Target (initial)	Notes
Unit coverage	Align with CI	CI runs Vitest with coverage in `gitnexus`
Unit wall time	Fast PR feedback	Use `vitest run test/unit` for tight loop
Integration duration	< few minutes	Guard heavy tests with env flags if needed

Regression testing

Re-run the full relevant suite when:

Prompt or agent-behavior documentation changes (if tests encode behavior)
Model or embedding-related code paths change
Graph schema, query contracts, or MCP tool shapes change
Dependencies with parsing or runtime impact upgrade

CI integration

GitHub Actions (.github/workflows/ci.yml) orchestrate:

ci-quality.yml — prettier format check, eslint lint, tsc --noEmit for gitnexus/, tsc -b --noEmit for gitnexus-web/
ci-tests.yml — vitest run with coverage (ubuntu) + cross-platform (macOS, Windows)
ci-e2e.yml — Playwright E2E tests, gated on gitnexus-web/** changes

Local checks before pushing:

bash

cd gitnexus && npx tsc --noEmit && npm test
cd ../gitnexus-web && npx tsc -b --noEmit && npm test

Or rely on the pre-commit hook which runs these automatically for staged files.

User acceptance / beta (optional)

For staged releases or UI betas: deploy to a staging environment, collect structured feedback, watch errors and latency, then iterate before a wider release.