How do I generate an HTML report from Behave?

Install a formatter — `pip install behave-html-formatter` (or `behave-html-pretty-formatter`) — then run `behave -f html -o behave-report.html`. It writes a single self-contained page with CSS and JS inlined.

Why publish a BDD report rather than a JUnit XML?

Because the audience is different. Gherkin exists so people outside engineering can read the specification; a JUnit XML in an artifact bucket puts it back out of their reach. A URL does not.

Do I need to upload assets?

No for the standard formatter — the page is self-contained. If your scenarios attach screenshots, upload those as assets alongside the entry HTML and their references are rewritten to the uploaded copies.

Can a product owner comment on a scenario?

Yes, and that is the point. Anchored threads attach to the rendered scenario, so "this step is wrong, the discount applies before tax" sits on the step rather than in a ticket that references it by paraphrase.

How do I keep one link across runs?

PATCH the same report id from CI on every run. The URL is stable, each run appends a revision, and the person you sent it to last month still has a working link.

Share a Behave HTML report

Behave exists because a .feature file is meant to be readable by the person who asked for the feature. Then the results of running those features get written to stdout on a build agent, and the readable-by-anyone property quietly evaporates.

Write the HTML

pip install behave-html-formatter
behave -f html -o behave-report.html

The prettier variant, if you want collapsible scenarios and a summary bar:

pip install behave-html-pretty-formatter
behave -f html-pretty -o behave-report.html

Both write a single self-contained page — styling and scripts inlined — which makes publishing a one-request job.

Keep a machine format alongside it if a dashboard needs one; Behave takes multiple formatters:

behave -f html -o behave-report.html -f junit --junit-directory reports/

Publish it

Drag the file into the app, or from CI:

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 behave-report.html \
        --arg title "Acceptance — $(git rev-parse --short HEAD)" \
        '{title: $title, html: $html}')"

Run the step with if: always() — Behave exits non-zero on a failing scenario, and a failing scenario is the one the product owner needs to see.

Screenshots from failing steps

If your environment.py attaches a screenshot on failure, upload those files as assets with the report. Their <img src="..."> references are rewritten to the uploaded copies, so the evidence travels with the run instead of being a path into a deleted workspace.

What review adds

The reason to publish a BDD report rather than archive it:

Anchored threads on the scenario — the specification conversation happens on the specification. See commenting on HTML.
Revisions, so "we changed that step last sprint" is checkable.
Access per report — private, team, domain-gated, or named reviewers, so a stakeholder outside the engineering org can read it without a seat in your CI provider. See the sharing model.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. Screenshot-heavy suites are the ones to watch.
60 requests/minute per token.

Try it

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

Publish a test report →