BDD & Gherkin10 min de leitura

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.

Por Engenharia de Qualidade teste.ai · Paiva Software Engineering

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

  1. 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.
  2. Terceira pessoa ou linguagem ubíqua consistente: Padronize o vocabulário do domínio com POs e desenvolvedores para reutilizar Step Definitions existentes.
  3. Cenários independentes entre si: O Cenário 2 nunca deve depender de dados deixados em memória pelo Cenário 1.
  4. Use Tags estratégicas (@smoke, @critico, @regressao): Facilite a execução seletiva em pipelines de Pull Request versus nightly builds.
  5. Mantenha o Contexto enxuto: Se um Contexto ultrapassa 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.

Continue aprofundando sua Engenharia de Qualidade