Find and fix your first Python test gap
This walkthrough takes one small Python module from an untested guard clause to a verified pytest test, and shows where to look when a candidate is rejected. It uses the real output of the repository build (2.0.1) with progress lines and emoji removed. If you have not installed the package yet, start with the Python quickstart.
1. Which code do I start with?
A function with a guard clause that no test exercises:
# src/payments.py
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
and a test file that only covers the happy path:
# tests/test_payments.py
from src.payments import charge
def test_charge_subtracts():
assert charge(30, 100) == 70
2. How do I find the gap?
quell find src/payments.py
Logic Gaps Found (1 untested / 1 total)
┌─────────────┬──────────┬─────────────────┬──────────┬────────┐
│ File │ Function │ Guard Clause │ Type │ Method │
├─────────────┼──────────┼─────────────────┼──────────┼────────┤
│ payments.py │ charge │ if amount <= 0: │ boundary │ │
└─────────────┴──────────┴─────────────────┴──────────┴────────┘
The coverage checker looked for tests/test_payments.py, found no test that exercises the guard, and marked it uncovered. It prefers a duplicate over a missed gap: when it cannot tell, the guard is reported.
3. How do I write the test?
quell find src/payments.py --fix
Quell generates a test with the rule engine, runs it, injects a violation into charge (for a boundary requirement such as this one it weakens the threshold, <= 0 becoming <= -9999; for a must_raise requirement it replaces the raise with pass), runs the test again, and requires it to fail. Only then does it ask:
def test_quell_charge_boundary_a89d4fdd():
"""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
The source file is restored in a finally block after the violation run, whatever happens.
4. How do I confirm the new test?
pytest tests/test_payments.py -v
tests/test_payments.py::test_charge_subtracts PASSED [ 50%]
tests/test_payments.py::test_quell_charge_boundary_a89d4fdd PASSED [100%]
============================== 2 passed in 0.01s ==============================
5. What if a candidate is rejected?
Every gap ends up in quell-report.json in the project root with an outcome and a reason:
| Outcome | Meaning |
|---|---|
verified | Test passed on the original code and failed on the violated code; offered for writing. |
rejected_no_catch | The test passes even when the guard is violated: it would not catch a bug, so it is not written. |
rejected_fails_on_correct | The generated stub breaks valid code, usually because the function takes complex or Pydantic arguments or depends on self state. The report keeps the pytest output. |
skipped_no_rule, skipped_local_var, skipped_async, skipped_no_gen | No deterministic test could be built; a stub may be written to tests/scaffold/. |
skipped_framework_no_app, skipped_framework_unsupported | A FastAPI or Flask route was detected, but no app object was found or the engine could not build a test. |
See three-bucket output for how these map to written, scaffolded and flagged, and constraint kinds for what each kind's test asserts.