Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Patterns and Pitfalls

Three Amigos, Example Mapping and Living Documentation

Learn the collaboration side of BDD: the three amigos, example mapping, the discover-formulate-automate cycle, and how Cucumber feature files become living documentation.

Teams that treat Cucumber as a testing library get a fraction of its value. BDD was invented to fix a communication problem: the business asks for one thing, the developers build another, the testers check a third, and everyone discovers the gap late and expensively. Cucumber is the last step of a process that starts with a conversation. This lesson covers the practices around the tool: the three amigos meeting, example mapping, the discovery, formulation and automation cycle, and how well-kept feature files become living documentation that is always true because the build checks it.

Cucumber cannot run on this site, so all Gherkin is read-only. The runnable stand-ins are two short Java programs: one turns an example map into a feature file draft, the other builds a documentation index from tagged scenarios.

The three amigos

Business What problem do we solve?
Development How could we build it?
Testing What could go wrong?
1 / 2

The three amigos

Before a story is built, three perspectives meet for 15 to 30 minutes: someone who understands the business need (product owner, analyst), someone who will build it (developer) and someone who thinks about risk and edge cases (tester). It is called "three amigos" but the number is a guide; the point is that every viewpoint is in the room before the code exists.

They do not write test scripts. They talk through concrete examples: "What if the customer has a gold membership and the cart is under 20 dollars?" Every example exposes a hidden assumption, a missing rule or a contradiction, at the cheapest possible moment. The output is shared understanding, and a few examples that will become scenarios.

Example mapping

Example mapping is a lightweight way to structure that conversation, using four colors of index card (or sticky notes):

  • Yellow: the user story at the top ("Free shipping for loyal customers").
  • Blue: the business rules that govern it ("Gold members ship free", "Orders over 50 dollars ship free").
  • Green: concrete examples under each rule ("Gold, cart 20 dollars, shipping 0", "Basic, cart 20 dollars, shipping 5", "Basic, cart 50 dollars, shipping 0").
  • Red: open questions nobody can answer yet ("Do gift cards count toward 50 dollars?").

Watch the board while you talk. Many red cards mean the story is not ready; many blue rule cards mean the story is too big and should be split; a rule with no green card means nobody understands it. A good session ends with a quick vote on whether the team is ready to start.

Discovery, formulation, automation

  1. Discovery: the conversation and the example map. Humans only, no tools.
  2. Formulation: rewrite the examples as Gherkin in the team's ubiquitous language, declaratively (Declarative scenarios). Review them with the business.
  3. Automation: write step definitions and the code. The scenarios fail first, then pass as the feature is built.

Skipping the first step is the single most common reason BDD "does not work". If scenarios are written alone by a tester after the code ships, nobody discussed anything, and the feature files are just verbose test scripts (anti-patterns).

The stand-in below turns an example map into a feature draft: rules become Rule: blocks (Gherkin 6+), examples become scenarios and open questions are written as comments to remind everybody.

Java From example map to feature draft (Java stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The output uses Rule: and Example: (a synonym of Scenario:), both valid Gherkin since version 6. Rules group scenarios by business rule, which keeps the feature file aligned with the conversation.

Living documentation

A document that describes what the system does is useful. One that is always correct is valuable. Feature files can be that document, because the build fails when behavior and description diverge. This is living documentation, in contrast to wikis and requirement documents that drift out of date.

To make it work:

  • Write for readers, not for the runner: a descriptive feature title, a short free-text description under Feature: explaining the purpose, clear scenario names, and no UI noise.
  • Organize by domain capability (features/shipping/free-shipping.feature), not by sprint or ticket number.
  • Link to context with tags such as @story-482 or @policy-gdpr (Tags).
  • Publish the HTML report (Reports) or generate a browsable site from the features with tools like Pickles, Serenity or Allure, or a small script of your own. Put the link where product owners will find it.
  • Delete scenarios when the rule changes or disappears. Stale scenarios are false documentation.

Below, a small script groups scenarios by capability and tag into an index, the kind of page that helps a product owner answer "what does the system do about shipping?".

Java A documentation index from tagged scenarios (Java stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The unchecked box is documentation of a gap, not only a test failure: the system does not yet do what the team agreed.

Rules of thumb

  • One conversation per story, before development starts, and keep it short.
  • Name things in the business's own language (ubiquitous language) and use the same words in code.
  • Examples first, abstractions later; vague rules without examples are untested opinions.
  • Treat feature files as code: review them in pull requests together with the implementation.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main purpose of the three amigos meeting?

    Different perspectives expose misunderstandings early, when they are cheapest to fix.
  2. 2. In example mapping, what do blue cards represent?

    Yellow is the story, blue the rules, green the examples and red the questions.
  3. 3. Why can feature files be called living documentation?

    An automated check keeps the description and the real behavior in sync.
  4. 4. A story has ten blue cards and many red cards after example mapping. What does that suggest?

    Many rules signal a large story; many questions signal missing knowledge. Both mean it is not ready to build.

Summary

  • BDD starts with conversation: the three amigos discuss concrete examples before coding.
  • Example mapping uses story, rules, examples and questions cards to judge whether a story is ready.
  • The cycle is discover, formulate, automate; skipping discovery turns Gherkin into verbose test scripts.
  • Well-written, organized, published and pruned feature files are living documentation.

Next: Project: bank account behavior