Execute testes com Nox#

O Nox é uma ferramenta de automação baseada em Python para executar testes em várias versões do Python e gerenciar ambientes de teste isolados. Se você prefere configuração controlada por Python em vez de TOML ou precisa de fluxos de automação complexos, o Nox é uma excelente opção.

For more information about Nox, see the official Nox documentation or the Scientific Python guide to testing.

Por que usar Nox?#

O Nox é uma ótima ferramenta de automação porque:

É baseado em Python, o que facilita o uso se você já conhece a linguagem
Cria ambientes isolados para executar fluxos de trabalho
É compatível com automações complexas e personalizadas, além dos testes padrão
É flexível e poderoso para cenários elaborados de build e teste

O nox simplifica a criação e o gerenciamento de ambientes de teste. Com o nox, você pode configurar ambientes virtuais e executar testes em diferentes versões do Python usando o gerenciador de ambientes de sua preferência com um único comando.

Configure o Nox#

Para começar a usar o Nox, crie um arquivo noxfile.py na raiz do diretório do projeto. Depois, defina comandos usando funções Python.

Nota

Instalações do Nox

Quando você instala e usa o Nox para executar testes em diferentes versões do Python, ele cria e gerencia ambientes venv individuais para cada versão do Python especificada na função do Nox. Cada ambiente é gerenciado separadamente.

O Nox também pode ser usado em outras tarefas de desenvolvimento, como construir a documentação, criar a distribuição do pacote e testar instalações tanto em ambientes relacionados ao PyPI (por exemplo, venv e virtualenv) quanto no conda (por exemplo, conda-forge).

Ambientes de teste#

Por padrão, o nox usa o gerenciador de ambientes venv, integrado ao Python. Um ambiente virtual (venv) é um ambiente Python autocontido que permite isolar e gerenciar as dependências de diferentes projetos Python. Ele ajuda a garantir que bibliotecas e pacotes específicos de cada projeto não interfiram uns nos outros, promovendo um ambiente de desenvolvimento limpo e organizado.

Nox com ambientes venv#

A seguir, veja um exemplo de configuração do Nox para executar testes usando venv, o gerenciador de ambientes integrado à instalação básica do Python.

Observe que o exemplo a seguir pressupõe que você configurou o pyproject.toml para declarar as dependências de teste usando project.optional-dependencies:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "pyosPackage"
version = "0.1.0"
dependencies = [
  "geopandas",
  "xarray",
]

[project.optional-dependencies]
tests = ["pytest", "pytest-cov"]

Com essa configuração, você pode usar session.install(".[tests]") para instalar suas dependências de teste. Observe que, a seguir, uma única sessão do Nox permite executar seus testes em 4 ambientes Python diferentes (Python 3.9, 3.10, 3.11 e 3.12).

Nota

Para executar essa configuração, você precisará ter python3.9, python3.10, python3.11 e python3.12 instalados no computador. Caso contrário, o nox pulará a execução dos testes nas versões que estiverem ausentes.

# This code would live in a noxfile.py file located at the root of your
# project directory
import nox

@nox.session(python=["3.9", "3.10", "3.11", "3.12"])
def test(session):
    # Install dependencies
    session.install(".[tests]")
    # Run tests
    session.run("pytest")

Acima, você cria uma sessão do Nox na forma de uma função com o decorador @nox.session. Observe que, no decorador, você declara as versões do Python que deseja executar.

Para executar o exemplo acima, use o comando a seguir e especifique a sessão com --session (às vezes abreviado como -s). A função acima se chama test; portanto, o nome da sessão é test:

nox --session test

Nox com conda / mamba#

A seguir, veja um exemplo de configuração do Nox para usar mamba (ou conda) como gerenciador de ambientes. Ao contrário do venv, o conda pode instalar automaticamente as várias versões do Python necessárias. Se você usar conda/mamba, não precisará instalar as quatro versões do Python, como ocorre com o venv.

Nota

Para o conda funcionar com o nox, verifique se o conda ou o mamba está instalado no seu computador.

# This code should live in your noxfile.py file
import nox

# The syntax below allows you to use mamba / conda as your environment
# manager. If you use this approach, you don't have to worry about installing
# different versions of Python

@nox.session(venv_backend='mamba', python=["3.9", "3.10", "3.11", "3.12"])
def test_mamba(session):
    """Nox function that installs dev requirements and runs tests on Python
    3.9 through 3.12.
    """
    # Install dev requirements
    session.conda_install(".[tests]")
    # Run tests using any parameters that you need
    session.run("pytest")

Para executar a sessão acima, use:

nox --session test_mamba

Hatch vs Nox#

Se estiver tentando escolher entre o Hatch e o Nox, consulte a comparação e as recomendações na página principal sobre testes.

Em resumo#

Escolha o Hatch se você já o usa para empacotamento e quer manter tudo em um só lugar
Escolha o Nox se você precisa de máxima flexibilidade, prefere uma configuração controlada por Python ou precisa de fluxos de automação complexos

Próximos passos#

Agora que você sabe executar testes localmente com o Nox, pode aprender a executar testes automaticamente com integração contínua ou a executar testes com Hatch.