# Python quickstart

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

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

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?

```bash
pip install quelltest
quell --version
```

Requires Python 3.11 or newer and pytest in the project you test. See [installation](https://quelltest.com/docs/installation.md) 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:

```python
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)
```

```bash
quell find src/
```

```text
┌───────────────────────────────────────────────────────┐
│ 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?

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

```text
[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](https://quelltest.com/docs/reference/buckets.md)).

> **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?

```bash
quell ci src/ --threshold 0.5
```

Before the test was written:

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

After it was written:

```text
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](https://quelltest.com/docs/cli/ci.md) and the [CI guide](https://quelltest.com/docs/guides/ci-integration.md).

## Next steps

- [How it works](https://quelltest.com/docs/how-it-works.md): spec readers, coverage checker, rule engine and the five gates.
- [CLI overview](https://quelltest.com/docs/cli.md): every command.
- [Writing good docstrings](https://quelltest.com/docs/guides/docstrings.md): what the docstring and type readers extract.
- [MCP server and Claude Code plugin](https://quelltest.com/docs/mcp.md): let an agent run these commands.
