# Quelltest documentation

> Docs for quelltest on npm (JavaScript, TypeScript) and PyPI (Python). Verify that tests catch bugs, gate weakened tests, find untested edge cases.

Canonical page: https://quelltest.com/docs

Quelltest is a pair of tools that check whether your tests would actually notice a bug. The **npm package** (`quelltest`, JavaScript and TypeScript) is a free, offline gate for AI-written tests: it proves a test fails when the code is wrong and fails the build when a change weakens tests. The **PyPI package** (`quelltest`, Python) reads docstrings, Pydantic models and type hints, writes a pytest test for each gap and proves each test catches the violation. Pick the package that matches your language below.

## Which package should I use?

| | npm | PyPI |
| --- | --- | --- |
| Language | JavaScript and TypeScript | Python 3.11+ |
| Install | `npm install -D quelltest` | `pip install quelltest` |
| Command | `npx quell` | `quell` |
| Version in these docs | 0.3.1 | 2.0.0 |
| Licence | Apache-2.0 | MIT |
| Test runners | Jest, Vitest, Mocha, `node:test` | pytest |
| Main job | Mutation-check tests, gate weakened tests, list risky untested edges | Generate and verify pytest tests from specs already in your code |

Both packages are named `quelltest` and both installed command names are `quell`. They are separate projects with separate commands, so a repository with Python and Node code can use both.

## I write JavaScript or TypeScript

1. [Install](https://quelltest.com/docs/npm/installation.md) with `npm install -D quelltest`.
2. Follow the [npm quickstart](https://quelltest.com/docs/npm/quickstart.md): find risky edges, score them against coverage, generate tests, verify a test, gate a change.
3. Put the gate in CI with the [CI guide](https://quelltest.com/docs/npm/ci.md), or give it to a coding agent through the [MCP server](https://quelltest.com/docs/npm/agents.md).

```bash
npm install --save-dev quelltest
npx quell verify tests/pay.test.js --source src/pay.js --runner jest
npx quell gate --diff origin/main
```

## I write Python

1. [Install](https://quelltest.com/docs/installation.md) with `pip install quelltest`.
2. Follow the [Python quickstart](https://quelltest.com/docs/quickstart.md).
3. Read [how the five gates work](https://quelltest.com/docs/how-it-works.md), then wire it into [CI](https://quelltest.com/docs/guides/ci-integration.md) or give it to an agent through the [MCP server and Claude Code plugin](https://quelltest.com/docs/mcp.md).

```bash
pip install quelltest
quell find src/
```

## What do the two packages have in common?

- **They prove tests, not only coverage.** Line coverage says code ran. Both tools check that a test fails when the code is broken: the npm package by mutating your source in a throwaway copy, the Python package by injecting a violation of the requirement it is testing.
- **They run on your machine.** The npm package never sends code anywhere. The Python rule engine needs no network; the LLM fallback is opt-in. See [npm privacy](https://quelltest.com/docs/npm/privacy.md) and [LLM providers](https://quelltest.com/docs/configuration/llm-providers.md).
- **They are built for agents.** Each ships an MCP server so a coding agent can run the checks itself: [npm](https://quelltest.com/docs/npm/agents.md) and [Python](https://quelltest.com/docs/mcp.md).

## Where is everything else?

- [Python reference pages](https://quelltest.com/docs/reference/gates.md): the five gates, three-bucket output, Production Readiness Score and constraint kinds.
- [Claude connector](https://quelltest.com/docs/connector.md): read synced readiness reports from Claude.ai (Pro and Team).
- [npm limits and known issues](https://quelltest.com/docs/npm/limits.md): what the npm package does not do.

## All documentation pages

### Getting started

- [Introduction](https://quelltest.com/docs.md): Docs for quelltest on npm (JavaScript, TypeScript) and PyPI (Python). Verify that tests catch bugs, gate weakened tests, find untested edge cases.

### npm (JavaScript/TypeScript)

- [npm overview](https://quelltest.com/docs/npm.md): Free offline CLI for JavaScript and TypeScript that proves tests fail when code is wrong, flags weakened tests in a diff, and ranks untested risky edges.
- [Installation](https://quelltest.com/docs/npm/installation.md): Install quelltest 0.3.1 with npm, pnpm, yarn or npx on Node.js 20+. It makes no network calls; only the verify command executes your tests.
- [Quickstart](https://quelltest.com/docs/npm/quickstart.md): Run every quelltest command on a small Jest project and read the real output, from finding risky edges to gating a change that weakens tests.
- [CLI reference](https://quelltest.com/docs/npm/cli.md): All eight quelltest npm commands (find, score, generate, verify, gate, mcp, eval, mocks) with every flag, the JSON report shape and exit codes 0 to 6.
- [How verify works](https://quelltest.com/docs/npm/verify.md): How quelltest verify mutates your source in a throwaway copy and requires a test to pass first, observe the code and fail on a mutant. Flags and handoff.
- [The test gate](https://quelltest.com/docs/npm/gate.md): quell gate compares changed test files with their merge-base version and fails on deleted, skipped, .only, removed or loosened assertions. Flags and SARIF.
- [Code that calls APIs](https://quelltest.com/docs/npm/dependencies.md): How quelltest synthesises stubs from guards on API call results, checks stubs against HAR or OpenAPI examples with quell mocks, and what it cannot know.
- [Rule pack](https://quelltest.com/docs/npm/rules.md): Every quelltest find rule id with what it flags, its risk and confidence, the sanitisers it recognises, and the quell-ignore and quell-ignore-mutant directives.
- [CI integration](https://quelltest.com/docs/npm/ci.md): Fail pull requests that weaken tests with quell gate, report risky changed lines with find --diff, upload SARIF to code scanning, and set score thresholds.
- [Privacy](https://quelltest.com/docs/npm/privacy.md): The quelltest npm package sends no code anywhere and makes no network calls. What each command reads and writes, what verify copies, and what the llm hook runs.
- [Limits and known issues](https://quelltest.com/docs/npm/limits.md): What the quelltest npm package does not do: no suite-wide mutation score, narrow test generation, line-level rules, plus known issues in 0.3.1 with workarounds.

### Python (PyPI)

- [Quickstart](https://quelltest.com/docs/quickstart.md): Install the quelltest PyPI package, run quell find on a Python project, write a verified pytest test with --fix, and gate CI with quell ci.
- [Installation](https://quelltest.com/docs/installation.md): Install the quelltest PyPI package (MIT, Python 3.11+) with pip or uv, add optional extras for Groq, PySpark and MCP, and verify the quell command works.
- [How it works](https://quelltest.com/docs/how-it-works.md): How quelltest reads specs from Python code, checks which have no test, generates a pytest test and proves it through five gates before writing it with libcst.
- [Find your first gap](https://quelltest.com/docs/guides/first-gap.md): Step-by-step walkthrough for a Python module: find an untested guard clause, generate a verified pytest test, read quell-report.json, and run the new test.
- [Writing good docstrings](https://quelltest.com/docs/guides/docstrings.md): Which docstring sections and Pydantic constraints the Python quelltest readers turn into requirements, with the real extraction output for a sample module.
- [CLI overview](https://quelltest.com/docs/cli.md): Reference list of the quell commands in the quelltest PyPI package, with what each does, which are deprecated, and links to detailed pages.
- [quell find](https://quelltest.com/docs/cli/find.md): The primary quell command. Reads guard clauses, reports which have no test, and with --fix writes verified pytest tests. Options, output and exit codes.
- [quell score](https://quelltest.com/docs/cli/score.md): Show the Production Readiness Score for a Python path as a panel, JSON or an SVG badge, from a cached quell-report.json or a quick rule-engine scan.
- [quell reproduce](https://quelltest.com/docs/cli/reproduce.md): Convert a plain-English bug description into a verified failing pytest test with quell reproduce. Options, what it needs, and how to read the result.
- [quell ci](https://quelltest.com/docs/cli/ci.md): quell ci checks docstring and type requirements for coverage and exits 1 when the score is below --threshold, a fraction from 0.0 to 1.0.
- [quell auth](https://quelltest.com/docs/cli/auth.md): Configure an LLM provider key with quell auth set, log in to the hosted service in a browser, check status and privacy, and see where credentials are stored.
- [quell init](https://quelltest.com/docs/cli/init.md): quell init appends a default [tool.quell] block to an existing pyproject.toml and adds the scaffold directory to .gitignore. Shows the exact block.
- [quell install](https://quelltest.com/docs/cli/install.md): quell install adds a pre-commit hook and a GitHub Actions workflow that comments the Production Readiness Score on pull requests. Flags --hook and --pr.
- [CI/CD integration](https://quelltest.com/docs/guides/ci-integration.md): Run quell ci in GitHub Actions, GitLab CI or CircleCI to fail Python builds below a requirement-coverage threshold. Threshold units, exit codes and tips.
- [GitHub Actions](https://quelltest.com/docs/guides/github-actions.md): Two ways to run the Python quelltest package on pull requests: the generated quell install --pr workflow with a score comment, or a plain quell ci step.
- [pyproject.toml](https://quelltest.com/docs/configuration/pyproject.md): Reference for every [tool.quell] key the Python quelltest package defines, with types and defaults, and which keys the code actually reads today.
- [LLM providers](https://quelltest.com/docs/configuration/llm-providers.md): Configure the optional LLM fallback in the Python quelltest package: providers, how to store a key, how to enable it, and exactly what the prompt contains.

### Reference

- [Three-bucket output](https://quelltest.com/docs/reference/buckets.md): How the Python quelltest package sorts every edge case into WRITTEN, SCAFFOLDED or FLAGGED, which outcomes map to each bucket, and where reasons are recorded.
- [Five-gate pipeline](https://quelltest.com/docs/reference/gates.md): The five gates every Python quelltest test must pass before it is written: valid AST, original, secure, passes on correct code, fails on violated code.
- [Production Readiness Score](https://quelltest.com/docs/reference/prs.md): How the Python quelltest Production Readiness Score is computed from written tests and per-test confidence, with modifiers, tiers and the confidence factors.
- [Constraint kinds](https://quelltest.com/docs/reference/constraint-kinds.md): The requirement kinds the Python quelltest package extracts, which ones the rule engine can generate tests for, and how each violation is injected.

### AI agents

- [npm: MCP server and hooks](https://quelltest.com/docs/npm/agents.md): Run quell mcp so Claude Code, Cursor or any MCP client can call find, verify and gate, and block an agent from finishing with weakened tests via a Stop hook.
- [Python: MCP server and plugin](https://quelltest.com/docs/mcp.md): Run the local quelltest MCP server (pip install quelltest[mcp]) so Claude Code, Cursor or any MCP client can find gaps and write verified Python tests.

### Connector

- [Overview and setup](https://quelltest.com/docs/connector.md): Connect the Python quelltest package to Claude.ai (Pro and Team) so Claude can answer questions about your synced readiness reports without seeing source code.
- [Tool reference](https://quelltest.com/docs/connector/tools.md): The eight tools the quelltest Claude connector exposes to Claude.ai, with inputs, outputs and rate limits. All read synced reports, never your local disk.
- [Privacy and security](https://quelltest.com/docs/connector/privacy.md): Exactly what the quelltest Claude connector and cloud sync send (test names, scores, flagged locations) and what always stays on your machine.
