Se você evitou escrever testes porque eles pareciam uma tarefa árdua, este tutorial do pytest deve fazer você mudar de ideia. Pytest remove a maior parte da cerimônia: não há classes das quais herdar e nenhum método de afirmação especial para lembrar. Um teste pode ter apenas duas linhas.

Construiremos um pequeno carrinho de compras e o testaremos passo a passo. Executamos tudo no Python 3.13 com pytest 9.2, e a saída mostrada é real, embora tenhamos cortado os caminhos dos arquivos e os detalhes de tempo que serão diferentes em sua máquina.

Por que pytest?

Python vem com unittest, o que funciona bem, mas pytest geralmente é a escolha mais conveniente. Aqui está a mesma verificação em cada um:

Pytest também pode executar seus testes unittest existentes, para que você possa mudar gradualmente. Ele também possui um grande ecossistema de plugins, incluindo pytest-cov para cobertura e pytest-xdist para execuções paralelas.

Instale o pytest

Crie um ambiente virtual primeiro, conforme explicado em nosso tutorial de ambiente virtual Python, e depois instale-o:

pip install pytest
pytest --version

# pytest 9.2.0

Crie uma pasta de projeto contendo dois arquivos, cart.py e test_cart.py. O Pytest encontra testes automaticamente seguindo regras de nomenclatura: arquivos nomeados test_*.py ou *_test.py, funções começando com test e classes começando com Test. Se um teste não estiver sendo selecionado, uma incompatibilidade de nomenclatura é a primeira coisa a verificar.

O código para testar

# cart.py
class Cart:
    def __init__(self):
        self.items = []

    def add(self, name, price, qty=1):
        if qty < 1:
            raise ValueError("qty must be at least 1")
        self.items.append((name, price, qty))

    def total(self, discount=0):
        subtotal = sum(price * qty for _, price, qty in self.items)
        return round(subtotal * (1 - discount / 100), 2)

Seus primeiros testes

# test_cart.py
from cart import Cart

def test_empty_cart_is_free():
    assert Cart().total() == 0

Esse é um teste completo. Execute pytest na pasta do projeto e ele relatará um teste aprovado. Se você receber um erro de importação, execute-o como python -m pytest, que adiciona a pasta atual ao caminho de importação.

Falhas de leitura

É aqui que o pytest realmente brilha. Aqui está um teste com um valor esperado deliberadamente errado:

def test_wrong_total():
    c = Cart()
    c.add("Keyboard", 1500)
    assert c.total() == 1400

E foi isso que foi impresso quando o executamos:

    def test_wrong_total():
        c = Cart()
        c.add("Keyboard", 1500)
>       assert c.total() == 1400
E       assert 1500.0 == 1400
E        +  where 1500.0 = total()

FAILED fail_example.py::test_wrong_total - assert 1500.0 == 1400
============================== 1 failed in 0.12s ==============================

O > marca a linha com falha e as linhas E mostram os valores reais. Você não precisou adicionar uma mensagem personalizada, porque o pytest reescreve as instruções assert para que possam relatar o que compararam. Faz o mesmo com listas e dicionários, apontando exatamente quais itens diferem.

Testando exceções

O tratamento de erros também é um comportamento e merece testes. pytest.raises passa apenas se o bloco gerar a exceção esperada:

import pytest

def test_rejects_zero_qty():
    with pytest.raises(ValueError, match="at least 1"):
        Cart().add("Pen", 10, qty=0)

O argumento opcional match verifica a mensagem usando uma expressão regular, portanto um ValueError diferente não passará por acidente. Para saber como gerar e tratar erros como este, leia nosso guia sobre tratamento de exceções em Python.

Luminárias: configuração reutilizável

A maioria dos testes precisa de algo preparado primeiro. Um fixture é uma função que fornece isso. Decore-o com @pytest.fixture, e qualquer teste que o nomeie como argumento receberá o resultado:

@pytest.fixture
def cart():
    c = Cart()
    c.add("Keyboard", 1500)
    c.add("Mouse", 500, qty=2)
    return c

def test_total(cart):
    assert cart.total() == 2500

Cada teste recebe um carrinho novo por padrão, portanto, os testes não podem afetar uns aos outros. Pytest combina o nome do argumento com o nome do aparelho, e você nunca chama o aparelho sozinho. @pytest.fixture é um decorador, que explicamos em Decoradores Python explicados.

Limpeza com rendimento

Use yield em vez de return quando precisar limpar depois. O código após yield é executado quando o teste termina, mesmo que tenha falhado:

@pytest.fixture
def temp_db():
    print("\nopen db")
    yield {"users": []}
    print("close db")

def test_db(temp_db):
    assert temp_db["users"] == []

A execução com -s para mostrar a saída impressa confirmou que o pedido foi aberto, testado e fechado.

Escopo de fixação e conftest.py

Por padrão, um fixture é executado uma vez por teste. Para configurações caras, como banco de dados ou navegador, altere seu tempo de vida com scope:

Coloque os fixtures usados por vários arquivos em um arquivo chamado conftest.py. O Pytest o carrega automaticamente, para que os testes possam usar seus fixtures sem importação. Porém, tenha cuidado com escopos compartilhados, pois uma alteração feita por um teste pode vazar para o próximo.

Parametrizar: um teste, muitas entradas

Em vez de copiar um teste para cada valor, liste os casos:

@pytest.mark.parametrize("discount, expected", [
    (0, 2500),
    (10, 2250),
    (100, 0),
])
def test_discount(cart, discount, expected):
    assert cart.total(discount) == expected

Cada linha se torna seu próprio teste, e você pode ver isso na saída detalhada da execução do arquivo completo:

test_cart.py::test_total PASSED                        [ 16%]
test_cart.py::test_discount[0-2500] PASSED             [ 33%]
test_cart.py::test_discount[10-2250] PASSED            [ 50%]
test_cart.py::test_discount[100-0] PASSED              [ 66%]
test_cart.py::test_rejects_zero_qty PASSED             [ 83%]
test_cart.py::test_empty_cart_is_free PASSED           [100%]

============================== 6 passed in 0.05s ==============================

Se uma linha falhar, as outras ainda serão executadas e o nome informará exatamente quais valores causaram o problema. Observe que combinamos parametrize com o fixture cart. Para escolher valores com probabilidade de encontrar bugs, use a análise de valor limite.

Acessórios integrados úteis

Pytest inclui vários acessórios prontos. Esses dois são especialmente úteis e ambos foram aprovados em nossa corrida:

def test_write_report(tmp_path):
    report = tmp_path / "report.txt"
    report.write_text("passed")
    assert report.read_text() == "passed"

def read_mode():
    return os.environ.get("APP_MODE", "dev")

def test_mode(monkeypatch):
    monkeypatch.setenv("APP_MODE", "staging")
    assert read_mode() == "staging"

tmp_path fornece a cada teste uma pasta temporária exclusiva, para que os testes nunca toquem em arquivos reais. monkeypatch altera variáveis ​​​​ou atributos de ambiente e desfaz a alteração quando o teste termina. Outro útil é capsys, que captura a saída impressa para que você possa verificá-la.

Marcadores: pular e xfail

Os marcadores adicionam rótulos e comportamento aos testes:

@pytest.mark.skip(reason="payment sandbox is down")
def test_payment():
    assert False

@pytest.mark.xfail(reason="floating point")
def test_rounding():
    assert 0.1 + 0.2 == 0.3

skip não executa o teste. xfail o executa, mas espera falha, portanto, um problema conhecido não interrompe sua compilação. Com os outros testes extras no mesmo arquivo, nossa execução foi resumida como 3 passed, 1 skipped, 1 xfailed. A propósito, esse teste de arredondamento realmente falha: na aritmética de ponto flutuante, 0,1 + 0,2 não é exatamente 0,3. Use pytest.approx(0.3) ao comparar decimais.

Você também pode criar seus próprios marcadores, como @pytest.mark.slow, e executá-los apenas com pytest -m slow ou deixá-los de fora com -m "not slow". Registre marcadores personalizados em seu arquivo de configuração para evitar avisos.

Sinalizadores de linha de comando úteis

Executando pytest em CI

Os testes são mais valiosos quando são executados automaticamente a cada alteração. Um trabalho mínimo do GitHub Actions é assim:

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
    with:
      python-version: "3.13"
  - run: pip install -r requirements.txt
  - run: python -m pytest

Pytest sai com um código diferente de zero quando os testes falham, o que faz o pipeline parar. Não executamos este arquivo de fluxo de trabalho, então adapte-o ao seu projeto. Nosso guia de CI/CD de ações do GitHub explica os detalhes. Pytest também funciona bem para testes de navegador, como mostram nosso tutorial Selenium Python e tutorial de modelo de objeto de página.

Considerações finais

Agora você tem o que precisa para a maioria dos conjuntos de testes Python: declarações simples, acessórios para configuração, parametrização para variações e alguns sinalizadores para velocidade. Comece pequeno. Escolha uma função na qual você corrigiu recentemente um bug e primeiro escreva um teste para esse bug. Se você não tiver certeza do que testar em cada nível, leia sobre teste de unidade versus teste de integração.

Perguntas frequentes

Continue aprendendo