Differential capture

Record named captures of the same page and compare them to see which requests appeared, disappeared, or changed between runs.

Differential capture records named captures and compares them, so you can see what changed between two runs of the same page. It is the tool for questions like “which requests does the new build make that the old one did not?”

Captures live in a working directory, which is what ties a comparison together. Pass the same -diff-work-dir to every command in a session, or they will not see each other. (The localhost:8099 fixture below is the demo server from the Quickstart.)

Recording two captures

chrome-to-har -headless -diff-mode -diff-work-dir ./diffwork \
	-url http://localhost:8099/ -capture-name base

Completed capture: base (ID: 20260804-185921-3ec56fb6)
To compare with another capture, use: -compare-with <capture-id> -baseline 20260804-185921-3ec56fb6

Make whatever change you are measuring, then record the second capture into the same directory:

chrome-to-har -headless -diff-mode -diff-work-dir ./diffwork \
	-url http://localhost:8099/ -capture-name after

-capture-name is a label for your benefit; the ID is what the comparison flags take. -list-captures reports both:

chrome-to-har -diff-work-dir ./diffwork -list-captures

Available captures (2):
  ID: 20260804-185924-892cd850
  Name: after
  URL: http://localhost:8099/
  Timestamp: 2026-08-04 18:59:24
  Status: completed
  Entries: 1
  Size: 2.15 KB
  …

Status: completed with a nonzero Entries is what a usable capture looks like. A capture stuck at recording with Entries: 0 did not record anything, and comparing against it will fail for want of a HAR file.

Recording obeys the ordinary capture flags, so -wait-for, -wait-stable, -urls, and -block all apply. Use them: a capture that stops before the page finishes loading produces a diff full of differences that are really just timing.

Comparing

chrome-to-har -diff-mode -diff-work-dir ./diffwork \
	-baseline 20260804-185921-3ec56fb6 \
	-compare-with 20260804-185924-892cd850 \
	-diff-format json -diff-output report.json

Comparison completed successfully
Report generated: report.json
Summary: 0 added, 0 removed, 1 modified requests

-diff-format accepts html (the default), json, text, and csv. The JSON report carries baseline_capture, compare_capture, summary, network_diffs, resource_diffs, performance_diff, and timestamp; the summary object holds the added, removed, modified, and unchanged request counts. Reach for json when something downstream reads the result, and html when a person does.

Two captures of an unchanged page still report 1 modified in the example above — response timings differ between runs even when the bytes do not. Treat added and removed as the signal, and read modified with that in mind.

When a plain diff is enough

If all you want is which URLs appeared or disappeared, two ordinary captures and jq answer it without a working directory:

chrome-to-har -headless -url http://localhost:8099/ -wait-for '#done' -output before.har
# make the change
chrome-to-har -headless -url http://localhost:8099/ -wait-for '#done' -output after.har

diff <(jq -r '.log.entries[].request.url' before.har | sort) \
     <(jq -r '.log.entries[].request.url' after.har  | sort)

The differential mode earns its keep when you want the comparison itself as an artifact — a report to attach, or timing and resource changes rather than a list of URLs.

Next steps

Last updated: 2026-09-23