Pytest em Python: guia completo para iniciantes

Testar um programa manualmente funciona enquanto ele é pequeno. Você executa o arquivo, informa alguns valores e observa o resultado. Porém, conforme o projeto cresce, repetir essas verificações depois de cada alteração se torna demorado e sujeito a esquecimentos. É nesse ponto que o Pytest em Python se torna muito útil.

Com o Pytest, você escreve pequenos testes que verificam automaticamente se as funções do seu programa continuam produzindo os resultados esperados. Quando algo quebra, a ferramenta mostra qual teste falhou, em qual linha ocorreu o problema e quais valores foram comparados.

Neste guia, você aprenderá a instalar o Pytest, criar seu primeiro teste, entender o comando assert, verificar exceções e organizar uma estrutura simples de testes. O conteúdo foi preparado para quem ainda está começando e não exige experiência anterior com automação de testes.

O que é Pytest?

Pytest é uma biblioteca usada para criar e executar testes automatizados em projetos Python. Um teste automatizado é um trecho de código que chama outra parte do programa e verifica se o resultado obtido é igual ao resultado esperado.

Imagine uma função que soma dois números. Você espera que somar(2, 3) devolva 5. Em vez de abrir o programa e conferir isso manualmente toda vez, você pode escrever um teste que faz essa verificação em poucos milissegundos.

O Pytest é muito utilizado para criar testes unitários em Python. Esse tipo de teste normalmente verifica uma pequena unidade do programa, como uma função ou método. Ainda assim, a ferramenta também pode ser usada em testes maiores, envolvendo APIs, bancos de dados e aplicações web.

Uma das vantagens do Pytest é a sintaxe simples. Em muitos casos, basta criar uma função iniciada com test_ e usar o comando assert. Isso permite começar sem precisar aprender uma estrutura complexa.

Por que aprender Pytest?

Testes não servem apenas para grandes empresas. Eles também ajudam em projetos pessoais, exercícios e automações pequenas. Ao adicionar testes, você ganha mais confiança para alterar o código, porque pode executar uma verificação rápida antes de considerar o trabalho concluído.

Entre os principais benefícios estão:

• detectar erros logo após uma alteração;
• evitar que um problema corrigido volte a aparecer;
• documentar como uma função deve se comportar;
• facilitar melhorias e refatorações;
• economizar tempo em verificações repetitivas;
• melhorar a confiança ao publicar novas versões.

Um teste não prova que o programa está completamente livre de erros. Ele comprova apenas os comportamentos que foram verificados. Por isso, é importante escrever testes claros e escolher casos relevantes.

O que você precisa antes de começar

Para acompanhar o tutorial, você precisa ter o Python instalado e saber executar comandos no terminal. Também é útil conhecer o básico sobre funções. Caso esse assunto ainda seja novo, consulte o guia de funções em Python.

Você pode escrever o código em qualquer editor, mas o VS Code é uma opção prática para iniciantes. Crie uma pasta chamada projeto_pytest e abra essa pasta no editor.

Também é recomendado usar um ambiente virtual. Ele mantém as dependências do projeto separadas das bibliotecas instaladas globalmente no computador. Isso reduz conflitos e deixa o projeto mais organizado. Veja o tutorial sobre como criar um ambiente virtual com venv para entender o processo completo.

Como instalar o Pytest

Abra o terminal dentro da pasta do projeto e crie o ambiente virtual:

python -m venv .venv

No Windows, ative o ambiente com:

.venv\\Scripts\\activate

No Linux ou macOS, use:

source .venv/bin/activate

Depois, instale o Pytest:

python -m pip install -U pytest

Você também pode encontrar o comando pip install pytest em muitos exemplos. Usar python -m pip ajuda a garantir que o pacote seja instalado no mesmo Python usado pelo projeto. Caso tenha dúvidas sobre esse processo, leia o guia para instalar bibliotecas com pip.

Confirme a instalação:

pytest --version

O terminal deverá exibir a versão instalada. A documentação oficial do Pytest recomenda a instalação pelo pip e usa esse mesmo comando para verificar a versão. O Python Packaging User Guide também apresenta orientações oficiais sobre instalação de pacotes e ambientes virtuais.

Criando o código que será testado

Na pasta principal, crie um arquivo chamado calculadora.py. Adicione uma função simples:

def somar(a, b):
    return a + b

Essa função recebe dois valores e devolve a soma. Agora poderíamos abrir o interpretador, importar a função e conferir vários resultados manualmente. Em vez disso, vamos criar um arquivo que fará isso automaticamente.

Criando seu primeiro teste com Pytest

Crie outro arquivo, na mesma pasta, chamado test_calculadora.py. O prefixo test_ é importante porque ajuda o Pytest a encontrar o arquivo automaticamente.

Adicione o seguinte conteúdo:

from calculadora import somar


def test_somar_dois_numeros():
    resultado = somar(2, 3)
    assert resultado == 5

Vamos entender cada parte:

• from calculadora import somar importa a função que será testada;
• def test_somar_dois_numeros() cria uma função de teste;
• resultado = somar(2, 3) executa o código real;
• assert resultado == 5 verifica se o resultado corresponde ao esperado.

O nome da função também começa com test_. Essa é outra convenção usada pelo Pytest para descobrir testes. Use nomes descritivos, pois eles ajudam a entender rapidamente qual comportamento está sendo verificado.

Como executar o primeiro teste

No terminal, dentro da pasta do projeto e com o ambiente virtual ativado, execute:

pytest

Se tudo estiver correto, você verá uma mensagem semelhante a:

collected 1 item
test_calculadora.py .                         [100%]
1 passed

O ponto indica que o teste passou. A expressão 1 passed informa que um teste foi executado com sucesso.

Para visualizar os nomes dos testes, use o modo detalhado:

pytest -v

O parâmetro -v significa “verbose”, ou seja, uma saída mais detalhada. Para uma saída mais curta, use:

pytest -q

O que acontece quando um teste falha?

Uma das maiores vantagens do Pytest é a clareza do relatório de falha. Altere temporariamente o teste para esperar um resultado incorreto:

def test_somar_dois_numeros():
    resultado = somar(2, 3)
    assert resultado == 6

Execute pytest novamente. O teste falhará porque a soma de 2 e 3 produz 5, não 6. O relatório mostrará algo parecido com:

E       assert 5 == 6
FAILED test_calculadora.py::test_somar_dois_numeros

A letra F representa uma falha. O Pytest informa o valor obtido, o valor esperado, o nome da função e a linha responsável pela comparação.

Uma falha não significa necessariamente que a ferramenta está com problema. Normalmente, uma destas situações ocorreu:

• o código da aplicação está incorreto;
• o valor esperado no teste está incorreto;
• o teste não representa corretamente a regra desejada.

Depois de observar a falha, volte o resultado esperado para 5.

Como criar mais de um teste

Você pode adicionar várias funções no mesmo arquivo. Vamos verificar números negativos e valores iguais a zero:

from calculadora import somar


def test_somar_dois_numeros():
    assert somar(2, 3) == 5


def test_somar_numero_negativo():
    assert somar(-2, 5) == 3


def test_somar_com_zero():
    assert somar(10, 0) == 10

Ao executar pytest -v, os três testes serão listados separadamente. Essa separação ajuda a descobrir exatamente qual cenário falhou.

Evite colocar muitos comportamentos diferentes em uma única função de teste. Testes pequenos costumam ser mais fáceis de entender e corrigir.

Como testar exceções com pytest.raises()

Nem todo teste espera que uma função devolva um valor. Às vezes, o comportamento correto é gerar uma exceção. Adicione esta função ao arquivo calculadora.py:

def dividir(a, b):
    if b == 0:
        raise ValueError("O divisor não pode ser zero")

    return a / b

Agora atualize o arquivo de testes:

import pytest

from calculadora import dividir, somar


def test_dividir_por_zero():
    with pytest.raises(ValueError):
        dividir(10, 0)

O bloco with pytest.raises(ValueError) informa que a chamada deve gerar um ValueError. Se a exceção ocorrer, o teste passa. Se não ocorrer, o teste falha.

Isso é útil em validações, conversões, leitura de arquivos e diversas regras de negócio. Para conhecer as formas básicas de lidar com problemas durante a execução, consulte o conteúdo sobre tratamento de exceções em Python.

Também é possível conferir a mensagem da exceção:

def test_mensagem_ao_dividir_por_zero():
    with pytest.raises(ValueError, match="O divisor não pode ser zero"):
        dividir(10, 0)

Como organizar os arquivos de teste

Em um projeto pequeno, o código e os testes podem ficar na mesma pasta. Quando o projeto crescer, uma estrutura separada fica mais clara:

projeto_pytest/
├── calculadora.py
└── tests/
    └── test_calculadora.py

Execute o comando a partir da pasta projeto_pytest. O Pytest procura arquivos com nomes como test_*.py e *_test.py na pasta atual e em suas subpastas.

Algumas convenções úteis:

• use a pasta tests para centralizar os testes;
• comece os arquivos com test_;
• comece as funções de teste com test_;
• escolha nomes que descrevam o cenário;
• mantenha o código da aplicação separado dos testes.

Nomes claros e formatação consistente também ajudam bastante. O guia de boas práticas da PEP 8 apresenta recomendações para deixar o código Python mais legível.

Comandos úteis do Pytest

Você não precisa memorizar dezenas de opções. Estes comandos já resolvem grande parte das necessidades de quem está começando.

Executar todos os testes

pytest

Mostrar os nomes dos testes

pytest -v

Executar um arquivo específico

pytest tests/test_calculadora.py

Executar testes cujo nome contém uma expressão

pytest -k somar

Esse comando executa testes que possuem a palavra somar no nome.

Parar depois da primeira falha

pytest --maxfail=1

Executar novamente apenas o último teste que falhou

pytest --lf

A opção --lf significa “last failed”. Ela é prática quando você está corrigindo um problema específico.

Erros comuns ao começar com Pytest

O comando pytest não é reconhecido

Verifique se o ambiente virtual está ativado e se a instalação terminou sem erros. Você também pode executar:

python -m pytest

Essa forma pede ao próprio Python para carregar o módulo instalado.

Nenhum teste foi encontrado

Confirme se o arquivo começa com test_ ou termina com _test.py. Verifique também se as funções começam com test_.

Erro ao importar o arquivo principal

Execute o comando na pasta raiz do projeto. Confira o nome do módulo e evite espaços ou hífens nos nomes dos arquivos Python.

O arquivo recebeu o nome pytest.py

Não use pytest.py como nome do seu próprio arquivo. Esse nome pode entrar em conflito com a biblioteca real e causar erros de importação.

O teste passa, mas não verifica nada

Uma função iniciada com test_ pode ser executada mesmo sem assert. Porém, nesse caso, ela talvez não esteja verificando o resultado. Confira se existe uma expectativa clara em cada teste.

O resultado parece confuso

Use pytest -v e leia a primeira falha com atenção. Quando necessário, adicione pontos de interrupção e aprenda a depurar código Python no VS Code.

Boas práticas para seus primeiros testes

Comece com regras simples e previsíveis. Escolha funções que recebem valores e devolvem resultados, pois elas são mais fáceis de testar.

• Dê nomes descritivos aos testes.
• Teste um cenário principal por função.
• Inclua casos comuns, limites e entradas inválidas.
• Evite depender da ordem de execução dos testes.
• Não faça um teste depender do resultado de outro.
• Execute a suíte depois de alterar o código.
• Mantenha os testes tão legíveis quanto o programa.

Uma estrutura útil para pensar em cada teste é:

1. Preparar: definir os dados necessários.
2. Executar: chamar a função testada.
3. Verificar: comparar o resultado com o esperado.

No primeiro exemplo, preparamos os números 2 e 3, executamos a função somar e verificamos se o resultado era 5.

Próximos passos depois deste guia

Depois de dominar os testes básicos, você poderá explorar recursos que reduzem repetição e tornam a suíte mais completa:

• fixtures: preparam dados e recursos reutilizáveis;
• parametrização: executa o mesmo teste com várias entradas;
• mocks: substituem serviços e dependências externas;
• cobertura: mostra quais partes do código foram executadas;
• integração contínua: executa testes automaticamente no repositório.

Não é necessário aprender tudo de uma vez. Um pequeno conjunto de testes claros já oferece valor real e ajuda a criar o hábito de verificar o código continuamente.

Conclusão

O Pytest em Python oferece uma forma simples de começar a escrever testes automatizados. Você instala a biblioteca, cria arquivos e funções iniciados com test_, usa assert para comparar resultados e executa tudo com o comando pytest.

Neste tutorial, criamos testes para uma soma, observamos uma falha proposital, verificamos diferentes cenários e usamos pytest.raises() para confirmar uma exceção esperada. Também vimos uma estrutura de pastas e alguns comandos úteis.

Como exercício, crie novas funções para subtração, multiplicação e divisão. Depois, escreva pelo menos dois testes para cada uma. Essa prática simples ajudará você a entender o fluxo e a ganhar segurança antes de avançar para fixtures, parametrização e mocks.