Execução de testes de Shell em pipelines de integração contínua

Scripts de Shell são código — e, como todo código, merecem barreiras automatizadas de qualidade. Sem CI, um erro de digitação em um script de implantação pode chegar silenciosamente à produção e causar uma interrupção às 3h da manhã.

Uma pipeline de CI sólida para projetos Bash impõe duas coisas em cada solicitação de pull:

• Análise estática por meio do ShellCheck — detecta erros de sintaxe, padrões inseguros e problemas de portabilidade POSIX antes mesmo de o script ser executado.
• Testes unitários/de integração por meio do Bats (Bash Automated Testing System) — executa suas funções e verifica se o comportamento está correto.

Juntos, eles formam uma rede de segurança que torna a refatoração mais tranquila e acelera a integração de novos colaboradores. Nesta lição, as duas ferramentas são integradas ao GitHub Actions, a plataforma gratuita de CI mais comum para projetos de código aberto e de equipes pequenas.

GitHub Actions é uma CI/CD orientada a eventos integrada ao GitHub. Um fluxo de trabalho é um arquivo YAML armazenado em .github/workflows/. Ele é acionado por eventos (push, pull_request etc.) e executa tarefas em executores hospedados.

Conceitos principais que precisa conhecer:

• on: — o acionador (por exemplo, push, pull_request)
• jobs: — unidades paralelas de trabalho, cada uma em uma VM nova
• steps: — comandos de Shell sequenciais ou ações reutilizáveis dentro de uma tarefa
• runs-on: — a imagem do executor (usamos ubuntu-latest)

Os arquivos de fluxo de trabalho precisam ser confirmados no repositório. O GitHub os detecta automaticamente — nenhuma configuração externa é necessária.

O ShellCheck vem pré-instalado nos executores ubuntu-latest, portanto, na maioria dos casos, não é necessário executar nenhuma etapa de instalação. No entanto, a versão pré-instalada pode estar atrasada em relação à versão mais recente. Para obter compilações reproduzíveis, fixe uma versão específica.

Duas estratégias de instalação:

• Usar o binário pré-instalado — é a opção mais simples e suficiente para a maioria dos projetos.
• Instalar uma versão fixada por meio do arquivo tarball oficial da versão do GitHub — garante a mesma versão do analisador localmente e na CI.

A etapa abaixo mostra a abordagem com versão fixada, usando uma cadeia de versão fixa armazenada como variável de ambiente, o que transforma as atualizações em uma alteração de uma linha.

Após a instalação, é necessário ter uma etapa que descubra e analise todos os scripts de Shell no repositório. Use find para localizar os arquivos e, em seguida, encaminhe-os para shellcheck.

Opções importantes:

• -e SC2034 — exclui uma regra específica (use com moderação e acompanhada de um comentário).
• --severity=warning — falha somente em avisos ou problemas mais graves (ignorando sugestões de estilo).
• -x — segue diretivas source para analisar também os arquivos incluídos.

Se shellcheck encontrar qualquer problema, ele termina com código diferente de zero, o que faz a etapa da CI falhar automaticamente — não é necessária lógica adicional.

O Bats (Bash Automated Testing System) é uma estrutura de testes para Bash compatível com TAP. Cada arquivo de teste é um arquivo .bats que contém blocos @test.

Um teste é aprovado quando seu corpo termina com código 0 e reprovado quando termina com código diferente de zero. O Bats fornece variáveis e funções auxiliares:

• $status — código de saída do último comando run.
• $output — saída combinada de stdout+stderr do último comando run.
• $lines — matriz de linhas da saída.
• run <cmd> — executa um comando sem reprovar o teste quando a saída é diferente de zero.

O auxiliar run é essencial — sem ele, um comando com falha interromperia o teste antes que pudesse inspecionar $status.

A maneira padrão de adicionar o Bats a um projeto é como um submódulo do Git. Isso fixa um commit específico, mantém a versão do executor idêntica à do desenvolvimento local e evita a dependência de gerenciadores de pacotes.

Execute estes comandos uma vez localmente e depois confirme o resultado:

• git submodule add https://github.com/bats-core/bats-core test/bats
• git submodule add https://github.com/bats-core/bats-support test/test_helper/bats-support
• git submodule add https://github.com/bats-core/bats-assert test/test_helper/bats-assert

Na CI, restaure os submódulos com actions/checkout@v4 e a opção submodules: recursive. A etapa abaixo mostra a configuração completa do checkout.

Quando o Bats estiver disponível (por meio de um submódulo ou da instalação de um pacote), executar os testes exige um único comando. Aponte-o para um diretório, e o Bats descobrirá recursivamente todos os arquivos .bats com a opção --recursive.

A opção --formatter tap gera a saída no formato TAP (Test Anything Protocol), que muitos sistemas de CI analisam para gerar relatórios de testes. O formatador pretty padrão é melhor para leitura humana nos registros brutos.

Use --timing para identificar precocemente testes lentos — um teste que leva mais de 5 segundos geralmente indica uma chamada de rede indesejada ou um mock ausente.

Agora, combine tudo em um único arquivo de fluxo de trabalho pronto para produção. Estas são as boas práticas aplicadas:

• Duas tarefas separadas (lint e test) são executadas em paralelo, proporcionando um retorno mais rápido.
• A tarefa test declara needs: lint, portanto os testes só são executados depois que a análise é aprovada — evitando desperdiçar minutos do executor com código obviamente quebrado.
• Versões fixadas das ações (@v4) evitam falhas inesperadas causadas por atualizações upstream.
• Um bloco permissions: restringe o token do fluxo de trabalho ao mínimo necessário.

Quando os auxiliares do Bats ou outras ferramentas são instalados por um gerenciador de pacotes dentro do fluxo de trabalho, o armazenamento em cache acelera significativamente as execuções seguintes. O GitHub Actions fornece a ação actions/cache para isso.

Pontos principais para um armazenamento em cache eficaz:

• Use uma chave de cache que inclua o sistema operacional, o nome da ferramenta e um hash do arquivo de bloqueio — assim, o cache é invalidado automaticamente quando as dependências mudam.
• Um fallback restore-keys permite que o fluxo de trabalho use um cache desatualizado em vez de começar do zero quando não encontra uma correspondência.
• Para submódulos do Git, o armazenamento em cache raramente é necessário, pois o checkout de submódulos é rápido. O cache é mais valioso para instalações de npm, pip ou de ferramentas compiladas.

Uma fluxo de trabalho de CI que não bloqueia mesclagens é, no melhor dos casos, apenas consultivo. As regras de proteção de ramificações do GitHub transformam suas verificações em barreiras obrigatórias.

Para configurá-las: acesse Settings → Branches → Add rule para main e habilite:

• Require status checks to pass before merging — selecione ShellCheck e Bats Tests pelo nome.
• Require branches to be up to date before merging — impede que uma PR aprovada em uma base desatualizada integre código quebrado.
• Do not allow bypassing the above settings — aplica as regras inclusive aos administradores do repositório.

Com essas regras em vigor, o único caminho para a mesclagem é uma PR com todas as tarefas da CI aprovadas — exatamente a rede de segurança desejada.

Quando uma execução da CI falha, o ciclo de correção mais rápido é reproduzir a falha localmente antes de enviar outra confirmação. Duas técnicas:

• Execute os comandos exatos da etapa com falha no seu terminal — a CI executa um Shell simples, portanto os comandos podem ser reproduzidos por copiar e colar.
• Use act — uma ferramenta que executa fluxos de trabalho do GitHub Actions localmente dentro do Docker, oferecendo a correspondência mais próxima possível com o ambiente do executor hospedado.

Uma fonte comum de falhas que ocorrem apenas na CI é a incompatibilidade entre versões de ferramentas no seu Mac (por exemplo, find BSD no macOS em comparação com find GNU no Ubuntu). Sempre teste com opções --posix ou use act para executar localmente a imagem do Ubuntu.

Teste sua compreensão da integração do ShellCheck e do Bats ao GitHub Actions.

Nesta lição, você criou uma pipeline de CI completa para projetos Bash usando o GitHub Actions. Veja o que foi abordado:

• Fundamentos do GitHub Actions — o YAML do fluxo de trabalho fica em .github/workflows/, é acionado por push e pull_request e executa tarefas em executores ubuntu-latest.
• ShellCheck — pré-instalado nos executores Ubuntu; use find para descobrir scripts e --severity=warning -x como uma barreira prática de análise.
• Bats via submódulo — fixe o bats-core e os auxiliares como submódulos do Git; restaure-os na CI com submodules: recursive na ação de checkout.
• Ordenação das tarefas — use needs: para que os testes sejam executados somente depois da aprovação da análise, mantendo um retorno rápido e evitando desperdício de processamento.
• Proteção de ramificações — imponha verificações de status nas configurações do GitHub para que nenhuma PR seja integrada sem uma CI aprovada.
• Reprodução local — copie os comandos da CI diretamente para o terminal ou use act para depurar falhas sem confirmações adicionais.

Com essa pipeline em vigor, cada alteração no Shell é validada automaticamente antes de chegar à sua ramificação principal.