Módulos e depuração em Python: testes unitários

Um módulo contém código Python que outro programa pode reutilizar. A maioria dos módulos são arquivos .py. A biblioteca padrão acompanha o Python; código de terceiros precisa de uma instalação separada. Um pacote agrupa módulos relacionados, normalmente em uma pasta.

Relacione a chamada à importação

Uma importação cria nomes no seu programa. A forma escolhida determina como você chama o código importado.

Notação com ponto significa consultar um nome dentro de um módulo ou objeto. Em math.sqrt(16), o Python encontra sqrt dentro de math e o chama com 16. O resultado é 4.0. A constante math.pi não precisa de parênteses de chamada porque é um valor, não uma função.

Após import math, apenas sqrt(16) lança NameError: o programa tem um nome para o módulo, mas nenhum nome separado para sqrt. Após apenas from math import sqrt, o erro inverso, math.sqrt(16), também lança NameError porque math não foi associado. Um nome alternativo substitui o nome usual da associação importada: import statistics as stats cria stats, não ambos os nomes.

Faça o mesmo cálculo de duas formas

Um triângulo retângulo tem lados 3 e 4. Primeiro eleve os lados ao quadrado e some-os; depois extraia a raiz quadrada.

import math

length = math.sqrt(3**2 + 4**2)
print(length)  # 5.0

A expressão dentro da chamada torna-se 9 + 16, depois 25; sqrt retorna 5.0. Com from math import sqrt, escreva length = sqrt(3**2 + 4**2). Usar o prefixo do módulo torna visível a origem de uma função e mantém os outros nomes do módulo fora do espaço de nomes do programa. A própria associação de math ainda pode substituir uma variável anterior chamada math.

Mantenha os nomes claros

Evite from math import *. Essa importação com curinga traz nomes públicos para seu programa sem nomeá-los individualmente. Por exemplo, e = 5 seguido dessa importação altera e para 2.718281828459045. Assim, uma importação que parece não ter relação pode alterar um cálculo posterior. A PEP 8 recomenda importações explícitas e as coloca no início, com um módulo por linha: primeiro a biblioteca padrão, depois pacotes de terceiros e, por último, seus próprios módulos.

O Python executa o código de nível superior de um módulo em sua primeira importação durante a execução de um programa. Importações posteriores reutilizam o módulo carregado; elas não o iniciam novamente.

Use o erro para escolher a correção

No interpretador interativo, execute import math e depois dir(math) para listar seus nomes. Execute help(math.sqrt) para ler a documentação de uma função. A referência oficial da biblioteca Python explica seus argumentos e resultado.

A biblioteca padrão oferece ferramentas testadas para cálculos e simulações. A escolha de uma função começa pelo resultado de que você precisa: uma contagem inteira, uma medida arredondada, um item aleatório ou uma lista reordenada.

Arredondar tem vários significados

Após import math, math.sqrt(16) retorna o número de ponto flutuante 4.0. math.pi e math.e fornecem as constantes 3.141592653589793 e 2.718281828459045. math.factorial(5) multiplica os números inteiros de 1 a 5 e retorna 120.

Para 23 metros quadrados de parede e 10 metros quadrados por lata de tinta, a divisão resulta em 2.3 latas. Comprar latas inteiras exige math.ceil(23 / 10), que retorna 3. round(2.3) resulta em 2 e deixa tinta insuficiente.

A função embutida round() não precisa ser importada. Para um círculo de raio 2, round(math.pi * 2 ** 2, 2) resulta em 12.57. O arredondamento altera a precisão de um número; sua função é diferente da de comprar recipientes inteiros suficientes.

Verifique domínios e comparações de números de ponto flutuante

math.sqrt(-1) lança ValueError porque não há raiz quadrada real para essa entrada. Números de ponto flutuante calculados também exigem cuidado: o armazenamento em binário faz com que 0.1 + 0.2 == 0.3 seja False. math.isclose(0.1 + 0.2, 0.3) é True; use-o para comparar aproximadamente números de ponto flutuante calculados.

Selecione a operação aleatória

O módulo random usa um algoritmo para produzir resultados pseudoaleatórios.

Mantenha random.shuffle(cards) em uma linha própria. Atribuir seu resultado de volta a cards faz com que o nome deixe de estar associado à lista e passe a estar associado a None. Amostrar posições também é diferente de exigir valores distintos: random.sample([1, 1], 2) retorna [1, 1].

Execute uma simulação reproduzível

import random

sevens = 0
for _ in range(1000):
    if random.randint(1, 6) + random.randint(1, 6) == 7:
        sevens += 1
print(sevens)

Seis dos 36 pares igualmente prováveis somam 7, então a contagem geralmente fica perto de 167, mas muda entre execuções. Para reproduzir uma sequência durante a depuração, chame random.seed(42) antes de gerar os valores, usando a mesma versão do Python e sequência de chamadas. Para senhas ou tokens de segurança, use secrets.

Encontre outras ferramentas de uso cotidiano

statistics.mean([2, 4, 9]) retorna 5; statistics.median([2, 4, 9]) retorna 4. datetime.date.today() fornece a data de hoje. Após import sys, sys.argv contém o nome do script seguido de seus argumentos: executar python greet.py Ada fornece ['greet.py', 'Ada'].

Uma função fica mais fácil de reutilizar quando está em um módulo com uma finalidade bem definida. Outro programa pode importar essa função, e um teste pode verificá-la sem pedir que uma pessoa execute toda a aplicação.

Separe a função do código chamador

Salve este código como geometry.py:

"""Calculations for simple shapes."""
import math

def circle_area(radius):
    """Return the area of a circle with the given radius."""
    return math.pi * radius ** 2

Na mesma pasta, salve este código chamador como main.py:

import geometry

print(geometry.circle_area(2))

Execute python main.py. O Python encontra geometry, cria sua função e, em seguida, o código chamador executa essa função. O resultado exibido é 12.566370614359172. Importe sem a extensão .py. Um nome de módulo válido usa letras, dígitos e sublinhados, com um primeiro caractere válido; my_tools.py funciona com import my_tools, enquanto import my-tools é sintaxe inválida.

As strings no início do módulo e da função são docstrings. Elas descrevem a finalidade do código e aparecem em help(geometry) e help(geometry.circle_area).

Entenda o que a importação executa

Na primeira importação, o Python executa as instruções de nível superior do módulo em ordem. Uma instrução def cria uma função; ela não executa o corpo dessa função. Porém, um print(circle_area(2)) sem proteção no final de geometry.py exibiria o resultado durante a importação.

Esse efeito colateral é relevante quando um módulo contém solicitações de entrada ou um laço do programa. Um teste que só precisa de circle_area não deveria ter que iniciar o programa e responder às suas solicitações.

Proteja a inicialização e mantenha a função disponível

Adicione isto abaixo da função reutilizável em geometry.py:

def main():
    print(circle_area(2))

if __name__ == "__main__":
    main()

O Python define __name__ para cada módulo. Uma execução direta, python geometry.py, atribui a ele "__main__", tornando a condição verdadeira e chamando main(). Importar geometry atribui a ele "geometry", então o Python pula a chamada. As definições acima da condição de execução principal continuam disponíveis nos dois casos.

Não coloque a própria circle_area dentro da condição. Quem importa precisa dessa definição mesmo quando a condição de inicialização é falsa. A condição controla quando a aplicação começa; ela não impede o Python de carregar o módulo.

Saiba onde o Python procura

O Python verifica módulos embutidos, como sys, e depois as pastas em sys.path, em ordem. Normalmente, a pasta do script em execução vem primeiro nesse caminho, seguida das pastas da biblioteca padrão e dos pacotes instalados. Manter seus próprios arquivos ao lado do script em execução é uma organização simples para um projeto de iniciante. Um módulo fora do caminho de busca não pode ser encontrado por uma importação comum.

Essa ordem também pode ocultar um módulo da biblioteca. Se você salvar seu programa como random.py, seu import random pode carregar seu arquivo em vez da biblioteca. Um random.randint(1, 6) posterior lança então AttributeError. Renomeie o arquivo, por exemplo, para dice.py; o Python 3.13 e versões posteriores podem incluir uma dica para renomeá-lo no erro.

Um módulo carregado é reutilizado na mesma execução. Em um interpretador interativo, editar o arquivo e importá-lo novamente mantém a versão carregada. Reinicie o interpretador antes de testar suas alterações.

Pacotes de terceiros acrescentam código que não acompanha o Python. O PyPI, o Índice de Pacotes Python em https://pypi.org, hospeda esses projetos. O pip os baixa e instala para uma instalação específica do Python.

Use o terminal e depois use o Python

Um comando de terminal e uma instrução Python pertencem a lugares diferentes. O prompt >>> indica que você está no interpretador interativo do Python. Digitar pip install requests ali produz SyntaxError; o Python não consegue interpretá-lo como uma instrução.

No terminal, execute:

python -m pip install cowsay

Depois, coloque isto em um programa Python:

import cowsay

cowsay.cow("Hello, Ada")

O programa exibe uma vaca feita de texto ao lado de um balão de fala que contém a mensagem. A instalação disponibiliza o pacote; a importação cria a associação do programa para ele.

Associe o pip ao seu interpretador

A forma -m pip pede ao Python indicado que execute seu próprio pip. Use o comando que inicia seus programas: geralmente python3 no macOS ou Linux, ou py no Windows.

python3 -m pip install cowsay
python3 game.py

As duas linhas selecionam o mesmo comando Python. Se uma instalação informar que foi bem-sucedida, mas um script ainda lançar ModuleNotFoundError, compare o Python usado para instalar com o usado para executar o script. Um editor pode ter selecionado um interpretador diferente do seu terminal. Use o pip do interpretador selecionado antes de alterar a importação.

Inspecione e mantenha uma instalação

Uma versão específica é útil quando você precisa do comportamento daquela versão. show ajuda a verificar qual local o pip realmente alterou.

Verifique o nome na documentação

O nome da distribuição digitado para o pip pode ser diferente do nome de importação. Instale beautifulsoup4 e depois use import bs4; instale Pillow e depois use import PIL. Instalar repetidamente um nome de importação não é uma correção útil quando a documentação indica uma distribuição com outro nome.

A biblioteca padrão do Python, incluindo math, random e unittest, já acompanha o Python. Esses módulos não exigem instalação com pip.

Respeite uma instalação gerenciada

Alguns sistemas operacionais e gerenciadores de pacotes protegem seu Python com um erro externally-managed-environment. Isso significa que uma instalação direta é bloqueada para manter a instalação gerenciada consistente. Use um ambiente virtual, uma pasta separada com Python e pacotes para o projeto. Não force a instalação com sudo pip install.

Qualquer pessoa pode publicar no PyPI. Antes de instalar, verifique a grafia exata e leia a página e a documentação do projeto. Nomes parecidos podem ser tentativas de registro de nomes semelhantes com erros de digitação. Prefira pacotes estabelecidos e mantidos e instale aqueles de que seu programa realmente precisa.

Um traceback informa quais chamadas estavam ativas quando uma exceção não tratada interrompeu o programa. Ele fornece tanto um ponto para começar a leitura quanto um caminho de volta ao valor que causou a falha.

Comece pela última linha

Considere este programa completo em scores.py:

def average(values):
    return sum(values) / len(values)

def report(scores):
    avg = average(scores)
    print(f"Average: {avg:.1f}")

report([])

A última linha de seu relatório de erro é ZeroDivisionError: division by zero. Ela informa o tipo de exceção e descreve a operação que falhou. Comece por ela e depois leia para cima até o local do código imediatamente acima.

Um traceback simplificado, sem os marcadores de expressão, é:

Traceback (most recent call last):
  File "scores.py", line 8, in <module>
    report([])
  File "scores.py", line 5, in report
    avg = average(scores)
  File "scores.py", line 2, in average
    return sum(values) / len(values)
ZeroDivisionError: division by zero

Leia cada quadro como uma chamada ativa

Um quadro de chamada fornece o arquivo, o número da linha e a função, seguidos do código relevante. in <module> indica código de nível superior. A chamada mais antiga está no topo; a mais recente está na parte inferior. Ler de baixo para cima inverte essa ordem para que você possa perguntar o que falhou antes de perguntar como a execução chegou até ali.

1. A linha 2 divide por len(values). Para que esse divisor seja zero, values precisa estar vazio.
2. A linha 5 chama average(scores), então inspecione o scores passado por report.
3. A linha 8 fornece [], a lista vazia. Isso explica como o divisor zero chegou ao cálculo.

A linha que falhou e a causa estão relacionadas, mas podem estar em lugares diferentes. Substituir a divisão sem decidir o que uma lista vazia deve significar ocultaria a questão de projeto. O código chamador deve evitar uma lista vazia ou a função precisa ter um comportamento definido para uma entrada vazia.

Use os destaques sem depender de sua forma exata

O Python 3.11 e versões posteriores podem acrescentar os marcadores ^ e ~ para mostrar a parte de uma expressão que falhou. Eles ajudam quando uma linha contém várias operações. O destaque exato varia entre versões, mas os locais das chamadas e a mensagem de exceção ainda indicam a ordem de leitura.

Um traceback pode conter quadros da biblioteca padrão ou de um pacote instalado. Encontre o quadro mais abaixo no seu próprio código e inspecione os argumentos que você forneceu ali. Um quadro de biblioteca é uma pista de localização; ele não prova que a biblioteca contém o defeito.

Reconheça um relatório de sintaxe

Um erro de sintaxe no script que está sendo iniciado impede sua execução. O Python informa um arquivo, uma linha, um marcador e uma mensagem sem o cabeçalho habitual de traceback. Por exemplo, falta o sinal de dois-pontos em if True; total = sum([1, 2, 3] deixa um parêntese aberto.

O local marcado é onde o Python percebeu que não conseguia interpretar a sintaxe do código. Quando essa linha parecer válida, verifique se há aspas ou parênteses não fechados na linha anterior. Não há cadeia de chamadas em tempo de execução a acompanhar quando o script inicial não foi executado.

Uma execução comum para em sua primeira exceção não tratada. Corrija esse problema e execute novamente para revelar o que houver depois no programa.

O nome de um erro delimita a busca, e sua mensagem acrescenta detalhes sobre os valores envolvidos. Um programa também pode estar errado sem lançar uma exceção, então verificar sua saída esperada continua fazendo parte da busca por erros.

Distinga três tipos de problema

IndentationError é um tipo de SyntaxError. O corpo de uma função precisa de indentação; a ausência de um bloco indentado interrompe o código antes da execução. Inspecione também aspas ou parênteses não fechados e palavras reservadas escritas incorretamente.

Leia nomes e tipos com atenção

Um NameError significa que o programa não conhece um nome naquele ponto. Em prnt("hi"), a função embutida pretendida é print. Um nome também pode ser usado antes da atribuição, ou uma importação pode estar ausente.

Um TypeError significa que uma operação recebeu um tipo inadequado ou que uma chamada recebeu o número errado de argumentos. "Age: " + 30 mistura uma string e um inteiro. Escreva "Age: " + str(30) ou f"Age: {30}". Se area precisa de w e h, area(3) também é um TypeError, dessa vez por causa de um argumento ausente.

A mensagem distingue essas causas. Em can only concatenate str (not "int") to str, o Python informa os tipos envolvidos. Após age = input("Age: "), age é texto. age + 1 falha; para uma entrada inteira, int(age) + 1 realiza a operação aritmética.

Um ValueError significa que o tipo da entrada é aceito, mas seu valor é inadequado. int("12.5") recebe uma string, que é um tipo de entrada aceito, mas o texto não representa um número inteiro na forma exigida. math.sqrt(-1) é outro valor inadequado para um cálculo com números reais.

Verifique posições, chaves e atributos

Divisores iguais a zero também provocam falhas com // e %. Uma posição de lista ausente e uma chave de dicionário ausente são consultas diferentes, embora ambas envolvam pedir algo que não existe.

Detecte um resultado que parece plausível

def total_price(prices):
    total = 0
    for i in range(1, len(prices)):
        total += prices[i]
    return total

Para [4, 6, 10], isso retorna 16 em vez de 20. Não há exceção: os índices 1 e 2 existem, então toda operação é válida. O laço começa tarde demais e deixa de incluir o índice 0. O erro se torna visível quando você compara a saída com o total pretendido.

Para uma exceção desconhecida, procure seu tipo e a mensagem geral na documentação oficial do Python. Remova seus próprios caminhos e valores de entrada de uma busca; eles raramente explicam a regra geral.

Um defeito é uma diferença entre o comportamento pretendido e o comportamento real. A depuração encontra a causa e a corrige. Uma sessão útil de depuração transforma uma observação em uma explicação testável e depois altera o código com base em evidências.

Faça a falha se repetir

Registre uma entrada específica e o resultado que ela produz. Para a função de preços que começa seu laço no índice 1, use [4, 6, 10]. O total esperado é 20; o total real é 16. Esses valores concretos permitem verificar se cada investigação ainda diz respeito ao mesmo defeito.

A diferença é 4, e o resultado real é igual a 6 + 10. Uma hipótese específica é que o primeiro preço é ignorado. Essa hipótese prevê algo que você pode inspecionar: o laço nunca passará pelo índice 0.

Siga seis etapas

1. Reproduza: encontre uma entrada que mostre o defeito de forma consistente.
2. Declare os resultados esperado e real: calcule o resultado esperado de forma independente.
3. Formule uma hipótese: indique uma possível causa e o comportamento previsto por ela.
4. Teste-a: inspecione valores com impressões, uma tabela de rastreamento ou um depurador.
5. Corrija a causa: faça uma alteração pontual.
6. Teste novamente: execute a entrada que falhou e os casos que funcionavam antes.

Exiba o índice dentro do laço. Para essa entrada, os únicos índices são 1 e 2, confirmando a previsão. Começar range em 0 corrige o item ignorado. Percorrer diretamente os preços elimina a necessidade de controlar um índice:

def total_price(prices):
    total = 0
    for price in prices:
        total += price
    return total

A função corrigida retorna 20 para [4, 6, 10], 5 para [5] e 0 para []. O caso com um item é útil porque o laço com defeito retornava anteriormente 0 para ele.

Adicionar 4 a cada resposta corrigiria o total observado, mas deixaria a causa. Para [5], essa correção improvisada retornaria 4; o valor ausente depende da entrada. Verifique se uma correção proposta explica todas as evidências antes de mantê-la.

Delimite uma busca maior

Divisão e conquista verifica os valores que alimentam o resultado incorreto em um ponto durante a execução. Se um valor necessário já estiver errado, inspecione o código anterior que o produziu. Se os valores necessários ainda estiverem corretos, acompanhe seu processamento posterior. Repita dentro da seção restante.

Você também pode chamar uma função isoladamente ou remover temporariamente código não relacionado. Um exemplo mínimo reproduzível mantém o código mais curto e a menor entrada que ainda falham. Para um problema visto inicialmente em centenas de registros, encontrar um ou dois registros que o provoquem facilita cada inspeção.

Verifique o que os dados realmente são

Um 5 exibido pode ser a string "5". "5" + "3" produz "53", enquanto a adição numérica resulta em 8. Inspecione type(value) para verificar o tipo. Use repr(value) para revelar espaços e caracteres de nova linha que uma impressão comum pode ocultar, como em ' Ada'.

Explique o código em voz alta, linha por linha, incluindo o que cada laço realmente percorre e o que cada função retorna. Isso é depuração com pato de borracha: explicar uma etapa muitas vezes revela a diferença entre a operação pretendida e a escrita.

Altere uma causa por vez para poder relacionar o resultado à edição. Teste novamente os casos que funcionavam antes, assim como aquele que falhou.

A resposta final de um programa oculta o caminho que a produziu. Impressões temporárias, uma tabela de rastreamento e um depurador permitem ver esse caminho e verificar uma hipótese específica sobre onde ele dá errado.

Exiba um valor em um momento conhecido

Identifique a saída de diagnóstico para que um número tenha um significado claro. O Python 3.8 e versões posteriores aceitam esta forma de f-string:

print(f"{i=} {total=}")

Para o laço de preços com defeito, coloque-a imediatamente antes de total += prices[i]. Com os preços [4, 6, 10], ela exibe:

i=1 total=0
i=2 total=6

Esses são os totais antes de cada adição. Após a primeira impressão, o laço soma 6; após a segunda, soma 10. Uma impressão após a adição mostraria totais diferentes. Decida qual momento responde à sua pergunta antes de interpretar a saída.

Rastreie o mesmo código à mão

Uma tabela de rastreamento registra variáveis passo a passo. Para esse laço:

Não há iteração para o índice 0. Acompanhe os valores reais de início e de parada escritos no código, mesmo quando você já sabe o que o laço deveria fazer. Uma tabela ajuda a separar o que você espera do que acontece.

Pause em um ponto de interrupção

Um depurador pausa um programa em execução para permitir que você inspecione seu estado atual. Um ponto de interrupção marca um lugar para pausar. Em editores como Thonny e VS Code, clique ao lado de um número de linha e inicie o modo de depuração; no IDLE, clique com o botão direito na linha e escolha “Set Breakpoint”.

Após a pausa, escolha uma etapa com base na questão que está investigando:

Se o código chamador passar argumentos corretos, mas receber uma resposta incorreta, entre na função. Se você só precisa ver o resultado retornado, execute a chamada sem entrar na função. Inspecione os valores antes e depois da linha que pode criar o erro.

Use o depurador de texto do Python

Insira breakpoint() imediatamente antes do código que você quer inspecionar. Com a configuração padrão do depurador, executar o programa inicia o pdb naquele ponto. Digite estes comandos no prompt (Pdb):

• p total exibe total.
• n executa a próxima linha sem entrar na função.
• s entra em uma chamada de função.
• c continua a execução.
• q encerra a sessão de depuração.

Esses são comandos do depurador, não linhas para copiar no seu programa.

Distinga a saída exibida dos resultados retornados

Uma função pode exibir o número correto e ainda retornar None porque não tem return total. Inspecione o valor recebido pelo código chamador quando a falha ocorrer após a chamada da função. Ver a saída correta dentro da função não comprova que o código chamador recebeu aquele número.

Use impressões para obter evidências rapidamente ao longo das iterações de um laço e o depurador para inspecionar um momento específico. Após corrigir o defeito, remova as impressões temporárias e as chamadas a breakpoint() para que o programa final seja executado normalmente.

Uma asserção declara algo que deve ser verdadeiro se seu código estiver funcionando corretamente. Ela pode interromper um defeito perto de sua origem ou comparar o resultado de uma função com o valor esperado.

Escreva uma condição e uma mensagem opcional

assert letter_grade(90) == "A", "90 should be an A"

O Python avalia a condição. Se letter_grade(90) retornar "A", a condição é verdadeira e a execução continua sem saída. Se retornar "B", o Python lança AssertionError com a mensagem 90 should be an A. O traceback aponta para a verificação que falhou.

Sem a mensagem, assert letter_grade(90) == "A" ainda verifica o resultado. A última linha da exceção contém AssertionError, enquanto o traceback mostra a expressão. Uma mensagem útil indica a expectativa que falhou; ela deve ajudar você a localizar a regra verificada.

Interrompa cedo um erro interno

Suponha que um cálculo interno exija uma lista não vazia:

def average(values):
    assert len(values) > 0, "values must not be empty"
    return sum(values) / len(values)

Agora, uma lista vazia aciona a asserção antes da divisão. A verificação documenta a suposição interna da função e aponta diretamente para sua violação. Ela não atribui uma média a uma lista vazia nem decide como uma aplicação deve responder à ausência de dados do usuário.

Mantenha ativa a validação de entrada do usuário

A opção -O do Python remove instruções assert. Portanto, um programa que depende de uma asserção para rejeitar entradas externas pode se comportar de forma diferente quando otimizado. Verifique entradas do usuário e outros dados externos com o fluxo de controle comum:

def require_score(score):
    if score < 0 or score > 100:
        raise ValueError("score must be 0 to 100")
    return score

Aqui, raise ValueError(...) informa um valor inadequado. A instrução if continua sendo executada sob -O. Escolha uma asserção para uma suposição interna de programação e uma verificação de entrada ativa para dados externos que podem estar incorretos.

Evite uma verificação que nunca pode falhar

assert é uma instrução, não uma função. Escreva a condição e a mensagem separadas por vírgula:

assert x > 10, "x too small"

Escrever assert (x > 10, "x too small") cria uma tupla de dois itens. Uma tupla não vazia é considerada verdadeira mesmo quando seu primeiro item é False, então a asserção passa. O Python pode avisar que essa asserção é sempre verdadeira. Parênteses em torno apenas de uma condição, como em assert (x > 10), não criam essa tupla; o problema é a vírgula dentro dos parênteses.

Use == para comparação. assert total = 20 é sintaxe inválida porque = atribui um valor.

Compare números com a precisão pretendida

Para um número de ponto flutuante calculado, use uma verificação de proximidade:

import math

assert math.isclose(0.1 + 0.2, 0.3)

Uma comparação exata falha aqui porque a soma de ponto flutuante armazenada difere um pouco de 0.3. Um teste automatizado simples aplica a mesma ideia de asserção a uma função: assert total_price([4, 6, 10]) == 20. O valor esperado vem da regra da função, então a verificação pode revelar uma implementação incorreta.

Um teste unitário verifica uma pequena unidade de código, geralmente uma função, com uma entrada escolhida e um resultado esperado. Testes automatizados facilitam a repetição das mesmas verificações após edições, ajudando a detectar defeitos que voltam em comportamentos que funcionavam antes.

Comece pela especificação

Suponha que uma função de classificação de notas deva retornar "A" para notas de pelo menos 90, "B" para notas de pelo menos 80, mas abaixo de 90, e "C" abaixo de 80. A primeira condição com defeito é score > 90.

Os testes devem cumprir várias funções:

• Casos típicos verificam entradas comuns dentro de cada faixa, como 95 e 85.
• Casos limite verificam os valores em que uma regra muda, como 90 e 89, ou 80 e 79.
• Casos extremos verificam entradas como zero ou uma coleção vazia quando as regras da função as permitem.

Calcule a resposta esperada a partir dessas regras. Copiar a resposta atual do programa para um teste pode preservar seu erro.

Coloque os testes ao lado do módulo

Salve os testes em test_grade.py e a função em grade.py. A inicialização da aplicação em grade.py deve ficar sob a condição de execução principal __main__, para que importar a função não inicie o programa.

from grade import letter_grade

def test_letter_grade():
    assert letter_grade(95) == "A"
    assert letter_grade(90) == "A"
    assert letter_grade(85) == "B"

Para a regra com defeito, a primeira asserção passa. A segunda falha porque 90 não é maior que 90; a execução para ali, antes da terceira asserção nessa função. Alterar a primeira condição para score >= 90 corrige esse limite. Execute todos os testes novamente para verificar o caso afetado e o comportamento anterior.

Garanta que os testes sejam executados

Definir uma função de teste não a chama. Sem um executor de testes, adicione test_letter_grade() no final do arquivo de teste e execute python test_grade.py. Para usar pytest, instale-o com python -m pip install pytest e execute pytest test_grade.py no terminal. Ele encontra as funções de teste e informa seus resultados. Não inclua chamadas manuais quando um executor gerenciar os testes.

Um teste que apenas chama letter_grade(90) não faz comparação. Ele pode terminar com sucesso enquanto a resposta retornada está errada; só falha se a chamada lançar uma exceção inesperada. Uma asserção relaciona a chamada ao comportamento exigido.

Teste valores retornados e propriedades aleatórias

Uma função que apenas exibe um total retorna None. Portanto, uma comparação como assert print_total([4, 6]) == 10 falha mesmo que a tela mostre 10. Faça o cálculo retornar sua resposta e deixe que main cuide da exibição.

Resultados aleatórios exigem uma expectativa diferente. Não se pode exigir que uma função de dado sem semente retorne uma face exata em todas as chamadas. Verifique se cada uma de 100 chamadas retorna um valor permitido de 1 a 6 ou defina uma semente antes de uma sequência reproduzível. Passar no teste de limites verifica os limites para essas chamadas; isso não comprova que todas as faces sejam igualmente prováveis.

Quando um novo defeito aparecer, adicione um teste que falhe por causa dele antes de corrigir a função. Mantenha esse teste de regressão para que edições posteriores verifiquem novamente o mesmo comportamento. Testes que passam comprovam o que aconteceu nos casos testados; outras entradas ainda podem revelar outro defeito.

O Python inclui unittest, uma ferramenta de testes que descobre testes, executa-os e informa resultados separados. Ela não precisa ser instalada com pip. Sua estrutura de classe pode ser usada como modelo enquanto você aprende a testar funções.

Escreva métodos de teste independentes

Para uma função em grade.py, coloque isto em test_grade.py:

import unittest
from grade import letter_grade

class TestLetterGrade(unittest.TestCase):
    def test_top(self):
        self.assertEqual(letter_grade(95), "A")

    def test_boundary(self):
        self.assertEqual(letter_grade(90), "A")

    def test_low(self):
        self.assertEqual(letter_grade(50), "C")

if __name__ == "__main__":
    unittest.main()

TestLetterGrade herda as ferramentas de teste de unittest.TestCase. Cada teste é um método cujo nome começa com test. self identifica o objeto de teste atual; mantenha-o na lista de parâmetros de cada método e antes das chamadas aos métodos de asserção. Você pode copiar essa estrutura sem projetar suas próprias classes.

Por padrão, os testes são executados em ordem alfabética dos nomes de seus métodos, então test_boundary vem antes de test_low e test_top. Faça cada teste fornecer a própria entrada necessária e funcionar independentemente dos testes anteriores.

Escolha um método de asserção

Prefira assertEqual(a, b) a assertTrue(a == b) ao comparar valores: o relatório de falha mostra os dois valores. Os métodos do unittest também mantêm suas verificações quando o Python é executado sob -O.

Para verificar uma exceção esperada, coloque a chamada dentro de assertRaises:

def test_score_too_high(self):
    with self.assertRaises(ValueError):
        letter_grade(120)

Esse teste exige que a regra da função rejeite essa nota com ValueError. Um retorno sem exceção faz essa verificação falhar; uma exceção diferente que não seja de asserção é um erro.

Execute e leia o relatório

Execute python test_grade.py para executar seu unittest.main() protegido pela condição de execução principal. Ou execute python -m unittest para descobrir arquivos test*.py na pasta atual. python -m unittest -v exibe os nomes individuais dos testes e seus resultados.

No relatório resumido, . significa que o teste passou, F significa que uma asserção falhou e E significa que outra exceção ocorreu. Para uma função de classificação com score > 90, os três testes acima produzem F... O relatório de falha de test_boundary mostra 'B' != 'A': o resultado real é "B", enquanto o resultado esperado é "A". O resumo informa três testes e uma falha.

Antes de editar a função, verifique a expectativa do teste em relação às regras de classificação. Uma expectativa incorreta exige uma correção no teste. Se nenhum teste for executado, inspecione os nomes dos métodos, a condição de execução direta e o comando de inicialização. Evite também chamar seu arquivo de unittest.py, pois ele oculta o módulo padrão.