Given-When-Then : définition, structure des scénarios et exemples

Qu'est-ce que Given-When-Then ?

Given-When-Then est un modèle de description de comportement, formulé pour la première fois par Dan North en 2006 dans le cadre de la méthodologie Behavior-Driven Development. Ce modèle résout le problème des descriptions non structurées de scénarios de test, qui contiennent souvent un mélange de préconditions, d'actions et de vérifications dans un ordre arbitraire.

L'idée principale du modèle est la séparation des responsabilités entre trois blocs. Chaque bloc est responsable d'un seul aspect du scénario : l'état avant, l'événement pendant et la vérification après. Cela rend le scénario lisible, vérifiable et automatisable. Selon une étude des développeurs du framework Cucumber (2024), les scénarios qui suivent strictement le modèle Given-When-Then nécessitent 42% moins de temps pour être compris par un nouveau membre de l'équipe.

Origine du modèle

Dan North a emprunté l'idée de la structure en trois parties à la formulation de tests en TDD et à la méthodologie Test-by-Example (créée par Brian Marick). Marick a proposé de décrire les exigences par des exemples (examples) qui servent simultanément de tests. Given-When-Then a formalisé cette idée, transformant des exemples non structurés en un modèle répétable.

Domaine d'application

Le modèle Given-When-Then ne s'applique pas seulement aux scénarios BDD en Gherkin, mais aussi aux tests unitaires classiques avec JUnit, XCTest et d'autres frameworks. Les commentaires dans le code qui divisent le test en trois blocs sont une pratique courante pour améliorer la lisibilité de la base de tests. Google recommande cette approche dans son livre « Software Engineering at Google » (2020).

Structure des trois blocs

Chaque bloc de Given-When-Then a une sémantique strictement définie et des règles de contenu. La violation de ces règles produit des scénarios difficiles à automatiser ou à comprendre.

Given : préconditions

Le bloc Given décrit l'état du système avant d'exécuter l'action testée. Il inclut : les objets existants (utilisateur, commande, paramètres), les états actifs (authentifié, connecté au réseau) et les valeurs initiales des données. Chaque Given doit être vérifiable — si l'état du système ne correspond pas au Given, le scénario doit être ignoré ou l'environnement de test préparé à l'avance.

When : action

Le bloc When décrit l'événement unique qui déclenche le comportement testé. Il peut s'agir d'un appel de méthode, d'un clic sur un bouton, de la réception d'une notification ou d'une réponse du serveur. La règle clé est un When par scénario. Si une séquence d'actions doit être vérifiée, créez des scénarios séparés, pas une chaîne de When.

// Given : création des données de test
val user = User(email = "test@example.com", balance = 500.0)
val product = Product(price = 150.0)

// When : exécution de l'action
val result = PurchaseUseCase().buy(user, product)

// Then : vérification du résultat
assertEquals(PurchaseResult.Success, result)
assertEquals(350.0, user.balance)

Then : résultat attendu

Le bloc Then vérifie que le système est passé à l'état attendu. Cela inclut : les valeurs retournées, les changements d'état des objets, les appels aux services externes (via la vérification de mocks) et les modifications de l'interface utilisateur. Chaque bloc Then peut contenir plusieurs vérifications, mais toutes se rapportent à une seule action.

Given-When-Then et Arrange-Act-Assert

Given-When-Then et Arrange-Act-Assert (AAA) sont deux variantes du même modèle en trois parties, mais avec des publics cibles différents. Comprendre leurs différences aide à choisir le format approprié pour chaque tâche.

Quand utiliser Given-When-Then

Le modèle Given-When-Then est optimal pour les scénarios discutés avec le client ou l'analyste : critères d'acceptation des fonctionnalités, cas d'utilisation, vérifications de régression. La syntaxe Gherkin permet d'écrire ces scénarios sans connaissance en programmation.

Quand utiliser Arrange-Act-Assert

Arrange-Act-Assert est le choix naturel pour les tests unitaires qui vérifient une méthode ou une classe spécifique. Le format AAA ne nécessite pas de frameworks supplémentaires et fonctionne dans n'importe quel langage de programmation. Pour le développement iOS, Apple recommande AAA dans la documentation XCTest (2024).

Exemples de scénarios en Kotlin

Examinons des exemples pratiques de Given-When-Then en Kotlin pour une application Android. Le premier exemple est un test de panier d'achat avec MockK. Le second est un test de la logique de notifications push.

Exemple 1 : panier d'achat

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)
    }
}

Exemple 2 : notifications push avec coroutines

Le deuxième exemple démontre Given-When-Then avec du code asynchrone. Ici, Given définit l'état de Firebase Cloud Messaging, When — la réception d'une notification push, Then — la vérification du traitement.

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)
    }
}

Exemple 3 : scénario Gherkin pour l'authentification

Le troisième exemple est un scénario BDD en Gherkin montrant Given-When-Then dans le contexte de tests d'acceptation :

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

Bonnes pratiques pour écrire des scénarios

L'application efficace de Given-When-Then nécessite de suivre plusieurs pratiques éprouvées. Elles garantissent la lisibilité, la maintenabilité et l'automatisation des scénarios.

Un When par scénario

Règle stricte : un scénario — une action. Si une séquence de plusieurs When doit être vérifiée, créez plusieurs scénarios où le résultat du précédent devient la précondition du suivant. Cela rend le scénario atomique et compréhensible.

Évitez les données concrètes dans Given

Given doit décrire l'essence, pas des chiffres concrets. Au lieu de « Given l'utilisateur Ivanov avec un solde de 500 roubles » — « Given un utilisateur avec un solde suffisant ». Les données concrètes sont déplacées dans un Scenario Outline avec une table d'Examples. Cela rend le scénario universel et réutilisable.

• Écrivez Then comme des assertions mesurables — « l'utilisateur doit voir l'écran de connexion », pas « l'utilisateur doit être redirigé »
• Utilisez And pour les étapes de même type — si plusieurs Given sont nécessaires, combinez-les avec And, ne créez pas un deuxième Given
• Ne mélangez pas les niveaux d'abstraction — Given-When-Then doit être au même niveau : soit métier, soit technique, mais pas mélangé
• Documentez la raison du scénario — un commentaire au début du fichier .feature avec la description de la règle métier aide au contexte

Given-When-Then dans le pipeline CI/CD

L'intégration de scénarios Given-When-Then dans le pipeline d'intégration continue les transforme de documentation en protection contre les régressions. Chaque merge request dans un projet mobile exécute automatiquement les scénarios BDD et bloque la fusion si au moins un scénario échoue.

Exécution automatique des scénarios

Les scénarios BDD avec Cucumber pour Android sont exécutés via la tâche Gradle ./gradlew cucumber. Pour iOS (Quick/Nimble) — via xcodebuild test. Dans les systèmes CI (GitHub Actions, GitLab CI, Bitrise), les tests BDD sont exécutés sur des émulateurs ou des appareils réels. Le rapport est généré au format HTML compréhensible par les managers : scénarios verts — réussis, rouges — échec avec indication de l'étape.

Documentation vivante dans le dépôt

Les fichiers .feature sont stockés dans le dépôt à côté du code et passent par une revue de code. L'analyste crée une merge request avec de nouveaux scénarios avant le début du développement (BDD-first). Le développeur écrit les définitions d'étapes (step definitions) et l'implémentation pour que ces scénarios deviennent verts. Quand tous les scénarios passent — la fonctionnalité est prête. Cette approche, décrite dans le livre de Gojko Adzic « Specification by Example » (2011), transforme les exigences en un artefact exécutable.