Simulação de comandos e criação de substitutos para ferramentas externas

Ao testar um script Bash que chama curl, aws, git ou qualquer ferramenta externa, você enfrenta um problema: as chamadas reais acessam a rede, modificam o estado, custam dinheiro ou simplesmente falham em um ambiente de integração contínua no qual essas ferramentas não estão instaladas.

Simular significa substituir o comando real por um falso que você controla. Seu falso (o stub) retorna uma saída e códigos de saída previsíveis, fazendo com que o teste seja rápido, isolado e reproduzível.

• Nenhum acesso à rede ou à nuvem é necessário
• Os testes são executados em milissegundos, em vez de segundos
• Você pode simular erros difíceis de provocar em sistemas reais
• Os pipelines de integração contínua permanecem limpos e sem dependências

O Bash oferece um mecanismo surpreendentemente simples para isso: basta colocar o seu binário falso em algum local anterior ao binário real no $PATH.

Quando o shell executa um comando como curl, ele pesquisa cada diretório em $PATH, da esquerda para a direita, e executa a primeira correspondência encontrada.

Isso significa que, se você colocar no início um diretório que contenha seu próprio script curl, o shell nunca chegará a /usr/bin/curl.

O padrão de substituição:

1. Crie um diretório temporário (seu diretório de binários simulados)
2. Grave um executável falso com o mesmo nome do comando real
3. Coloque esse diretório no início de PATH
4. Execute o script em teste — ele chamará sua simulação, não o binário real
5. Limpe o diretório temporário depois do teste

Isso funciona sem acesso de administrador, sem modificar arquivos do sistema e sem nenhum framework especial.

O padrão convencional usa mktemp -d para criar um diretório temporário isolado para suas simulações. Cada teste ou conjunto de testes recebe seu próprio diretório, evitando a contaminação entre testes.

Depois que o teste for concluído, remova o diretório com rm -rf. Usar um trap garante a limpeza mesmo quando o teste termina antecipadamente devido a um erro.

Uma simulação é simplesmente um arquivo executável com o mesmo nome do comando que você deseja substituir. Ela imprime a saída esperada pelo script em teste e termina com o código que você escolher.

Regras principais para simulações:

• O arquivo deve ser executável (chmod +x)
• A linha de shebang (#!/usr/bin/env bash) é obrigatória
• Mostre a saída que seu script real analisaria
• Use exit 0 para indicar sucesso e um valor diferente de zero para falhas simuladas

Agora vamos juntar tudo. Suponha que você tenha um script de implantação que chama curl para verificar um endpoint de integridade e termina com um erro se o serviço não estiver saudável. Você quer testar tanto o caminho de sucesso quanto o caminho de falha sem usar um servidor real.

Um dos usos mais valiosos dos stubs é simular falhas difíceis de reproduzir com ferramentas reais — tempos limite de rede, erros de permissão, disco cheio ou uma API remota que retorna um 500.

Para simular uma falha, basta fazer o stub sair com um código diferente de zero. Também pode escrever em stderr exatamente como o comando real faria, para que o tratamento de erros do seu script seja exercitado por completo.

Às vezes, precisa verificar não apenas o que seu script produz, mas também como ele chamou uma ferramenta externa — os argumentos que passou, quantas vezes ela foi chamada ou em que ordem. Um stub espião registra suas invocações em um arquivo.

Após o teste, seu ambiente de testes lê o arquivo de registro e verifica o conteúdo. Isso permite uma verificação em nível de argumentos sem nenhuma estrutura especial.

Um script real costuma chamar várias ferramentas externas. Pode criar stubs para todas elas no mesmo diretório STUB_BIN. Cada arquivo de stub é independente e pode retornar saídas e códigos de saída diferentes.

Mantenha os stubs mínimos: retorne apenas o que o script em teste realmente analisa. Não tente simular todas as opções — apenas o subconjunto usado pelo seu script.

Em casos simples, não precisa escrever arquivos. Pode definir uma função do shell com o mesmo nome do comando. Como as funções são resolvidas antes da busca externa em PATH, elas ganham prioridade automaticamente.

Esta é a abordagem mais rápida para testar scripts carregados com source. No entanto, os stubs de função só funcionam dentro do mesmo processo do shell — eles não ficam visíveis para subprocessos iniciados com bash -c explicitamente nem para processos executados em segundo plano. Nesses casos, use a abordagem baseada em arquivos.

Quando o script em teste inicia um subprocesso (por exemplo, bash script.sh ou um pipeline), os stubs de funções do shell definidos no processo pai não são herdados por padrão. Há duas opções:

• Use export -f function_name para exportar a função — ela ficará disponível para processos filho do bash
• Ou recorra a stubs baseados em arquivos em um diretório STUB_BIN, que sempre funcionam entre diferentes processos

export -f é elegante, mas funciona apenas com bash (não com sh nem com outros shells). Prefira stubs baseados em arquivos em ambientes de integração contínua poliglotas.

Ao usar o BATS (Sistema Automatizado de Testes do Bash), a configuração dos stubs deve ficar no gancho setup(), e a limpeza, em teardown(). O BATS redefine o ambiente entre os testes, portanto cada teste recebe um diretório de stubs novo.

Variáveis do BATS, como $BATS_TEST_TMPDIR, fornecem automaticamente um diretório temporário exclusivo para cada teste — use-o em vez de mktemp -d para manter o código mais limpo.

Teste sua compreensão sobre a simulação de comandos e os padrões de stubs no Bash.

Um desenvolvedor escreve um teste que define uma função do shell chamada aws para substituir o AWS CLI real. O teste funciona normalmente quando executado diretamente no terminal, mas, quando o pipeline de integração contínua executa o script em teste como bash deploy.sh, o stub é ignorado e o comando aws real é chamado.

Qual é a correção correta?

Você aprendeu o conjunto completo de técnicas para substituir comandos reais por falsificações controladas durante os testes de scripts Bash.

Principais técnicas abordadas:

• Precedência no PATH — crie um diretório STUB_BIN com mktemp -d, escreva nele arquivos de stub executáveis e coloque esse diretório no início de PATH
• Códigos de saída dos stubs — retorne 0 em caso de sucesso e valores diferentes de zero para simular falhas específicas (erros de rede, permissão negada etc.)
• Stubs espiões — acrescente os argumentos a um arquivo de registro dentro do stub para verificar como seu script chamou as ferramentas externas
• Vários stubs — coloque vários arquivos de stub no mesmo STUB_BIN para simular de uma só vez todo um ecossistema de dependências
• Stubs de função — defina uma função do shell com o mesmo nome de um comando para simulação no mesmo processo; use export -f para alcançar processos filho do bash
• Integração com BATS — use os ganchos setup()/teardown() e $BATS_TEST_TMPDIR para obter isolamento limpo em cada teste

Sempre use um trap '...' EXIT para garantir a limpeza dos stubs, independentemente do resultado do teste. Mantenha os stubs mínimos — retorne apenas o que seu script realmente analisa. Stubs baseados em arquivos são a opção mais portável para pipelines de integração contínua.