QuellDocs
DocsQuickstart

Quickstart

This guide assumes you have a Python project with docstrings or Pydantic models. If not, the example below creates one from scratch.

1. Install Quell

pip install quelltest

2. Add a spec to your code

If you don't have one already, add a docstring or a Pydantic model:

# payments.py
from pydantic import BaseModel, Field
from typing import Literal

class PaymentRequest(BaseModel):
    amount: float = Field(gt=0)
    currency: Literal["USD", "EUR", "GBP"]

def process_payment(request: PaymentRequest) -> dict:
    """
    Process a payment transaction.

    Args:
        request: Amount must be greater than 0. Currency must be one of: USD, EUR, GBP.

    Returns:
        dict with transaction_id, status, amount.

    Raises:
        ValueError: If amount is zero or negative.
    """
    if request.amount <= 0:
        raise ValueError("Amount must be positive")
    return {"transaction_id": "txn_123", "status": "ok", "amount": request.amount}

3. Scan for requirement gaps

quell check payments.py

Quell reads the docstring and the Pydantic model, extracts every requirement, and shows which ones have no test:

Requirements — payments.py
Function              Kind         Description                        Covered
process_payment       MUST_RAISE   ValueError: If amount is zero...   NO
process_payment       MUST_RETURN  dict with transaction_id, statu... NO
process_payment       BOUNDARY     Amount must be greater than 0      NO
PaymentRequest        ENUM_VALID   currency: USD, EUR, GBP            NO
PaymentRequest        BOUNDARY     amount: gt=0                       NO

Score: 0% (0/5 covered)
5 gap(s) found. Run with --fix to generate tests.

4. Generate and write verified tests

quell check payments.py --fix

For each gap, Quell generates a candidate test, proves it passes on correct code AND fails on violated code, then writes only the verified tests.

5. Reproduce a bug from a description

quell reproduce "payment accepts zero amount silently"

Quell converts the plain-English bug description into a failing test that you can use to drive a fix.

6. Check coverage for a specific file

quell prove payments.py

80% of requirements proven for payments.py

7. Project-wide score

quell score --badge

File          Requirements   Covered   Score   Grade
payments.py            5         4     80%       B
auth.py                8         7     87%       A

Project Score: 84%
Badge written to .quell/badge.svg

Next steps

Previous

Introduction

Next

Installation