GitNexus/TESTING.md

# 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 |

## Test lanes

### `gitnexus/` commands

From `gitnexus/`:

| Command                       | What it runs                                       | When to use                           |
| ----------------------------- | -------------------------------------------------- | ------------------------------------- |
| `npm test`                    | Full suite (all 3 vitest projects)                 | Before opening a PR                   |
| `npm run typecheck:tests`     | TypeScript checks for source, tests, and helpers   | Before opening a PR                   |
| `npm run test:unit`           | Unit tests only (`test/unit/`)                     | Tight development loop                |
| `npm run test:integration`    | Integration tests (`test/integration/`)            | After changing pipelines, DB, workers |
| `npm run test:coverage`       | Full suite + v8 coverage with thresholds           | Checking coverage impact              |
| `npm run test:parity`         | Scope-resolution parity for all migrated languages | After changing resolver or scope code |
| `npm run test:cross-platform` | Platform-sensitive subset only                     | Debugging a Windows/macOS issue       |
| `npm run test:watch`          | Vitest in watch mode                               | Active development                    |

Vitest transpiles TypeScript without checking types. Run `npm run typecheck:tests`
in `gitnexus/` to check test code and helpers against the production types. This
uses `tsc --noEmit -p tsconfig.test.json`; parser input files under `test/fixtures/`
are excluded because they are sample source code, not part of the test program.

### `gitnexus-web/` commands

From `gitnexus-web/`:

| Command                 | What it runs                  | When to use                                                         |
| ----------------------- | ----------------------------- | ------------------------------------------------------------------- |
| `npm test`              | Unit/component tests (vitest) | After changing web code                                             |
| `npm run test:coverage` | Unit tests + coverage         | Checking coverage impact                                            |
| `npm run test:e2e`      | Playwright browser tests      | After changing UI flows (requires `gitnexus serve` + `npm run dev`) |

### Before opening a PR

```bash
# gitnexus-shared/dist must exist first. `npm install` / `npm run build` in
# gitnexus/ compiles it via parent `lib/tsc.js` (do not npm ci gitnexus-shared).
cd gitnexus && npx tsc --noEmit && npm run typecheck:tests && npm test
cd ../gitnexus-web && npx tsc -b --noEmit && npm test
```

## Pre-commit hook

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

1. **Formatting** — `lint-staged` runs prettier on staged files
2. **`gitnexus-web/` files staged** → `tsc -b --noEmit`
3. **`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).

## Vitest projects

`gitnexus/vitest.config.ts` defines three projects for safety isolation:

| Project   | Files                                              | Parallelism | Purpose                                             |
| --------- | -------------------------------------------------- | ----------- | --------------------------------------------------- |
| `lbug-db` | Native LadybugDB integration tests (explicit list) | Sequential  | Prevents file-lock conflicts from native mmap addon |
| `cli-e2e` | `skills-e2e.test.ts`                               | Sequential  | CLI process spawning requires serial execution      |
| `default` | Everything else                                    | Parallel    | Fast execution for pure logic and parser tests      |

When adding a new test that uses native LadybugDB (`@ladybugdb/core`), add it to the `lbug-db` project's explicit include list and the `default` project's exclude list.

## 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`.
- **Resolver / parity** — Language-specific call-resolution tests in `test/integration/resolvers/`.
- **E2E (web)** — Critical user paths only; prefer `data-testid` attributes for stable selectors. Tests run against real backend (`gitnexus serve`) and Vite dev server.

## Scope-resolution tests

Every language resolves calls and inheritance through the scope-resolution pipeline — the legacy call-resolution DAG and the per-language `REGISTRY_PRIMARY_<LANG>` flag were removed in RING4-1 (#942). Each language's resolver test lives at `test/integration/resolvers/<slug>.test.ts` and runs once, on the single scope-resolution path, as part of the normal `tests` job (`vitest test/**/*.test.ts`).

Adding a language: register its `ScopeResolver` in `scope-resolution/pipeline/registry.ts` (`SCOPE_RESOLVERS`) and add the resolver test file — no workflow or config edit needed.

## Cross-platform testing

Windows and macOS CI runs only the platform-sensitive test subset (~50 files out of 373). The full suite runs on Ubuntu.

The subset is defined in `gitnexus/scripts/cross-platform-tests.ts` and includes:

- **Platform-specific logic** — tests with `process.platform` guards, path.sep behavior, EPERM/EBUSY error classification
- **Native LadybugDB** — all `lbug-*` integration tests (N-API addon with known platform-varying behavior)
- **Process spawning / CLI** — tests using real `child_process.spawn`, shell quoting, CLI invocations
- **Worker threads** — tests spawning real `worker_threads`
- **Native addon loading** — tree-sitter grammar loading smoke tests
- **Filesystem behavior** — CRLF handling, directory walking, symlinks

When adding a platform-sensitive test, add it to the appropriate section in `scripts/cross-platform-tests.ts`.

### Confirming no tests are orphaned

Every test file matches one of the three vitest projects. To verify:

```bash
cd gitnexus
npx vitest list 2>/dev/null | wc -l  # should match total test count
```

To check the cross-platform list is up to date, run `npm run test:cross-platform` — it fails fast if any listed file is missing.

## CI integration

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

| Workflow              | Jobs                                                              | Purpose                                                               |
| --------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------- |
| `ci-quality.yml`      | format, lint, typecheck, typecheck-web, workflow-convention       | Code quality gates                                                    |
| `ci-tests.yml`        | ubuntu/coverage, cross-platform (Win/Mac), packaged-install-smoke | Full suite + coverage on Ubuntu; platform-sensitive subset on Win/Mac |
| `ci-scope-parity.yml` | discover, parity                                                  | Scope-resolution parity for all migrated languages                    |
| `ci-e2e.yml`          | e2e (chromium)                                                    | Playwright E2E, gated on `gitnexus-web/**` changes                    |

The `CI Gate` job in `ci.yml` requires the quality and test workflows to pass.
The browser E2E workflow must pass or be skipped because no web files changed.

Branch protection also requires six platform check names from the former
three-shard matrix. These names remain as aggregate gates: all native shards
and the `every test executed` audit must succeed before any of them passes.
Failed, cancelled, skipped, or missing dependency results fail these gates.
The actual native tests run in the current Windows/macOS shard matrix.

The `typecheck` job runs both the production compiler check and
`npm run typecheck:tests`. A type error in either check fails the job and the CI gate.

### Complete execution, including platform and benchmark tests

The required `every test executed` job reconciles execution receipts from Ubuntu
coverage, every Windows/macOS shard, the serial benchmark run, and the real Python
workflow preflight. It requires a recorded pass for every collected test. A skip
on Linux is satisfied only by a pass of that exact test in another required job.
Test identities include the file, suite/title and source location; ambiguous
parameterized cases must have unique titles. Missing receipts, missing test files,
unhandled runner errors, failed hooks, failed assertions, and tests with no pass
all fail the gate. Web tests are checked separately with the same rules.

The locked pytest suite and Linux/Windows containment jobs also upload JUnit
receipts. The same gate checks every Python test file was collected and every
case passed in at least one job, while preserving failures from any job. The
Linux containment job supplies Bubblewrap, the pinned CLI, and built Vitest
dependencies for tests that cannot run in the basic Python job. Python results
are included in the combined PR report.

The PR report shows the reconciled result as **Unverified**. Zero means every test
has execution evidence; individual OS logs still show tests that require another
OS as skipped. Failed executions remain failures even if another job passes.

`npm run test:benchmarks` discovers all tests gated by `GITNEXUS_BENCH` and runs
them serially. Keep timing measurements out of parallel coverage workers. The
`eval-tests` job installs the locked Python dependencies and runs the workflow
preflight Vitest tests as well as pytest; those tests must exercise real Python
validation, never a stubbed success.

## 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

## 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.