Você já sentiu aquele frio na barriga ao enviar um código para produção sem saber se ele realmente funciona? A boa notícia é que você pode eliminar essa preocupação de forma definitiva. Automatizar testes Python com GitHub Actions é a maneira mais rápida e eficiente de garantir que cada alteração no seu projeto seja validada automaticamente. Ao integrar o Continuous Integration (CI) diretamente no seu repositório, você transforma o seu fluxo de trabalho manual em uma esteira de produção profissional e segura.
O GitHub Actions é uma ferramenta de automação integrada ao GitHub que permite executar scripts sempre que um evento acontece, como um “push” ou um “pull request”. Para quem já utiliza testes unitários no Python, configurar essa automação é o próximo passo lógico para escalar a qualidade do software. Se você quer parar de testar tudo manualmente no terminal, este tutorial vai te mostrar como configurar tudo em apenas 5 minutos, utilizando padrões modernos da indústria.
O que é o GitHub Actions e por que usar com Python?
O GitHub Actions é um serviço de integração e entrega contínua (CI/CD). Imagine que ele é um robô que vive no seu repositório. Toda vez que você sobe um novo código, esse robô cria um computador virtual temporário, instala o Python, baixa as suas dependências e executa os comandos que você definiu. Se algo estiver errado, ele te avisa imediatamente por e-mail ou com um ícone vermelho ao lado do seu “commit”.
Isso é fundamental porque evita o famoso “na minha máquina funciona”. Como o teste roda em um ambiente limpo e isolado, você tem a certeza de que o código é portável. Além disso, essa prática é um padrão exigido em grandes empresas de tecnologia, conforme documentado em portais de referência como a Wikipédia sobre Integração Contínua.
Preparando o ambiente local para a automação
Antes de configurarmos o robô do GitHub, precisamos garantir que o nosso código Python tenha testes válidos e um arquivo de dependências limpo. O GitHub Actions precisa saber quais bibliotecas instalar para rodar o seu script. Geralmente, usamos um arquivo chamado requirements.txt para listar essas bibliotecas.
Se você está começando agora, é essencial que seu projeto esteja organizado dentro de um ambiente virtual venv no Python. Isso ajuda a capturar exatamente as versões das bibliotecas que você está usando sem poluir o sistema operacional global. Sem um ambiente isolado, você pode enfrentar o erro ModuleNotFoundError quando o GitHub tentar rodar seu código e não encontrar as ferramentas necessárias.
Criando os testes unitários
Vamos criar uma pasta chamada tests e um arquivo chamado test_calculos.py dentro dela. Usaremos a biblioteca pytest, que é o padrão da indústria pela sua simplicidade e poder. O objetivo aqui é ter algo que o GitHub Actions possa executar e verificar se o resultado é “pass” (sucesso) ou “fail” (falha).
# Exemplo simples de teste para validar a automação
def soma(a, b):
return a + b
def test_soma_positiva():
assert soma(2, 3) == 5
def test_soma_negativa():
assert soma(-1, -1) == -2Configurando o Workflow do GitHub Actions
Para automatizar testes Python com GitHub Actions, precisamos criar um arquivo de configuração no formato YAML. Este arquivo deve ficar obrigatoriamente dentro de uma pasta específica no seu repositório chamada .github/workflows/. O nome do arquivo pode ser qualquer um, como main.yml ou testes.yml.
Este arquivo YAML contém as “receitas” de como o servidor do GitHub deve se comportar. Ele define o sistema operacional (ex: Ubuntu), a versão do Python e os comandos de terminal. É importante entender a identação no Python e também nesses arquivos YAML, pois um espaço errado pode impedir a execução do script.
Estrutura básica do arquivo .yml
Aqui está a estrutura de uma etapa de configuração que define o nome do processo e quando ele deve ser disparado. Usaremos o evento push, o que significa que cada vez que você enviar código para o GitHub, os testes serão iniciados automaticamente.
name: CI de Testes Python
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Configurar Python
uses: actions/setup-python@v4
with:
python-version: '3.10'Automatize testes Python com GitHub Actions passo a passo
Agora que definimos a máquina virtual, precisamos adicionar as etapas para instalar dependências e rodar o pytest. Se o seu projeto lida com automação pesada, como python para automação de rotinas, essa configuração garante que novos scripts não quebrem as funcionalidades antigas do seu servidor.
Instalação de Dependências
No arquivo YAML, adicionamos uma etapa para ler o seu requirements.txt. Caso você use ferramentas mais modernas, pode também resolver dependências com Poetry, mas para este guia de 5 minutos, o pip tradicional é mais direto.
- name: Instalar dependências
run: |
python -m pip install --upgrade pip
pip install pytest
if [ -f requirements.txt ]; then pip install -r requirements.txt; fiExecução dos Testes
A última parte da nossa automação é o comando que realmente executa o teste. Se o comando pytest encontrar algum erro no seu código, ele retornará um código de falha para o runner do GitHub, marcando a sua automação como malsucedida. Isso é ótimo para manter a integridade conforme explicado na documentação oficial do GitHub Actions.
- name: Testar com pytest
run: |
pytestCódigo Completo do Projeto
Abaixo, você encontra o conteúdo completo que deve ser colocado dentro do arquivo .github/workflows/python-app.yml no seu repositório. Certifique-se de que seu código Python principal e sua pasta de testes estejam na raiz do projeto para que o runner consiga localizá-los corretamente.
# Nome do Workflow
name: Python Package e Testes
# Eventos que disparam a automação
on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
jobs:
testes_python:
# Escolha do sistema operacional
runs-on: ubuntu-latest
steps:
# Passo 1: Baixar o código do repositório para o runner
- uses: actions/checkout@v3
# Passo 2: Configurar a versão do Python desejada
- name: Set up Python 3.10
uses: actions/setup-python@v4
with:
python-version: "3.10"
# Passo 3: Cache de dependências para acelerar execuções futuras
- name: Instalar dependências
run: |
python -m pip install --upgrade pip
pip install pytest
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
# Passo 4: Executar a suíte de testes
- name: Executar testes com Pytest
run: |
pytestDicas avançadas para workflows mais rápidos
Se o seu projeto crescer e você começar a sentir que o python está lento na execução do CI, você pode otimizar as Actions. Uma técnica comum é usar o sistema de cache do GitHub para não precisar baixar as bibliotecas do zero em cada execução. Isso economiza tempo e largura de banda do servidor.
Outra prática importante é rodar testes em múltiplas versões do Python simultaneamente (Matrix Build). Isso garante que quem usa Python 3.8 tenha a mesma experiência de quem usa a versão 3.12. Se o seu projeto for um pacote público, esse cuidado é o que diferencia amadores de desenvolvedores sêniores que dominam todos os tipos de dados em Python e suas compatibilidades.
“A automação não serve apenas para encontrar erros, mas para dar ao desenvolvedor a confiança necessária para inovar rápido.”
Gerenciando falhas nos testes automatizados
Quando um teste falha no GitHub Actions, você não precisa entrar em pânico. O logs do console mostram exatamente onde a asserção deu erro. Muitas vezes, o erro pode ser um simples erro de sintaxe que passou despercebido no editor local ou um problema de caminho de arquivos.
Se você estiver manipulando arquivos de texto ou logs no CI, lembre-se de conferir se o caminho está correto, pois o GitHub roda no Linux. Desenvolvedores acostumados com Windows podem esquecer que as barras de diretório são diferentes, o que pode causar um erro de FileNotFoundError durante a automação.
Conclusão e Próximos Passos
Automatizar testes Python com GitHub Actions é um divisor de águas na carreira de qualquer programador. Além de trazer segurança técnica, demonstra um alto nível de maturidade profissional. Agora que você tem a base da Integração Contínua funcionando, por que não explorar como criar um pacote pip instalável? Você poderá integrar o build do seu pacote diretamente com as Actions, automatizando inclusive a publicação no PyPI toda vez que criar uma nova versão.
Perguntas Frequentes
O GitHub Actions é gratuito para repositórios privados?
Sim, o GitHub oferece um plano gratuito substancial de minutos por mês para repositórios privados, enquanto para repositórios públicos o uso é ilimitado e gratuito.
Preciso pagar para usar o pytest no GitHub?
Não, o pytest é uma biblioteca de código aberto e o GitHub apenas executa o comando que você define, sem custos adicionais pelo software utilizado.
Como executo testes que precisam de banco de dados?
Você pode usar “Service Containers” no arquivo YAML para subir instâncias de bancos de dados como PostgreSQL ou Redis diretamente no ambiente do GitHub.
Posso rodar o GitHub Actions localmente?
Oficialmente não, mas existem ferramentas da comunidade como o ‘act’ que permitem simular o ambiente de Actions na sua própria máquina.
O que fazer se o Python do GitHub for diferente do meu?
Basta alterar a chave ‘python-version’ no seu arquivo YAML para a versão exata que você utiliza localmente em seu projeto.
Como vejo o resultado dos testes?
No seu repositório do GitHub, clique na aba ‘Actions’. Lá aparecerá uma lista de todas as execuções, onde você pode clicar e ver os logs detalhados.
Posso esconder senhas ou chaves de API nos testes?
Sim, você deve usar os ‘GitHub Secrets’. Você cadastra a chave nas configurações do repositório e a chama no YAML como uma variável de ambiente.
O GitHub Actions funciona com Django ou Flask?
Perfeitamente. Você só precisa configurar as variáveis de ambiente necessárias e o comando de teste específico (como ‘python manage.py test’ no Django).
Comece a integrar essa automação hoje mesmo e verá como sua produtividade e a qualidade do seu código darão um salto gigantesco. Boa codificação!
