Sintaxe Gherkin
Gherkin é uma linguagem de texto simples para descrever o comportamento do software. Arquivos de funcionalidade usam um formato estruturado de Given-When-Then que pode ser executado tanto por humanos quanto por ferramentas BDD.
Receita
Feature: Invoice creation
As a billing clerk
I want to create invoices
So that customers receive accurate bills
Scenario: Valid invoice
Given an authenticated billing clerk
When they create an invoice for 100.00 USD
Then the invoice status is "draft"
And the invoice id is not emptyQuando usar isso:
- Escrever critérios de aceitação como especificações executáveis
- Compartilhar cenários de teste com partes interessadas não técnicas
- Documentar o comportamento da API em formato legível por humanos
Exemplo Funcional
Feature: User registration
Users must register with a valid email before accessing the system.
Background:
Given the registration API is available
Scenario: Successful registration
Given no user exists with email "ada@example.com"
When a registration request is sent with:
| email | ada@example.com |
| password | SecurePass123 |
Then the response status is 201
And a confirmation email is queued
Scenario Outline: Invalid email rejected
Given no existing user conflicts
When a registration request is sent with email "<email>"
Then the response status is 422
Examples:
| email |
| not-an-email |
| @missing.com |
| empty |O que isso demonstra:
Featuredescreve a capacidade com formato de história de usuárioBackgroundé executado antes de cada cenário no arquivoScenarioé um único caso de teste com passos Given-When-ThenScenario Outline+Examplesparametrizam cenários
Mergulho Profundo
Palavras-chave
| Palavra-chave | Propósito |
|---|---|
| Feature | Agrupa cenários relacionados |
| Background | Configuração compartilhada para todos os cenários |
| Scenario | Exemplo de comportamento único |
| Scenario Outline | Cenário parametrizado |
| Given | Pré-condições (organizar) |
| When | Ação (agir) |
| Then | Resultado esperado (afirmar) |
| And / But | Continuação do tipo de passo anterior |
| Examples | Tabela de dados para Scenario Outline |
Tabelas de Dados
When the user submits:
| field | value |
| name | Ada |
| amount | 100 |Armadilhas
- Detalhes de implementação nos passos - "When I call POST /api/v2/invoices". Correção: descreva o comportamento: "When uma fatura é criada."
- Muitos passos por cenário - ilegível. Correção: máximo de 5-7 passos; extraia a configuração para Background.
- Scenario Outline com 50 exemplos - ônus de manutenção. Correção: mantenha os exemplos focados em casos de limite.
- Comentários como documentação - comentários desatualizados. Correção: os passos devem ser autoexplicativos; use tags para metadados.
- Mistura de idiomas - palavras-chave Gherkin devem ser em inglês (ou um cabeçalho
# language: fr). Correção: um idioma por projeto.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Docstrings do pytest | Especificações apenas para desenvolvedores | Especificações legíveis por partes interessadas necessárias |
| Exemplos OpenAPI | Documentação de contrato de API | Comportamento de fluxo de trabalho do usuário |
| Planos de teste Markdown | Exploração pré-automação | Testes executáveis necessários |
FAQs
Devo usar o formato de história de usuário?
Não, mas a descrição da Feature deve explicar quem se beneficia e por quê.
Quantos cenários por arquivo de feature?
5-15 é gerenciável. Divida features grandes em vários arquivos.
O que são tags?
Rótulos @smoke, @wip para filtragem: pytest --tags smoke.
Os passos podem ter várias linhas?
Sim, com docstrings (""") para argumentos de passo multilinhas.
Given vs When vs Then - estrito?
Given = estado, When = ação, Then = asserção. And/But continuam o tipo anterior.
Como escrevo cenários negativos?
Then o status da resposta é 403 ou Then o registro falha com "e-mail já em uso".
Background vs Given em cada cenário?
Background para configuração compartilhada entre todos os cenários. Given específico do cenário para pré-condições únicas.
Posso usar Gherkin para testes unitários?
Não recomendado. Gherkin é para comportamento em nível de aceitação. Use pytest para unidades.
O que é a palavra-chave Rule?
Gherkin 6+ agrupa cenários sob regras de negócios dentro de uma Feature.
Como lidar com datas em exemplos?
Use termos relativos nos passos ("hoje", "próxima segunda-feira") resolvidos nas definições de passo.
Relacionados
- Checklist de Decisão BDD - quando usar BDD
- Definições de Passo - conectando passos ao Python
- Configuração behave / pytest-bdd - configuração do projeto
- Gherkin para Código - implementando passos
Versões da Stack: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.