Skip to content

Python quickstart

This quickstart installs the quelltest PyPI package, finds the untested guard clauses in a Python project, writes one verified pytest test, and shows how to fail CI on a low score. Use it when your code is Python and your tests run with pytest. Using JavaScript or TypeScript? See the npm quickstart.

The outputs below come from the quelltest repository at version 2.0.1 on Python 3.13 (the PyPI release shown on this site is 2.0.0, so wording may differ slightly). Progress lines printed on stderr and the emoji markers were removed.

1. How do I install it?

pip install quelltest
quell --version

Requires Python 3.11 or newer and pytest in the project you test. See installation for uv and optional extras.

2. How do I find untested edge cases?

The sample project has src/payments.py with two guard clauses and one test (tests/test_payments.py) that does not cover them:

def charge(amount: float, balance: float) -> float:
    """Charge an amount against a balance.

    Raises:
        ValueError: If amount is zero or negative.
    """
    if amount <= 0:
        raise ValueError(f"Amount must be positive, got {amount}")
    return balance - amount


def discount(price: float, pct: float) -> float:
    """Apply a percentage discount."""
    if pct < 0 or pct > 100:
        raise ValueError("pct must be between 0 and 100")
    return price * (1 - pct / 100)
quell find src/
┌───────────────────────────────────────────────────────┐
│ Quell Scan — reading guard clauses in 2 file(s)       │
│ No docstrings needed. Reading your if/raise patterns. │
└───────────────────────────────────────────────────────┘
                 Logic Gaps Found (2 untested / 2 total)
┌─────────────┬──────────┬──────────────────────────┬──────────┬────────┐
│ File        │ Function │ Guard Clause             │ Type     │ Method │
├─────────────┼──────────┼──────────────────────────┼──────────┼────────┤
│ payments.py │ charge   │ if amount <= 0:          │ boundary │        │
│ payments.py │ discount │ if pct < 0 or pct > 100: │ boundary │        │
└─────────────┴──────────┴──────────────────────────┴──────────┴────────┘

Run quell scan src --fix to generate failing tests.

quell find reads guard clauses (if ... raise, assert, isinstance checks, None checks) with Python's ast module and marks each one covered or uncovered by looking at your test files. It makes no network calls and does not run your tests. It also writes quell-report.json in the project root.

3. How do I write a verified test?

quell find src/ --fix

For each gap Quell generates a pytest test with its rule engine, verifies it, shows it, and asks whether to write it:

[1/2] charge() — boundary condition — if amount <= 0:
  Guard: if amount <= 0:
  Gap proven — test fails on current code
def test_quell_charge_boundary_2faf5d98():
    """Quell: boundary condition — if amount <= 0:"""
    import asyncio
    import pytest
    from src.payments import charge
    with pytest.raises(Exception):
        charge(amount=0.0, balance=1.0)

  Write this test? [Y/n]:   Test written → tests\test_payments.py

[2/2] discount() — boundary condition — if pct < 0 or pct > 100:
  Guard: if pct < 0 or pct > 100:
  Test generated but doesn't catch the gap — needs manual review

The first test was appended to tests/test_payments.py with libcst. The second candidate was rejected because it passed even when the guard was violated, so nothing was written for it. That is the verification working: a test that cannot fail is never written. Candidates that cannot be verified end up in the report with a reason (see three-bucket output).

CI note: --auto is listed in quell find --help as "Skip confirmation prompts", but in the 2.0.1 repository build tested for these docs, quell find --fix still asks Write this test? for each verified test. Use quell ci for non-interactive checks and run --fix locally.

4. How do I get a score for CI?

quell ci src/ --threshold 0.5

Before the test was written:

Quell Score: 0% | Threshold: 50%
FAIL: 0% < 50% threshold

After it was written:

Quell Score: 100% | Threshold: 50%
PASS

quell ci exits 1 when the score is below the threshold and 0 otherwise. The threshold is a fraction between 0.0 and 1.0. The score is the share of requirements read from docstrings and type annotations (including the Raises: section above) that have a covering test, so it uses different readers than quell find and can reach 100% while another guard clause is still untested. See quell ci and the CI guide.

Next steps