Execute testes no seu pacote Python#

Executar seus testes em diferentes versões do Python e sistemas operacionais é essencial para garantir que seu pacote funcione para os usuários. Eles podem usar versões do Python e sistemas operacionais diferentes dos seus.

Esta página ensina a executar testes localmente em ambientes isolados e em várias versões do Python. Você conhecerá duas ferramentas de automação principais: Hatch e Nox. Na próxima lição, você aprenderá a executar seus testes online com integração contínua (CI).

Por que executar testes em vários ambientes?#

Quando você desenvolve um pacote no computador, ele funciona em um ambiente específico: sua versão do Python, seu sistema operacional e as dependências instaladas. Seus usuários, no entanto, executarão o código em muitos ambientes diferentes. Ao executar os testes em várias versões do Python e sistemas operacionais, você encontra problemas de compatibilidade antes dos usuários.

Além disso, executar testes em ambientes isolados garante que eles passem por causa do seu código, e não por dependências inesperadas instaladas no seu computador. Isso aumenta a confiança de que seu pacote funcionará quando outras pessoas o instalarem.

Nesta página, você conhecerá as ferramentas que podem ser usadas para executar testes tanto em ambientes isolados quanto em diferentes versões do Python.

Veja também

Páginas relacionadas:

Ferramentas para executar seus testes#

Há três categorias de ferramentas que facilitam a configuração e a execução dos testes em diversos ambientes:

  1. Framework de testes (pytest): Fornece a sintaxe e as ferramentas para escrever e executar seus testes. Saiba mais na documentação do pytest. A seguir, você conhecerá o pytest, o framework de testes mais usado no ecossistema científico Python. Frameworks de testes são essenciais para executar testes, mas não oferecem uma maneira simples de rodá-los em várias versões do Python ou em ambientes isolados — é aí que entram as ferramentas de automação.

  2. Ferramentas de automação (Nox, Tox, Hatch): Permitem executar testes em ambientes isolados e em várias versões do Python com um único comando. A seguir, nosso foco será o Hatch e o Nox. Essas ferramentas criam ambientes virtuais automaticamente e garantem que seus testes sejam executados de forma consistente. Porém, normalmente elas testam apenas no sistema operacional local.

  3. Integração contínua (CI): Executa seus testes online em diferentes sistemas operacionais (Windows, Mac e Linux) e versões do Python. A CI se integra a plataformas como o GitHub Actions para testar automaticamente cada pull request e alteração no código.

Saiba mais sobre CI aqui.

Comparação rápida: o que cada ferramenta faz#

Framework de testes (pytest):

  • Executa seus testes localmente no ambiente Python atual

  • Fornece a sintaxe básica para escrever testes (asserções, fixtures etc.)

  • Pode ser ampliado com plugins (como o pytest-cov para cobertura)

Ferramentas de automação (Nox, Tox, Hatch):

  • Executam testes localmente em várias versões do Python

  • Criam e gerenciam ambientes virtuais isolados automaticamente

  • Podem automatizar outras tarefas, como construir a documentação

  • Facilitam a reprodução dos ambientes de teste

Integração contínua (GitHub Actions):

  • Executa testes online automaticamente para cada pull request

  • Testa em diferentes sistemas operacionais (Windows, Mac, Linux)

  • Testa em várias versões do Python em paralelo

  • Pode automatizar implantações, releases e outros fluxos de trabalho

Qual framework / pacote de testes devo usar para executar testes?#

Recomendamos usar o Pytest para criar e executar os testes do seu pacote. O Pytest é a ferramenta de teste mais comum no ecossistema Python.

O pacote Pytest também tem várias extensões que podem ser usadas para adicionar funcionalidades, como:

  • O pytest-cov permite analisar a cobertura de código do seu pacote durante os testes e gera um relatório que você pode enviar ao codecov.

Nota

Seu editor ou IDE pode oferecer recursos adicionais para executar testes, definir pontos de interrupção e ativar ou desativar a flag –no-cov. Consulte a documentação do seu editor para obter mais informações.

Execute testes usando pytest#

Se estiver usando pytest, você pode executar seus testes localmente chamando:

pytest

Ou, se quiser executar um arquivo de teste específico - vamos chamá-lo de «test_module.py» - você pode executar:

pytest test_module.py

Saiba mais sobre pytest aqui.

Ao executar o pytest no seu computador, os testes serão executados no ambiente Python que estiver ativo. Isso significa que serão executados em uma única versão do Python e apenas no sistema operacional que você usa localmente.

Uma ferramenta de automação pode simplificar o processo de executar testes em diversos ambientes Python.

Testes em diferentes sistemas operacionais

Se quiser executar seus testes em diferentes sistemas operacionais, você pode usar integração contínua. Saiba mais aqui.

Ferramentas para automatizar a execução dos testes#

Para executar testes em várias versões do Python ou em ambientes específicos com um único comando, você pode usar uma ferramenta de automação como nox ou tox. Tanto o nox quanto o tox podem criar ambientes virtuais isolados. Isso permite executar facilmente seus testes em vários ambientes e versões do Python.

Nesta página, nosso foco será o Hatch, pois ele é a ferramenta padrão usada nos nossos tutoriais e no nosso template de pacote Python.

Se você não curte o Hatch, o Nox é uma alternativa abordada na próxima lição. O nox é uma ferramenta de automação baseada em Python que aproveita recursos do make e do tox. O nox foi criado para simplificar e otimizar os fluxos de trabalho de testes e desenvolvimento. Tudo o que você faz com o nox pode ser implementado por meio de uma interface em Python. Você aprenderá mais sobre o uso do nox aqui.

Outras ferramentas de automação que você encontrará por aí

  • O Tox é uma ferramenta de automação compatível com etapas comuns, como construir a documentação, executar testes em várias versões do Python e muito mais.

  • O Make é uma ferramenta de automação de builds que alguns desenvolvedores usam para executar testes devido à sua versatilidade. No entanto, a sintaxe própria do Make pode ser difícil de aprender, e ele não gerencia ambientes para você como o Hatch e o Nox.

Execute testes com Hatch#

O Hatch é um gerenciador moderno de empacotamento e ambientes Python que integra recursos de execução de testes diretamente ao seu pyproject.toml. Ao contrário do Nox (que usa um arquivo noxfile.py separado), o Hatch mantém toda a configuração do projeto em um só lugar, o que o torna ideal se você já usa o Hatch nos fluxos de trabalho de empacotamento.

Por que usar Hatch para testes?#

  • A configuração fica no pyproject.toml, junto aos metadados do projeto

  • Integra-se perfeitamente aos fluxos de empacotamento e build do Hatch

  • Não requer um arquivo Python separado (ao contrário do Nox)

  • Facilita o compartilhamento de ambientes de teste padronizados com a equipe

Como configurar ambientes do Hatch#

Hatch environments can be defined in pyproject.toml. These environments can be used to specify what Hatch needs to run the tests for the package. Test dependencies can be listed individually under [tool.hatch.envs.test], but if packages have already been grouped together under a name, those groups can be listed here instead. Using named groups keeps the dependencies in one place and avoids duplication.

The additional tools or options to run with the tests is specified under [tool.hatch.envs.test.scripts].

[dependency-groups]
test = [
    "pytest",
    "pytest-cov"
]

[tool.hatch.envs.test]
dependency-groups = [
    "test",
]

[tool.hatch.envs.test.scripts]
run = "pytest {args:--cov=test --cov-report=term-missing --cov-report=xml}"

For a complete example, see our packaging template tutorial which shows a full pyproject.toml configuration.

Como executar testes com Hatch#

Depois de definir seu ambiente de teste, você pode executar os testes com comandos simples:

Liste os ambientes disponíveis:

hatch env show

Execute o pytest no ambiente de teste:

# This command is how tests are run if you use the pyos-package-template
hatch run test:run

Como testar em diferentes versões do Python#

To test across multiple Python versions, define a matrix in your pyproject.toml under [[tool.hatch.envs.test.matrix]]:

[tool.hatch.envs.test]
...
...

[[tool.hatch.envs.test.matrix]]
python = ["3.10", "3.11", "3.12"]

Depois, execute todas as versões com um único comando:

hatch run test:run

O Hatch executará automaticamente seus testes no Python 3.10, 3.11 e 3.12. Se quiser testar apenas uma versão específica do Python:

hatch run test.py3.11:run

Como usar Hatch no GitHub Actions#

O Hatch se integra bem a CI/CD. Veja uma configuração mínima do GitHub Actions:

name: Run tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@8c6903cd8c0fde910a37f88322edcfb5dd907a8 # v4
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install hatch
      - run: hatch run test:run

Como todas as dependências de teste são declaradas na tabela dependency-group do seu pyproject.toml, seu ambiente de CI é reproduzível e consistente com os ambientes usados nos testes locais.

Nox vs Hatch: como escolher a ferramenta certa#

Tanto o Hatch quanto o Nox são excelentes ferramentas de automação / executores de tarefas para executar testes em várias versões do Python. Veja a comparação a seguir para decidir qual combina melhor com seu fluxo de trabalho:

Hatch#

  • Configuração: O Hatch usa uma abordagem de configuração declarative. Você informa o que deve compor um ambiente, e isso permite que o Hatch crie o ambiente para você. Todas as opções de configuração ficam no seu pyproject.toml, junto aos metadados do projeto

  • Integração: O Hatch é uma ferramenta de gerenciamento de pacotes que também conta com automação/execução de tarefas integrada. Usar o Hatch significa empregar a mesma ferramenta para todas as necessidades de empacotamento e automação.

  • Curva de aprendizado: Mais fácil se você prefere configuração declarativa a um fluxo de trabalho baseado em código

  • Escopo de empacotamento O Hatch é mais adequado para fluxos de trabalho simples, voltados a testes e empacotamento. Se você tiver builds mais complexos ou estiver criando um pacote Python que não seja puro, talvez prefira o Nox. O guia de desenvolvimento do Scientific Python traz mais detalhes sobre isso.

  • Ideal para: Equipes que usam o Hatch para empacotamento ou que desejam uma configuração padronizada em um só lugar

Nox#

  • Configuração: Controlada por Python via noxfile.py para máxima flexibilidade

  • Personalização: Excelente para fluxos de trabalho complexos que exigem lógica personalizada

  • Curva de aprendizado: Mais fácil se você já conhece Python e quer controle flexível das sessões

  • Ideal para: Necessidades complexas de automação, construção da documentação junto aos testes ou fluxos de trabalho que não seguem o modelo padrão

O que recomendamos#

Se você usa o Hatch para empacotamento: Use o Hatch também para testes. Assim, você tem tudo em um só lugar e usa uma única ferramenta de forma consistente.

Se você precisa de máxima flexibilidade: Escolha o Nox. A abordagem controlada por Python permite implementar praticamente qualquer fluxo de trabalho.

Se você está começando agora: Comece com o Hatch. Ele é mais simples de configurar e entender, e você sempre poderá migrar para o Nox depois, se precisar.

Both tools are good choices. For a more comprehensive guide to using Nox, see Run tests with Nox and the Scientific Python testing guide.

Próximos passos#

Agora que você sabe executar testes localmente em diferentes versões do Python, pode aprender a executar testes automaticamente no GitHub Actions com integração contínua. Você também pode revisar os tipos de teste e escrever testes para seu pacote.