Quell Documentation
Quell reads specifications that already exist in your codebase — docstrings, Pydantic models, bug reports — extracts every testable requirement, checks which ones have no test, generates a verified test for each gap, then writes it to disk.
New here? Jump straight to the Quickstart to prove your first requirement in under 5 minutes.
What problem does Quell solve?
Other test generation tools read your implementation and generate tests for what your code does. If your code has a bug, they generate tests that bless it.
Quell reads your specification — the docstring that says "must raise ValueError", the Pydantic model that says Field(gt=0) — and generates a test that proves the requirement. It catches bugs instead of blessing them.
Spec-first generation
Quell reads docstrings, Pydantic models, PySpark schemas, and bug descriptions. It extracts requirements, not implementation.
Zero false positives
Every generated test is verified in two phases: passes on correct code AND fails on violated code. Both are required.
Formatting preserved
Tests are injected using libcst — a lossless concrete syntax tree. Your comments and spacing are untouched.
Privacy first
Use --no-llm to guarantee no network calls. LLM is only called for complex unstructured specs when configured — most requirements are handled by the rule engine.
PR integration
quell pr <N> fetches a PR diff, checks coverage on changed files, and posts a formatted comment with a score emoji and gap table. One command: quell install --pr.
Diagnostic report
Every --fix run writes .quell/report.json — a privacy-safe file recording where the rule engine succeeded and failed. No source code included. Safe to share.
How it works
Read specs
Quell scans your docstrings (Raises:, Args:, Returns: blocks), Pydantic models (Field validators, Literal types), and bug descriptions. Each spec becomes a typed Requirement.
Find gaps
An AST-based coverage checker scans your test files and marks each Requirement as covered or uncovered — no test execution required.
Verify
For each gap, Quell generates a candidate test, then proves it in two phases: it must PASS on the original code and FAIL on code that violates the requirement.
Write
Verified tests are injected into your test file using libcst. The file is backed up first. The write is only committed if the injected source parses correctly.
Supported spec sources
| Source | Examples extracted |
|---|---|
| Docstrings | Raises: ValueError if amount <= 0, Returns: dict with status |
| Pydantic models | Field(gt=0), Field(min_length=1), Literal["USD", "EUR", "GBP"] |
| Type annotations | Literal["active", "inactive"] function arguments |
| Bug descriptions | "payment accepts zero amount silently" |
| PySpark schemas | StructType([StructField("amount", DoubleType(), nullable=False)]) |
Quick install
pip install quelltest
Requires Python 3.11+. The CLI command is quell. See Installation for virtual environment setup.