How do I generate LivingDoc as a single HTML file?

`livingdoc test-assembly bin/Debug/net8.0/MyTests.dll -t TestExecution.json -o LivingDoc.html`. The `-t` argument folds the last run's results into the feature documentation, so each scenario shows as passed, failed or not executed.

Reqnroll is the maintained continuation of SpecFlow and ships the same living-documentation generator. The command shape is the same and the output is the same single HTML file — publish it identically.

Why does LivingDoc need the TestExecution.json?

Without it you get the feature files rendered nicely and nothing about whether they pass. The JSON comes from the SpecFlow/Reqnroll test-run plugin and is what turns documentation into living documentation.

Can a product owner comment on a scenario?

Yes — that is the reason to publish it. Threads anchor to the rendered content, so "this Given is wrong, trial users do have billing" lands on the scenario instead of in an email.

Can I keep one link per release?

Save the report id and PATCH it from the CI job. Each publish appends a revision at the same URL, so the link in the release notes always resolves to current behaviour.

Share SpecFlow LivingDoc

BDD's premise is that the scenarios are readable by the people who define the behaviour. In practice the scenarios live in .feature files in a repository those people cannot open, which quietly reduces Gherkin to an unusually verbose test syntax.

LivingDoc is the part that was supposed to close that loop: one HTML file containing every feature, every scenario, the example tables, and — if you feed it the execution results — whether each one currently passes.

dotnet tool install --global SpecFlow.Plus.LivingDoc.CLI

livingdoc test-assembly bin/Debug/net8.0/MyTests.dll \
  -t bin/Debug/net8.0/TestExecution.json \
  -o LivingDoc.html

On Reqnroll — the maintained continuation of SpecFlow — the generator is the same and so is the output: a single self-contained document.

The file is the easy part

Then it goes into a CI artifact, which needs a login and expires on a retention schedule, and the product owner who asked "does the trial expiry scenario cover annual plans?" gets a screenshot of two lines of Gherkin.

Drop LivingDoc.html into Comma and it is a URL. Self-contained, so there is nothing to zip and nothing to break in transit.

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html LivingDoc.html \
        --arg t "Behaviour — $BUILD_BUILDNUMBER" '{title: $t, html: $html}')"

Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin), so LivingDoc's feature tree, tag filters and search keep working at the published URL. See the API reference and publishing from CI.

Who it is actually for

The audience for this document is not the team that wrote it. It is:

the product owner checking that the scenarios match what they asked for,
the support lead looking for the documented behaviour of an edge case,
the auditor who wants evidence that the stated requirement is tested.

None of them have a CI login, and none of them are going to get one. A link, with access set to anyone signed in at your domain, covers all three — see sharing & access control.

Comments are the feedback loop BDD promised

The value of living documentation is not that it is generated; it is that the non-engineers reading it can push back. Anchored threads put "this Given is wrong" on the Given. The scenario gets fixed in the .feature file, the next run republishes, and the thread is still there next to the corrected step. See commenting on HTML.

A revision per run also answers the question release notes never do: which scenarios changed between these two builds.

Limits

Entry HTML: 5 MB. LivingDoc inlines everything, so a very large suite can approach it — generate per feature folder, or drop the images from screenshot-attaching steps.
Assets: 25 MB per file, 250 MB and 500 files total.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish living documentation →