terraform-test

Visão geral do skill terraform-test

terraform-test é um skill de testes de Terraform para escrever cenários .tftest.hcl, validar o comportamento de módulos e checar a lógica de infraestrutura sem adivinhar sintaxe ou fluxo de trabalho. Ele é ideal para engenheiros que querem um guia prático de terraform-test para arquivos de teste, blocos run, assertions e mocks, especialmente quando o objetivo é tornar mudanças em Terraform mais seguras antes do merge.

Para que o terraform-test é mais útil

Use o skill terraform-test quando você precisa verificar outputs, argumentos de recursos, lógica condicional ou comportamento específico por ambiente. Ele é especialmente útil para autores de módulos, times de plataforma e revisores que preferem checagens repetíveis em vez de inspeção manual de plan.

Onde ele se encaixa no fluxo de trabalho de Terraform

Esse skill entra depois de terraform init e terraform validate, e antes ou junto da execução no CI. Ele ajuda a transformar uma intenção de configuração ainda solta em casos de teste explícitos, que podem rodar em modo plan ou apply, dependendo do que você precisa comprovar.

Principais diferenciais

O principal valor do terraform-test é colocar testes nativos de Terraform no centro, em vez de conselho genérico de prompt. Ele cobre estrutura de teste, padrões de assertion, uso de mock provider para Terraform 1.7+ e execução amigável ao CI, para que a pessoa saia mais rápido de “acho que isso deveria funcionar” para um arquivo de teste concreto.

Como usar o skill terraform-test

Instale e abra os arquivos certos

Instale com npx skills add hashicorp/agent-skills --skill terraform-test. Depois, leia primeiro SKILL.md, em seguida references/EXAMPLES.md para ver um padrão completo de suíte de testes, references/MOCK_PROVIDERS.md para testes unitários com mocks e references/CI_CD.md quando você precisar de execução no pipeline.

Dê ao skill um objetivo testável

Prompts fortes nomeiam o módulo, o comportamento e o resultado esperado. Por exemplo: “Escreva um arquivo .tftest.hcl para um módulo de VPC que verifique a quantidade de subnets públicas, o roteamento das subnets privadas e os valores de output em modo plan.” Isso é melhor do que “adicione testes”, porque o skill consegue mapear o pedido imediatamente para blocos run e assertions.

Use a forma certa de entrada

O skill funciona melhor quando você informa a versão do Terraform, as restrições dos providers, os inputs do módulo e o que precisa ser provado. Se quiser usar mock providers, diga isso e confirme Terraform 1.7+; se quiser cobertura real de integração, inclua a cloud de destino e quaisquer credenciais ou premissas de CI.

Comece com um fluxo, não com um arquivo em branco

Um fluxo prático de uso do terraform-test é: identificar o comportamento, escolher plan ou apply, decidir se mocks são permitidos e depois escrever um bloco run por cenário. Leia references/EXAMPLES.md para entender o layout geral dos testes e então adapte variáveis, assertions e nomes de arquivo às convenções do seu repositório.

FAQ do skill terraform-test

O terraform-test serve só para testes de módulo?

Não. Ele é mais forte para módulos, mas também ajuda com configurações de raiz, validação de outputs, checagens de comportamento de provider e execução de testes no CI. Se você precisa de verificação nativa de Terraform, esse skill é uma boa opção.

Quando não devo usar terraform-test?

Evite quando você só precisa de uma explicação pontual de terraform plan ou quando sua stack não consegue executar testes de Terraform no CI. Também evite padrões com mock provider se você estiver em Terraform abaixo da versão 1.7, porque essa parte do fluxo não se aplica.

É mais fácil usar terraform-test do que escrever prompts na mão?

Normalmente sim, porque ele restringe a tarefa à sintaxe real de teste e à estrutura de arquivos do Terraform. Um prompt genérico pode gerar orientação ampla; o skill terraform-test é voltado para criar casos de teste utilizáveis, especialmente para blocos run e assertions.

O terraform-test funciona para tarefas de Code Generation?

Sim, terraform-test para Code Generation é útil quando você quer arquivos de teste gerados que combinem com a interface e o comportamento esperado de um módulo. O principal limite é que os testes gerados ainda precisam de inputs reais, assertions realistas e uma decisão clara entre cobertura de plan e apply.

Como melhorar o skill terraform-test

Forneça fatos concretos sobre o módulo

Entradas melhores levam a testes melhores. Inclua nomes de variáveis, outputs obrigatórios, nomes de recursos, aliases de provider e quaisquer invariantes que importam para você, como “public subnets devem ser 2” ou “instance type deve ter default t3.micro.”

Diga ao skill o que pode ser mockado

O ganho de qualidade mais comum é deixar claro se as chamadas ao provider devem ser mockadas ou reais. Em decisões de instalação do terraform-test, isso importa porque mocks reduzem a necessidade de credenciais e aceleram testes unitários, mas só funcionam em modo plan e podem esconder comportamento específico do provider.

Separe casos de unit, integration e regression

Peça cenários de teste distintos em vez de um arquivo grande quando os comportamentos forem diferentes. Um guia de terraform-test bem montado normalmente divide checagens rápidas em modo plan de testes de integração mais lentos, o que simplifica o CI e deixa o sinal de falha mais fácil de ler.

Itere a partir das falhas, não das suposições

Depois da primeira execução, refine as assertions que ficaram fracas demais, amplas demais ou presas a valores instáveis. Se um teste falhar em atributos computados, peça uma checagem mais estável; se a mudança no módulo for intencional, atualize a condição esperada em vez de ampliar o teste até ele deixar de significar alguma coisa.