doctest procura sessões interativas em docstrings e compara a saída real com a saída escrita. Isso ajuda a impedir que exemplos curtos fiquem desatualizados quando a função muda.
Exemplo prático
def total_with_tax(value: float, rate: float) -> float:
"""Return the total after tax.
>>> total_with_tax(100, 0.2)
120.0
>>> total_with_tax(50, 0)
50.0
"""
return value * (1 + rate)
if __name__ == "__main__":
import doctest
doctest.testmod(verbose=True)Como executar o exemplo
O bloco chama testmod() apenas quando o arquivo é executado diretamente. Em um projeto, também é possível rodar python -m doctest -v arquivo.py. A comparação é textual, então representação, espaços e casas decimais importam.
Onde ele funciona melhor
Use doctests para contratos pequenos, tutoriais e exemplos de API. Evite esconder muita preparação dentro da docstring. Para fixtures, múltiplos cenários e mensagens de falha mais ricas, mova o caso para uma suíte convencional.
Cuidados práticos
Não copie saídas instáveis, como endereços de memória ou ordem de conjuntos. Opções como ELLIPSIS existem, mas tolerância excessiva pode fazer um exemplo incorreto passar.
Continue estudando
Aprofunde a base com testes unitários com unittest. A documentação oficial do Python, consultada em 22 de julho de 2026, detalha a API, as limitações e as diferenças entre versões.