Skip to content
flaky-tests

Using the HTML report

The CLI can emit a self-contained HTML report — a single .html file with inline CSS and a minimal inline script for interactivity. No build step, no bundler, no external assets; you can email it, attach it to a ticket, or archive it as a CI artifact and it still works opened via file://.

Preview of the flaky-tests HTML report showing the stat strip, sticky table of contents, pattern cards, and recent runs table.

Generate a report

Section titled “Generate a report”

  1. Run the CLI with --html

    Terminal window
    npx @flaky-tests/core --html

    The CLI writes the report to a temp file, prints its path, and opens it in your default browser.

  2. Or write to a specific location with --out

    Terminal window
    bunx @flaky-tests/core --html --out flaky-report.html

    Use this when you want to commit the file, attach it to a PR, or upload it as a CI artifact.

Wire it into package.json

Section titled “Wire it into package.json”

Drop a dedicated script into package.json so report generation is a single command everyone on the team can run:

Terminal window
npm i -D @flaky-tests/core
package.json
{
  "scripts": {
    "flaky:report": "flaky-tests --html",
    "flaky:report:save": "flaky-tests --html --out flaky-report.html"
  }
}

CI jobs can then call bun run flaky:report:save (or the npm / pnpm / yarn equivalent) and upload the resulting flaky-report.html as a workflow artifact.

What’s in the report

Section titled “What’s in the report”

Header stat strip

Section titled “Header stat strip”

Five at-a-glance counters across the top:

CellWhat it means
patternsTests failing ≥ threshold in the window
criticalTests with ≥ 10 recent fails
fails / NdTotal failure events inside the window
hot filesDistinct source files producing failures
last runRelative time since the most recent recorded run

Sticky table of contents

Section titled “Sticky table of contents”

A left-rail navigator with a severity dot per pattern (red / coral / orange / yellow for critical / high / medium / low) and jump links to each dashboard section. Stays pinned as you scroll; collapses to a static list on narrow viewports.

Pattern cards

Section titled “Pattern cards”

One card per newly-flaky test, sorted by recent-fail count descending. Each card shows:

  • A severity pill and card number
  • The test path (outer > inner > name) and file location
  • Recent/prior fail counts
  • The first line of the most recent error
  • A collapsible investigation prompt with a Copy button

The copy button writes the full prompt to the clipboard (via navigator.clipboard when available, falling back to range-selection). Paste into Claude, Cursor, Copilot, or any chat UI to start investigating.

Investigation prompts

Section titled “Investigation prompts”

Every pattern card ships with a collapsible investigation prompt — the same structured prompt the CLI emits under --prompt. It’s the fastest path from “something’s flaky” to “I have a working hypothesis”.

What’s in each prompt

Each prompt is a single block of plain text assembled from the failure’s context — enough for an LLM to reason about the failure without round-trips:

  • The test name and file path
  • The failure category (assertion / timeout / uncaught / unknown) and the first error line
  • Recent-vs-prior failure counts in the current window
  • Trimmed stack frames (stripped of timestamps so diffs are stable)
  • The git SHA at capture time — so the investigator can check out the exact state that produced the failure

No PII is added; the prompt is a subset of rows already in your store. See Data model & privacy for exactly what’s captured.

How to use them

  1. Click the summary row (“Investigation prompt · click to expand”) to see the full text inline.
  2. Click Copy to put the full prompt on your clipboard. The button flashes Copied ✓ on success.
  3. Paste into any LLM surface. The prompt is plain text — Claude, Cursor’s inline chat, Copilot Chat, a terminal LLM wrapper, all work the same.
  4. Fallback path — if clipboard write is blocked (Safari in some iframes, older file:// contexts) the button silently selects the prompt text so you can Cmd / Ctrl+C manually.

Prompt parity with the CLI

The same text is available headlessly:

Terminal window
bun run flaky:prompt     # if you added the script
# or
bunx @flaky-tests/core --prompt

Useful when you want to pipe prompts into a tool instead of opening the report UI — for example, a bot that posts the first prompt of the day into Slack.

Hot-file prompts

The Hot Files table has its own per-row Copy button. These emit a shorter, file-level prompt (“Investigate <path>: N failures across M distinct tests in the last D days”) — useful when a whole module has gone shaky and individual-test prompts miss the forest for the trees.

Recent runs table

Section titled “Recent runs table”

Chronological view of the last 20 recorded runs, filtered to the current project. Columns: status, when, duration, total / passed / failed / errors, short git SHA.

Click or press Enter on any run row to expand its per-failure breakdown — test name, failure kind, error preview, and relative timestamp. The chevron rotates to indicate the expanded state.

Theme toggle

Section titled “Theme toggle”

Top-right of the header: a sun / moon toggle. Three modes:

  1. System default (first visit) — follows prefers-color-scheme
  2. Light — forced light palette, persisted to localStorage
  3. Dark — forced dark palette, persisted to localStorage

The choice survives reloads and follows you across any reports opened from the same origin.

Sharing and archiving

Section titled “Sharing and archiving”

Because the report is a single .html file with no external dependencies, it travels well:

  • Email / Slack attachment — open directly from the download
  • Commit to the repo — diff-friendly for tracking trends over time
  • CI artifact — upload once per scheduled detection run
.github/workflows/flaky-check.yml
- name: Generate flaky report
  run: bunx @flaky-tests/core --html --out flaky-report.html


- name: Upload report
  uses: actions/upload-artifact@v4
  with:
    name: flaky-report
    path: flaky-report.html
    retention-days: 30

Interactivity cheatsheet

Section titled “Interactivity cheatsheet”
ActionHow
Jump to a patternClick its entry in the sticky TOC
Expand the investigation promptClick the Investigation prompt summary
Copy a promptClick Copy on any card
Drill into a runClick or Enter on a recent-runs row
Toggle light / darkClick the sun / moon icon in the header
Section titled “Related”