git:20260724.d4db756 to git:20260726.19ddd36

---

name: living-documentation-publisher

description: "Converts passing Cucumber JSON output into stakeholder-facing living documentation: generates HTML reports via multiple-cucumber-html-reporter (Node) or Serenity BDD aggregate (JVM), applies Gherkin tags to drive report sections, and publishes to GitHub/GitLab Pages in CI. Use when BDD scenarios are in use and the team needs an always-current, non-test-engineer-readable document showing which acceptance criteria pass."

metadata:

keywords: "living-documentation, bdd, cucumber, serenity, reporting, github-pages"

---

# living-documentation-publisher

## Overview

Per the Serenity BDD book ([serenity-bdd/the-serenity-book, living-documentation.adoc][ld]):

> "Living documentation is generated by the automated test suite, and is

> therefore by definition it is always up-to-date."

The same source distinguishes living documentation from plain test reports:

living documentation is authored before development starts, targets the whole

team (BAs, product owners, stakeholders), and reads as a business-functionality

narrative, not a pass/fail table.

This skill covers the full workflow: produce Cucumber JSON from a passing suite,

feed it into a report renderer, apply tag-based section routing, and publish the

HTML artefact to a Pages endpoint so stakeholders get a URL, not a zip file.

Two primary renderers are covered:

- **Serenity BDD aggregate report** (JVM, Maven/Gradle projects using

## When to use

- The team already has Cucumber scenarios (see

`cucumber-testing`) and stakeholders need to

read acceptance-criteria status without opening a test runner.

- The living-documentation page must track only *passing* scenarios (not every

scenario authored, including pending or skipped ones).

- CI should gate report publication so stakeholders never see a stale or

red-run document.

If only engineers read the results, the JUnit XML feed to

`junit-xml-analysis` (in the qa-test-reporting plugin)

is sufficient.

## Step 1 - Produce Cucumber JSON output

The report renderers both consume Cucumber JSON. Configure the JSON formatter

before wiring the renderer.

**Cucumber-JS** (in `package.json`):

```json

{

"scripts": {

"test": "cucumber-js features/ --format json:reports/cucumber.json"

}

}

```

**Cucumber-JVM with Serenity** (in `serenity.properties`):

The `CucumberWithSerenity` runner captures results automatically; no explicit

JSON formatter is needed. Serenity writes its own JSON artefacts to

`target/site/serenity/` as part of `mvn verify`

([serenity-bdd/the-serenity-book, maven.adoc][mv]).

## Step 2 - Generate the HTML report (Node path)

## Step 3 - Generate the HTML report (JVM / Serenity path)

## Step 4 - Tag scenarios for report sections

Use Gherkin tags to categorise scenarios in both renderers.

In the feature file:

```gherkin

@billing @sprint-12

Scenario: Apply promo at checkout

Given ...

```

**Serenity tag filtering** - run only tagged tests and limit the aggregate

report to those requirements ([serenity-bdd/the-serenity-book, filtering-reports.adoc][fr]):

```bash

# Run and report on one sprint

mvn clean verify -Dcucumber.options="--tags=@sprint-12" \

-Dtags=sprint-12

# Post-run report filtered to a tag

mvn serenity:aggregate -Dtags=sprint-12

```

Note: "requirements filtering only happens if you specify the `tags` option"

([serenity-bdd/the-serenity-book, filtering-reports.adoc][fr]).

**Excluding pending/WIP from published docs:**

```bash

# Cucumber-JS: exclude anything tagged @wip from the JSON

npx cucumber-js features/ \

--tags "not @wip" \

--format json:reports/cucumber.json

```

This keeps the living-documentation page free of scenarios that are not yet

passing.

## Step 5 - Only publish passing runs

Gate the report publication step on a green test exit code. In a shell script:

```bash

set -e

npm test # exits non-zero on any failure

node scripts/generate-report.js # only reached if all tests pass

```

For Serenity, use `serenity:check` after `verify`

([serenity-bdd/the-serenity-book, maven.adoc][mv]):

```bash

mvn verify serenity:check # fails the build if any scenario is red

```

This ensures the published artefact reflects only a fully-green run.

## Step 6 - Publish to GitHub Pages (CI)

## Anti-patterns

| Anti-pattern | Why it fails | Fix |

|---|---|---|

| Publishing on any push, including red runs | Stakeholders see failing-scenario counts; erodes trust in the document | Gate publish on exit code 0 (Step 5) |

| Including `@wip` / `@pending` scenarios in the report | Document shows work-in-progress as if it is accepted behaviour | Filter with `not @wip` before generating JSON |

| One flat tag for all scenarios | Stakeholders cannot navigate to a capability area | Apply two-level tags: `@capability-name` and `@sprint-N` |

| Publishing stale JSON from a previous run | Report shows old results after source changes | Delete `reports/*.json` at the start of each CI run before running tests |

| Embedding full screenshots in every step | HTML artefact becomes hundreds of MB | Use Serenity's evidence API (`Serenity.recordReportData()`) selectively, or configure `take.screenshots=FOR_FAILURES` in `serenity.properties` |

## Limitations

- **Serenity aggregate requires JVM test execution in the same Maven

lifecycle.** Running `serenity:aggregate` against JSON files from a

Cucumber-JS run is not supported; use multiple-cucumber-html-reporter for

Node projects.

- **multiple-cucumber-html-reporter merges JSON by filename, not by run order.**

If parallel shards write JSON with identical names, results are silently

overwritten. Use timestamped or shard-indexed filenames.

- **Pages publish latency.** GitHub Pages can take 60-120 seconds to reflect

a push; stakeholders may see the previous version briefly after a CI run.

- **Serenity requirements hierarchy is derived from directory layout.** Renaming

a feature directory breaks historical trend data in the report.

## References

- `cucumber-testing` - upstream skill: produce Cucumber JSON

with `--format json:`.

- `junit-xml-analysis` (in the qa-test-reporting plugin) -

engineer-facing test result analysis (separate concern from stakeholder docs).

- `github-actions-test-jobs` (in the qa-ci-integration plugin) -

CI job conventions for the publish step.

[ld]: https://raw.githubusercontent.com/serenity-bdd/the-serenity-book/master/modules/ROOT/pages/living-documentation.adoc

[mv]: https://raw.githubusercontent.com/serenity-bdd/the-serenity-book/master/modules/ROOT/pages/maven.adoc

[fr]: https://raw.githubusercontent.com/serenity-bdd/the-serenity-book/master/modules/ROOT/pages/filtering-reports.adoc