Testing and CI

Human verified2026-11-04

A human reviewed this page, but it may be out of date. Later edits may not have been reviewed.

Overview

Choose local tests to check a change, or open the CI check pages to see what runs automatically and what each result proves. Run commands from the repository root. This page links test suites and setup for dependencies such as databases, clusters, and providers.

Test	Purpose	Location
Conformance	Unit-style domain and Driver contract checks.	`tests/conformance`
Integration	Component workflows, using fixtures or real services.	`tests/integration`
Browser	Console and docs site behavior in Chromium.	`tests/browser`
Go	CLI and other Go packages.	`cmd/` and `internal/`
Docs and test tooling	Docs site, generated references, and test helpers.	`tests/docs` and `tests/helpers`

Automatic checks and blocking failures

See CI checks and gates for what runs automatically and which failures block merge, publication, or deployment.

Requirements and credentials

Install Node.js 24.22.1 or newer, the pnpm version in package.json, the Go version in go.mod, Git, and tar:

pnpm install --frozen-lockfilepnpm cli:build

Browser tests also need Chromium; see browser setup. Real-service tests may need Docker, Kubernetes, databases, or credentials; follow their linked guides. Keep credentials outside the repository. Commands do not automatically load .env; exported variables override node --env-file values.

Quickstart

Run all test files

Start with a shell without integration opt-in variables; otherwise prepared suites can run concurrently:

pnpm test                     # Conformance and integration filespnpm cli:test                 # Gopnpm docs:install             # Browser and docs dependenciespnpm test:console-browser     # Chromiumnode --test 'tests/docs/*.test.{mjs,ts}' tests/helpers/*.test.mjs

These commands select test files, but real-service cases may skip without their prerequisites. Check the skip count and use the suite guides to run those cases. For conformance tests alone, use pnpm test:conformance.

Run one test

pnpm test:files --test-reporter=spec -- tests/conformance/contracts.test.tspnpm test:files --test-name-pattern='the Driver contract exposes' -- tests/conformance/contracts.test.ts

The second command selects one named case. test:files does not prepare fixtures or run the workspace check. Run node scripts/test-files.ts --help for options.

Integration tests

pnpm test:integration

Choose the scope you need:

Scope	What it runs	Setup and commands
Local integration tests	Component workflows in `tests/integration`; real-service cases skip unless configured.	`pnpm test:integration`; use the suite guides under Further reading for external dependencies.
Full Integration workflow	Manually selected CI lanes for databases, containers, clusters, and real providers. `all` runs every selectable lane, including `qa-matrix` and `dev-up-k3d`.	Lane coverage and hosted dispatch.
QA matrix	Agent journeys across supported installations.	Scenarios, credentials, and commands.

For real-service cases, prepare the selected suite first. Some create remote resources or send messages. Use authorized disposable resources, scope selectors to one run, and run prepared suites one at a time.

Run the hosted local installation lane

For the six dev-up-k3d cases, see local Kubernetes setup or hosted dispatch.

Results, cleanup, and troubleshooting

Check pass, failure, and skip counts; a skip is not a pass. If a case is skipped, check its selectors and prerequisites. For provider failures, check credential and model access without printing secrets. Retain failure evidence and remove only resources created by the run.