how to contribute testing

Testing

Tests are written with Vitest per package. Run tests from the package root, never npm test at the repo root (which is a forbidden validation command; it runs npm run build and npm run dev too). npm run check does not run tests.

Running package tests

From a package root, run a single test file:

cd packages/coding-agent
npx tsx ../../node_modules/vitest/dist/cli.js --run test/specific.test.ts

Run the full suite for a package with npm test from inside that package directory. If you create or modify a test file, you must run that file and iterate until it passes.

Coding agent suite harness

Tests under packages/coding-agent/test/suite/ use packages/coding-agent/test/suite/harness.ts plus the faux provider. Do not use real provider APIs, real API keys, or paid tokens in these tests.

Issue-specific regressions go under packages/coding-agent/test/suite/regressions/ and are named <issue-number>-<short-slug>.test.ts, for example packages/coding-agent/test/suite/regressions/502-unified-session-view.test.ts.

Web tests

The web/ pnpm workspace has its own test commands:

pnpm --dir web test                                             # all web unit tests
pnpm --dir web --filter @prime-agent/web test:e2e               # Playwright end-to-end

@prime-agent/web runs vitest run for unit tests and playwright test for e2e. Rendering checks for the web design package run message-turn-identity and OpenUI render checks via npm run check:rendering at the repo root.

Python runtime

prime-agent-runtime/ is the IPython kernel shim. Its tests run with pytest from prime-agent-runtime/test. The runtime requires Python >= 3.10.

What CI runs

.github/workflows/ci.yml runs three jobs on pull requests to main and pushes to main:

• Build and check: npm ci, pnpm install --dir web, npm run build, then npm run check.
• Test: a matrix over packages/agent, packages/ai, and packages/tui (each npm test), plus the coding-agent suites. packages/coding-agent tests are sharded with npm run test:ci -- --shard=1/3, --shard=2/3, --shard=3/3, followed by the process smoke suite (npm run test:process) and the kernel suite (npm run test:kernel). Coding-agent jobs install uv for the kernel runtime.
• Web: npm ci, pnpm install --dir web, npm run build, then npm run test:web.

A final build-check-test job verifies all three preceding jobs succeeded.

Related pages

• Debugging, reproducing failures with the faux provider
• How to contribute, definition of done
• Patterns and conventions, testing rules in AGENTS.md
• Getting started, build and test commands