Where is the BackstopJS HTML report?

`backstop test` writes it to `backstop_data/html_report/index.html`, with the reference, test and diff images in sibling directories. Publish the whole directory so the three-up comparison renders.

Why does a visual diff need comments?

Because every diff is a question — intended or regression — and the answer is a person's. Anchored threads put 'intended, new spacing scale' or 'this is the regression, see DES-77' on the specific scenario instead of in a channel where it detaches from the image.

How do I show the designer without giving them CI access?

Send the link. A published report needs no pipeline permission, no Node install and no local run — which is the entire reason visual review usually stalls.

Does the report keep working across runs?

PATCH the same report id each run and the URL stays put with a revision per run. The designer's bookmark keeps showing the current diffs, and the previous approval conversation is still attached.

The report has hundreds of images. Is that a problem?

Assets cap at 25 MB per file and 250 MB / 500 files per report. A large scenario matrix at several viewports can pass 500 files — publish per section or per viewport when it does.

Share a BackstopJS report

Visual regression testing has a well-known failure mode, and it is not technical. The suite runs, produces forty diffs, and then waits for a human to say which ones are intended. That human is usually a designer, and the report is usually on a CI worker behind a login they do not have.

So the diffs get screenshotted into Slack, one at a time, and the approval conversation happens next to a cropped image with an arrow drawn on it.

Publish it

npx backstop test || true

curl -fsS -X PATCH \
  "https://commareports.com/api/v1/reports/$COMMA_REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html backstop_data/html_report/index.html \
        --arg title "Visual diffs — $BRANCH — build $BUILD_NUMBER" \
        '{title: $title, html: $html}')"

The report is image-heavy by nature, so dragging backstop_data/html_report/ into the app is usually the better route: the reference, test and diff images upload as assets and their references are rewritten to the uploaded copies. Publish the index alone and you get a report shaped like a visual diff with no visuals in it.

|| true because backstop test exits non-zero whenever anything differs, which is every run you care about.

What the URL changes

Approval happens on the diff. "Intended — new spacing scale" or "regression, DES-77" pinned to the scenario. See commenting on HTML.
The designer needs no tooling. A link, in a browser, on a phone.
Run-over-run history. Same URL, revision per run, so the conversation about last week's diff is still there.
Private by default — pre-release UI is not something to leave on a guessable URL. See the sharing model.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total — three images per scenario per viewport adds up quickly. Publish per section when the matrix is large.
Scripts run, sandboxed: allow-scripts, no allow-same-origin.
60 requests/minute per token.

Try it

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

Create your first report →

Storybook static builds — the components themselves
Accessibility reports · Lighthouse
Share with a client · Publish from CI

Share a BackstopJS report

Publish it

What the URL changes

Limits

Try it

Related