Skip to content

Getting started ​

This page installs Veritas in your project, checks the environment and runs the pipeline once. For a guided example with a known bug, follow the tutorial.

Requirements ​

ItemRequirement
Node.js24 or later
Node.js for your project code25 or later (26 recommended) for property-based tests and counterexample replay, which run your functions with network access blocked
Test runnerVitest, installed in the project
LanguageTypeScript or JavaScript (ESM)
OSLinux, macOS or Windows
Optionalgit, for --since and commit metadata; Lean 4 and Lake through elan, for prove --engine lean

Z3, @mizchi/mutator and fast-check come with the package.

For property-based tests and counterexample replay, Veritas uses the Node.js it runs on, then VERITAS_SANDBOX_NODE, then node on PATH. If none of them is 25 or later, those checks do not run and their results are reported as inconclusive.

Install ​

bash
npm install -D @under18dev/veritas
bash
pnpm add -D @under18dev/veritas
bash
yarn add -D @under18dev/veritas
bash
bun add -d @under18dev/veritas

The package provides two commands, veritas and veritas-mcp. Run them through your package manager (npx veritas, pnpm exec veritas, yarn veritas, bunx veritas). Most pages in this guide write veritas for short.

To use Veritas without adding it to each project, install it globally:

bash
npm install -g @under18dev/veritas

This puts veritas and veritas-mcp on your PATH. When you run it in a project, Vitest, @mizchi/mutator and fast-check are taken from the project if it has them installed. If your tests use a test environment such as happy-dom or jsdom, or Vitest plugins, add @mizchi/mutator to the project too (npm install -D @mizchi/mutator): the copy that comes with Veritas runs the tests with its own Vitest, which cannot load them.

Create the configuration ​

bash
npx veritas init --yes
text
wrote /path/to/project/.veritas/config.json
detected: package manager=npm, tsconfig=none, vitest=5.1.1, git=true
next:
  veritas doctor
  veritas discover --offline
  veritas run --profile quick --offline
OptionEffect
--yesAccept the detected configuration
--forceOverwrite an existing .veritas/config.json
--dry-runPrint the configuration without writing it

init stops with VITEST_NOT_FOUND if the project does not use Vitest. The default configuration turns network sources and LLMs off and uses the integer domain [-10000, 10000] for formal checks. Every setting is listed in the configuration reference.

Answer the questions in a terminal ​

Without --yes, init run in a terminal asks about the settings it cannot detect. Pressing Enter keeps the default for each question, so nothing changes unless you say yes.

QuestionWhat a yes does
LLM providerSets llm.provider (claude, claude-code, codex or openai); each is marked as available or not set up. codex also needs your permission for its read-only shell to read local files (llm.allowCodexFileReads)
GitHub issues and pull requestsTurns on sources.github for the repository (the origin remote is offered); read only in runs without --offline
Web pagesTurns on sources.web for the domains you list; fetched only in runs without --offline
Install Lean 4 (only when it is missing)Downloads the official elan installer from GitHub and installs the stable Lean 4 toolchain into ~/.elan, where veritas doctor looks
Use Lean instead of Z3Sets formal.backend to lean. Lean covers integers and booleans only; Z3 also covers records and arrays
Add @mizchi/mutator to the project (only when it is missing)Runs your package manager to add it as a dev dependency, so mutation testing uses the project's Vitest, test environments and plugins

You then see the resulting configuration and confirm writing it. Installs run only after that confirmation; if Lean cannot be installed, proofs stay on Z3. With --json or in CI, these questions are skipped and nothing is installed; init still asks before writing the detected configuration. --yes writes it without asking, and is required without a terminal.

Check the environment ​

bash
npx veritas doctor
text
available   node             26.13.1 Node.js >= 24
available   git              git version 2.50.1 (Apple Git-155) git repository detected
available   package_manager  npm detected from lockfile
available   typescript       6.0.3 resolved from project
available   vitest           5.1.1 resolved from project
available   mutator          0.4.5 @mizchi/mutator resolved from project
available   fast_check       4.10.3 resolved from project
available   z3               5.4.1 z3-solver (wasm) resolved from project
[...]
disabled    llm               no LLM provider configured; rule-based analysis only
disabled    network           network access disabled (default)
available   sandbox           restricted process (permission model; defence in depth, the project's code is trusted): no writes, child processes or network

enabled   init
degraded  discover (missing: network, llm)
degraded  analyze (missing: llm)
enabled   mutate
[...]
enabled   prove (z3)

The first part lists each tool as available, degraded, unavailable or disabled. The second part lists each command and what it is missing. degraded because of network and llm is the default state: both are optional.

Run the pipeline ​

bash
npx veritas run --profile standard
ProfileWhat runsExecutes your code
quickSource collection, code and test analysis, assessmentNo
standardquick plus mutation testing (default)Your tests
deepstandard plus property-based tests and Z3 checksYour tests and functions
OptionEffect
--offlineVeritas makes no network requests (no web or GitHub sources, no LLM). Your tests run as with npm test
--include-proposedAlso check properties nobody has accepted; their results stay suspected
--since <ref>Mutation-test only what changed since a git ref

The command prints each stage, the verdict and the findings, and exits with 0 (success, possibly with warnings), 1 (confirmed policy failure), 2 (configuration or usage error), 3 (tool error) or 4 (inconclusive under a fail policy). Reading results explains the output.

Find the results ​

Each run writes .veritas/runs/<run-id>/. veritas report prints the latest run again and veritas explain <finding-id> prints the evidence behind one finding. The files are described in Reports and artifacts.

Decisions about specifications are stored in .veritas/approvals.json. Keep the configuration and the decisions in version control and ignore the rest:

text
.veritas/*
!.veritas/config.json
!.veritas/approvals.json
.mutator/

.mutator/ is the working directory of the mutation tool.

Next steps ​

Released under the Apache-2.0 License.