# Find and fix your first Python test gap

> 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.

Canonical page: https://quelltest.com/docs/guides/first-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](https://quelltest.com/docs/quickstart.md).

## 1. Which code do I start with?

A function with a guard clause that no test exercises:

```python
# 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:

```python
# 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?

```bash
quell find src/payments.py
```

```text
                 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?

```bash
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:

```text
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?

```bash
pytest tests/test_payments.py -v
```

```text
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](https://quelltest.com/docs/reference/buckets.md) for how these map to written, scaffolded and flagged, and [constraint kinds](https://quelltest.com/docs/reference/constraint-kinds.md) for what each kind's test asserts.
