Como Escrever o Melhor Caso de Testes em Gherkin: Um Guia Prático e Completo
Aprenda a escrever cenários Gherkin declarativos, reutilizáveis e livres de acoplamento de UI usando Dado, Quando, Então, Contexto e Esquema do Cenário.
A linguagem Gherkin é uma das ferramentas mais poderosas para alinhar Produto, Desenvolvimento e Qualidade em torno de regras de negócio claras. Porém, na prática cotidiana de muitas squads, arquivos .feature acabam transformados em longos roteiros imperativos cheios de cliques, seletores de tela e passos duplicados que ninguém consegue manter.
Neste guia prático e completo, você vai dominar as boas práticas da engenharia de qualidade para escrever casos de teste em Gherkin limpos, declarativos e prontos para automação.
O Que É Gherkin e Qual Seu Verdadeiro Objetivo?
Gherkin é uma linguagem estruturada, legível por humanos e interpretável por ferramentas de automação (como Cucumber, SpecFlow, Behave e Playwright-BDD). Seu propósito primário não é descrever cliques na interface, e sim registrar comportamentos observáveis do domínio de negócio como documentação viva.
As palavras-chave essenciais em português (# language: pt) são:
Funcionalidade(Feature): Descreve o épico ou módulo de negócio e seu valor para o usuário.Contexto(Background): Pré-condições comuns executadas antes de todos os cenários daquele arquivo.Cenário(Scenario): Um exemplo concreto e determinístico de uma regra de negócio.Esquema do Cenário+Exemplos(Scenario Outline): Execução orientada a dados (Data-Driven) para validar partições de equivalência e valores limite sem repetir passos.Dado(Given): Coloca o sistema em um estado inicial conhecido (pré-condição).Quando(When): Representa a ação principal ou evento disparado pelo ator.Então(Then): Verifica o resultado esperado e as mudanças de estado geradas.E/Mas(And / But): Conectores que mantêm a fluidez sem repetir palavras-chave.
Regra de Ouro: Estilo Declarativo vs. Estilo Imperativo
O erro número um em Gherkin é acoplar o cenário a detalhes de tela (botões, inputs, URLs). Quando o time de UX redesenha o formulário, dezenas de arquivos .feature quebram sem que a regra de negócio tenha mudado.
Anti-padrão Imperativo (Evite)
# language: pt
Cenário: Bloqueio de cartão por atraso
Dado que acesso a URL "/login"
E digito "cliente@email.com" no campo "#input-email"
E digito "Senha@123" no campo "#input-password"
E clico no botão "Entrar"
Quando navego até a aba "Faturas"
E o sistema roda o job das 00h00 no 5º dia após o vencimento
Então aparece um banner vermelho "#alert-bloqueio" na tela
Padrão Declarativo Profissional (Recomendado)
# language: pt
Funcionalidade: Gestão de bloqueio preventivo de cartão de crédito por inadimplência
Como área de Risco de Crédito
Quero aplicar regras graduais de restrição após o vencimento da fatura
Para reduzir a inadimplência preservando clientes que pagam o valor mínimo
Contexto:
Dado que o cliente possui um cartão de crédito ativo com limite disponível
Cenário: Enviar alerta preventivo no 3º dia de atraso sem pagamento
Dado que a fatura fechada de "R$ 1.500,00" está vencida há 3 dias sem pagamentos registrados
Quando o processamento diário de cobrança é executado
Então o cliente deve receber uma notificação push alertando sobre o bloqueio iminente
E o cartão deve permanecer habilitado para compras à vista e parceladas
Cenário: Bloquear cartão integralmente no 5º dia de atraso sem pagamento mínimo
Dado que a fatura fechada de "R$ 1.500,00" com mínimo de "R$ 225,00" está vencida há 5 dias
E nenhum pagamento igual ou superior ao mínimo foi compensado
Quando o processamento diário de cobrança é executado
Então o status do cartão deve ser alterado para "Bloqueado por Atraso"
E novas transações de compra devem ser recusadas
Usando Esquema do Cenário para Análise de Valor Limite
Sempre que uma regra envolver faixas numéricas, prazos, alçadas ou matrizes de permissão, utilize Esquema do Cenário para cobrir abaixo do limite, exatamente no limite e acima do limite com máxima concisão:
# language: pt
Esquema do Cenário: Regra de suspensão de parcelamento conforme valor pago na fatura em atraso
Dado que o cliente possui uma fatura vencida há 5 dias no valor total de <valor_total> e mínimo de <valor_minimo>
Quando é compensado um pagamento no valor de <valor_pago>
Então o status geral do cartão deve ser <status_cartao>
E a permissão para novas compras parceladas deve ser <compras_parceladas>
Exemplos:
| valor_total | valor_minimo | valor_pago | status_cartao | compras_parceladas |
| R$ 1.000,00 | R$ 150,00 | R$ 0,00 | Bloqueado | Suspensa |
| R$ 1.000,00 | R$ 150,00 | R$ 149,99 | Bloqueado | Suspensa |
| R$ 1.000,00 | R$ 150,00 | R$ 150,00 | Ativo | Suspensa |
| R$ 1.000,00 | R$ 150,00 | R$ 999,99 | Ativo | Suspensa |
| R$ 1.000,00 | R$ 150,00 | R$ 1.000,00| Ativo | Liberada |
Observe como 5 linhas na tabela Exemplos testam com precisão cirúrgica os centavos limítrofes (R$ 149,99 vs R$ 150,00 e R$ 999,99 vs R$ 1.000,00), prevenindo bugs clássicos de operadores < versus <= no backend.
5 Princípios para Manter Suítes Gherkin Escaláveis
- Um único comportamento por cenário: Evite encadear
Quando ... Então ... Quando ... Então ...no mesmo cenário. Se você tem múltiplos eventos independentes, divida em cenários distintos. - Terceira pessoa ou linguagem ubíqua consistente: Padronize o vocabulário do domínio com POs e desenvolvedores para reutilizar Step Definitions existentes.
- Cenários independentes entre si: O
Cenário 2nunca deve depender de dados deixados em memória peloCenário 1. - Use Tags estratégicas (
@smoke,@critico,@regressao): Facilite a execução seletiva em pipelines de Pull Request versus nightly builds. - Mantenha o
Contextoenxuto: Se umContextoultrapassa 3 ou 4 linhas, ele esconde complexidade excessiva ou mistura regras que pertencem a funcionalidades separadas.
Transforme Histórias de Usuário em Gherkin + Step Definitions Instantaneamente
Escrever cenários declarativos com tabelas de valor limite e depois codificar os Step Definitions em TypeScript, Java, Python ou JavaScript leva poucos segundos no teste.ai v.3.0 — com salvamento automático em projetos e exportação direta para sua esteira de QA.
Plataforma de QA End-to-End • teste.ai v.3.0
Pare de escrever planilhas e scripts de teste do zero.
Teste gratuitamente o teste.ai v.3.0 agora mesmo: receba 5 gerações completas na hora (sem cartão de crédito), organize suítes em nuvem e exporte relatórios executivos em PDF e Excel.