Q17 of 21 · BDD / Cucumber
What is living documentation in the context of BDD, and how do you achieve it in practice?
Short answer
Short answer: Living documentation means the feature files are the single source of truth for feature behaviour — they're always up-to-date because they're executable tests that fail if they drift. Tools like Serenity BDD or Pickles publish them as a browsable website from the CI build.
Detail
The key insight: if a scenario runs in CI and the feature changes without updating the scenario, the build fails. This forces the documentation to stay current. Compare this to a Word document or Confluence page that nobody updates after the sprint ends.
How to achieve it:
Feature files in source control — same repo as the code, reviewed in PRs, versioned with the feature.
Scenarios run in CI — every PR triggers the Cucumber suite. A failing scenario is a red build.
Publishing — Serenity BDD:
<dependency>
<groupId>net.serenity-bdd</groupId>
<artifactId>serenity-cucumber</artifactId>
</dependency>
Serenity generates an HTML report from Cucumber JSON output, showing scenarios grouped by feature, colour-coded pass/fail, with screenshots on failure. This is the "published documentation."
Pickles / Relish — older tools that convert .feature files to navigable HTML without running them. Less valuable than Serenity because they don't show pass/fail status.
Allure with Cucumber plugin:
--plugin io.qameta.allure.cucumber7jvm.AllureCucumber7Jvm
Generates Allure reports with Gherkin steps visible alongside timings and attachments.
The failure mode: Living documentation becomes dead documentation when teams use @Ignore or skip failed scenarios without fixing them. Monitor the tag counts — a growing @wip or @skip tag collection is a documentation debt alarm.