Given-When-Then: o que é, estrutura de cenários e exemplos

O que é Given-When-Then?

Given-When-Then é um padrão de descrição de comportamento, formulado pela primeira vez por Dan North em 2006 como parte da metodologia Behavior-Driven Development. O padrão resolve o problema de descrições não estruturadas de cenários de teste, que frequentemente contêm uma mistura de pré-condições, ações e verificações em ordem arbitrária.

A ideia principal do padrão é a separação de responsabilidades entre três blocos. Cada bloco é responsável exatamente por um aspecto do cenário: estado antes, evento durante e verificação depois. Isso torna o cenário legível, verificável e automatizável. De acordo com um estudo dos desenvolvedores do framework Cucumber (2024), cenários que seguem estritamente o padrão Given-When-Then exigem 42% menos tempo para serem compreendidos por um novo membro da equipe.

Origem do padrão

Dan North pegou emprestada a ideia da estrutura de três partes da formulação de testes em TDD e da metodologia Test-by-Example (criada por Brian Marick). Marick propôs descrever os requisitos através de exemplos (examples) que simultaneamente servem como testes. Given-When-Then formalizou essa ideia, transformando exemplos não estruturados em um padrão repetível.

Área de aplicação

O padrão Given-When-Then não se aplica apenas em cenários BDD com Gherkin, mas também em testes unitários comuns com JUnit, XCTest e outros frameworks. Comentários no código que dividem o teste em três blocos são uma prática comum para melhorar a legibilidade da base de testes. O Google recomenda essa abordagem em seu livro «Software Engineering at Google» (2020).

Estrutura dos três blocos

Cada bloco do Given-When-Then tem uma semântica estritamente definida e regras de preenchimento. A violação dessas regras produz cenários difíceis de automatizar ou entender.

Given: pré-condições

O bloco Given descreve o estado do sistema antes de executar a ação sob teste. Inclui: objetos existentes (usuário, pedido, configurações), estados ativos (autenticado, conectado à rede) e valores iniciais de dados. Cada Given deve ser verificável — se o estado do sistema não corresponder ao Given, o cenário deve ser pulado ou o ambiente de teste preparado previamente.

When: ação

O bloco When descreve o único evento que inicia o comportamento sob teste. Pode ser uma chamada de método, um clique em botão, o recebimento de uma notificação ou resposta do servidor. A regra chave é um When por cenário. Se for necessário verificar uma sequência de ações, crie cenários separados, não uma cadeia de When.

// Given: criamos dados de teste
val user = User(email = "test@example.com", balance = 500.0)
val product = Product(price = 150.0)

// When: executamos a ação
val result = PurchaseUseCase().buy(user, product)

// Then: verificamos o resultado
assertEquals(PurchaseResult.Success, result)
assertEquals(350.0, user.balance)

Then: resultado esperado

O bloco Then verifica se o sistema transitou para o estado esperado. Isso inclui: valores retornados, mudanças no estado de objetos, chamadas a serviços externos (via verificação de mocks) e alterações na UI. Cada bloco Then pode conter várias verificações, mas todas se referem a uma única ação.

Given-When-Then e Arrange-Act-Assert

Given-When-Then e Arrange-Act-Assert (AAA) são duas variantes do mesmo padrão de três partes, mas com públicos-alvo diferentes. Entender suas diferenças ajuda a escolher o formato certo para cada tarefa.

Quando usar Given-When-Then

O padrão Given-When-Then é ideal para cenários discutidos com o cliente ou analista: critérios de aceitação de funcionalidades, casos de uso, verificações de regressão. A sintaxe Gherkin permite escrever esses cenários sem conhecimento de programação.

Quando usar Arrange-Act-Assert

Arrange-Act-Assert é a escolha natural para testes unitários que verificam um método ou classe específica. O formato AAA não requer frameworks adicionais e funciona em qualquer linguagem de programação. Para desenvolvimento iOS, a Apple recomenda AAA na documentação do XCTest (2024).

Exemplos de cenários em Kotlin

Vejamos exemplos práticos de Given-When-Then em Kotlin para uma aplicação Android. O primeiro exemplo é um teste de carrinho de compras usando MockK. O segundo é um teste da lógica de notificações push.

Exemplo 1: carrinho de compras

class CartTest {
    fun `apply discount when total exceeds threshold`() {
        // Given
        val cart = Cart()
        cart.addItem(Item("Laptop", price = 1000.0))
        cart.addItem(Item("Mouse", price = 50.0))
        val discount = DiscountCalculator(0.1)

        // When
        val total = discount.applyIfEligible(cart)

        // Then
        assertEquals(945.0, total)
        assertTrue("Discount was not applied", total < 1050.0)
    }
}

Exemplo 2: notificações push com corrotinas

O segundo exemplo demonstra Given-When-Then com código assíncrono. Aqui Given define o estado do Firebase Cloud Messaging, When — o recebimento de uma notificação push, Then — a verificação do processamento.

class PushNotificationTest {
    fun `handle push notification when app in background`() = runTest {
        // Given
        val prefs = mockk<SharedPreferences>()
        every { prefs.getString("token", null) } returns "fcm-token-abc"
        val handler = PushHandler(prefs)

        // When
        val data = RemoteMessage().apply {
            putData("type", "order_update")
            putData("order_id", "123")
        }
        val result = handler.handleNotification(data)

        // Then
        assertEquals(NotificationAction.OpenOrder("123"), result)
    }
}

Exemplo 3: cenário Gherkin para autenticação

O terceiro exemplo é um cenário BDD em Gherkin mostrando Given-When-Then no contexto de testes de aceitação:

Feature: User Authorization
  Scenario: User cannot login with expired token
    Given the user has an expired refresh token
    When they try to access the protected profile screen
    Then they should see the login screen
    And the app should clear all cached data

Melhores práticas para escrever cenários

A aplicação eficaz do Given-When-Then requer seguir várias práticas comprovadas. Elas garantem legibilidade, mantenibilidade e automatização dos cenários.

Um When por cenário

Regra estrita: um cenário — uma ação. Se for necessário verificar uma sequência de vários When, crie vários cenários onde o resultado do anterior se torna pré-condição do próximo. Isso torna o cenário atômico e compreensível.

Evite dados concretos no Given

Given deve descrever a essência, não números concretos. Em vez de «Given o usuário Ivanov com saldo de 500 rublos» — «Given um usuário com saldo suficiente». Os dados concretos são transferidos para o Scenario Outline com uma tabela de Examples. Isso torna o cenário universal e reutilizável.

• Escreva Then como afirmações mensuráveis — «o usuário deve ver a tela de login», não «o usuário deve ser redirecionado»
• Use And para passos do mesmo tipo — se vários Given forem necessários, combine-os com And, não crie um segundo Given
• Não misture níveis de abstração — Given-When-Then deve estar no mesmo nível: ou de negócio, ou técnico, mas não misturado
• Documente a razão do cenário — um comentário no início do arquivo .feature com a descrição da regra de negócio ajuda no contexto

Given-When-Then no pipeline CI/CD

A integração de cenários Given-When-Then no pipeline de integração contínua os transforma de documentação em proteção contra regressões. Cada merge request em um projeto móvel executa automaticamente os cenários BDD e bloqueia a fusão se pelo menos um cenário falhar.

Execução automática de cenários

Cenários BDD com Cucumber para Android são executados através da tarefa Gradle ./gradlew cucumber. Para iOS (Quick/Nimble) — através de xcodebuild test. Em sistemas CI (GitHub Actions, GitLab CI, Bitrise), os testes BDD são executados em emuladores ou dispositivos reais. O relatório é gerado em formato HTML compreensível para gerentes: cenários verdes — aprovados, vermelhos — falha com indicação do passo.

Documentação viva no repositório

Os arquivos .feature são armazenados no repositório junto ao código e passam por code review. O analista cria um merge request com novos cenários antes do início do desenvolvimento (BDD-first). O desenvolvedor escreve as definições de passos (step definitions) e a implementação para que esses cenários se tornem verdes. Quando todos os cenários passam — a funcionalidade está pronta. Esta abordagem, descrita no livro de Gojko Adzic «Specification by Example» (2011), transforma requisitos em um artefato executável.