---
summary: "How to run tests locally (vitest) and when to use force/coverage modes"
read_when:
  - Running or fixing tests
title: "Tests"
---

# Tests

- Full testing kit (suites, live, Docker): [Testing](/help/testing)
- Public release gate: [Full Release Validation](/reference/full-release-validation)

- `pnpm test:fast`: runs the unit suite through `vitest.unit.config.ts`. Use
  this as the quick local gate for code that does not need Docker, live
  providers, or browser/UI coverage.
- `pnpm test:force`: clears a lingering gateway process on the default control
  port, then runs the full Vitest suite with an isolated gateway port. Use this
  when a prior gateway run left port 18789 occupied.
- `pnpm test:coverage`: runs the unit suite with V8 coverage through
  `vitest.unit.config.ts`. Global thresholds are 70% for lines, branches,
  functions, and statements. Integration-heavy entrypoints stay excluded so the
  target stays focused on unit-testable logic.
- `pnpm test` on Node 24+: Fased auto-disables Vitest `vmForks` and uses
  `forks` to avoid `ERR_VM_MODULE_LINK_FAILURE` / `module is already linked`.
  You can force behavior with `FASED_TEST_VM_FORKS=0|1`.
- `pnpm test:e2e`: runs gateway end-to-end smoke tests for multi-instance
  WS/HTTP/node pairing. Defaults to `vmForks` + adaptive workers in
  `vitest.e2e.config.ts`; tune with `FASED_E2E_WORKERS=<n>` and set
  `FASED_E2E_VERBOSE=1` for verbose logs.
- `pnpm test:ui`: Runs the Control UI test suite after the raw-window-open lint guard.
- `pnpm test:smoke:agent-flow`: runs the composite Provider -> Agent -> Skill
  -> Chat -> Task -> Memory -> Channel delivery smoke lane.
- `pnpm test:live`: runs provider live tests (minimax/zai). Requires API keys
  and `LIVE=1` or provider-specific `*_LIVE_TEST=1` to unskip.

## Local PR gate

For local PR land/gate checks, run:

- `pnpm check`
- `pnpm build`
- `pnpm test`
- `pnpm check:docs`

If `pnpm test` flakes on a loaded host, rerun once before treating it as a
regression, then isolate with `pnpm vitest run <path/to/test>`.

For memory-constrained hosts, use:

- `FASED_TEST_PROFILE=low FASED_TEST_SERIAL_GATEWAY=1 pnpm test`

## Model latency bench (local keys)

Script: [`scripts/bench-model.ts`](https://github.com/fased-ai/fased/blob/main/scripts/bench-model.ts)

Usage:

- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Optional env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Default prompt: “Reply with a single word: ok. No punctuation or extra text.”

The script prints min/median/max latency for the configured providers. Treat
local results as a point-in-time comparison; provider latency varies by account,
region, model load, and network path.

## Onboarding E2E (Docker)

Docker is optional; this is only needed for containerized onboarding smoke tests.

Full cold-start flow in a clean Linux container:

```bash
scripts/e2e/onboard-docker.sh
```

This script drives the interactive wizard through a pseudo-tty, verifies
config/workspace/session files, starts the gateway, and runs `fased health`.

## QR import smoke (Docker)

Ensures `qrcode-terminal` loads under Node 22+ in Docker:

```bash
pnpm test:docker:qr
```
