Skip to content

What is Veritas? ​

This page explains what Veritas checks, what it reports, and where its results stop.

Veritas checks what the Vitest tests of a TypeScript or JavaScript project actually guarantee. It reads the rules your project already documents (README, docs/, JSDoc, OpenAPI and JSON Schema, git history, exported issues), links them to your code and tests, runs mutation testing, property-based tests and bounded formal checks, and reports each finding together with its evidence.

The problem it addresses ​

A passing test suite tells you that the tests pass, not what they check. For example:

  • a test asserts expect(true).toBe(true) and never calls your code;
  • a test calls your code but never uses the boundary input your documentation describes;
  • the README says "1000 or more", the code says total > 1000, and every test passes because none uses 1000.

In the second and third case every line runs, so line coverage counts the code as covered. Veritas reports all three as findings.

What you get for each test and rule ​

QuestionEvidence in the report
Which documented rule does this test relate to?The quoted source line (file and line) and the property built from it
What does the test check?The project functions it calls and the results it asserts
Which faults would it catch?The mutants it kills and the mutants that survive it
What was checked formally, and within which bounds?Z3 or Lean results with their input domain, assumptions and solver files
What is still unknown?Undecided, unsupported and skipped checks, listed by name

What Veritas does not do ​

  • It gives no score. Each test gets an evidence vector and one of five outcomes. See Reading results.
  • It does not prove your code correct. proven_within_model means that no counterexample exists within the stated model, bounds and assumptions. See Verification.
  • It does not decide what the specification is. No rule it finds becomes accepted unless you accept it, and it never changes a specification or an expected value to match the code. See Specifications.
  • It does not isolate your project's code. Veritas runs your tests and functions with the same trust as npm test. See Untrusted repositories.

How a run works ​

text
CLI / Node API / Agent Skill / MCP server / GitHub Action
                       |
                  Orchestrator
                       |
    +------------------+-------------------+
Evidence collectors  Code intelligence  Test inventory
 (README, docs, ...)  (TypeScript API)    (Vitest tests)
    +---------- Specification engine ------+
                       |
                Property registry
         (proposed -> accepted | rejected ...)
       +---------------+-------------------+
 Mutation testing  Property-based tests  Formal checks
   (mutator)          (fast-check)       (Z3 / Lean 4)
       +---------------+-------------------+
                Assessment engine
       (evidence vectors, findings, verdict)
                       |
               Improvement planner
                       |
       Artifacts / reports / CI exit codes
  1. Veritas collects sources and keeps the file and line of every statement.
  2. It turns statements such as "Orders with a total of 1000 or more receive a flat discount of 100" into properties of one function and one parameter. It also infers candidate properties from the code; those are hypotheses, not specifications.
  3. It finds your Vitest tests and what they call and assert.
  4. Mutation testing, property-based tests and Z3 or Lean produce evidence about each property.
  5. The assessment engine produces per-test evidence vectors, findings, a verdict and an exit code.
  6. On request, the improvement planner proposes new test files whose expected values come from accepted properties.

Architecture describes the packages behind each step.

Ways to run it ​

All entry points use the same engine. Each command writes the artifacts of the stages it runs to .veritas/runs/<run-id>/; commands that include the report stage (veritas run and veritas prove) also write the reports listed in reports.formats (by default JSON, Markdown, HTML and SARIF).

Entry pointUse it forStart here
CLI veritasLocal use and any CI systemGetting started, CLI reference
Node APICalling Veritas from your own toolsNode API
MCP serverAgents that use MCP (veritas-mcp)Agents and MCP
Agent SkillAgents that load SKILL.md filesAgents and MCP
GitHub ActionChecks on pull requestsCI and GitHub Action

Veritas makes no network requests unless you enable network sources or an LLM provider.

Released under the Apache-2.0 License.