Gate fetch priority collection behind a --priority flag

[sergeychernyshev]

Summary

Collecting fetch priorities requires tagging every request with an x-telescope-id header, so Chromium's CDP request IDs can be matched to HAR entries. Injecting that header needs a catch-all page.route() handler — and registering one disables the browser HTTP cache. That changes what is being measured: resources advertised in an Early Hints (103) response get re-requested instead of reused.

This makes the whole feature opt-in via --priority, defaulting to off.

Changes

Gating

• testRunner.ts — the catch-all route and the requestfinished collector move into setupPriorityCorrelation(), which returns early unless the flag is set.
• chromeRunner.ts — the three CDP Network.* priority listeners move into collectPriorities(), only called when the flag is set. Network.enable is no longer sent unconditionally. --cpuThrottle still works either way (it uses the Emulation domain).
• Flag plumbed through LaunchOptions, DefaultOptions, CLIOptions, DEFAULT_OPTIONS, the Commander options, and normalizeCLIConfig.

mergeEntries() needed no guard — with the flag off, this.requests is empty, so it is already a no-op.

README

• Removed the global x-telescope-id note from the top of the document.
• Added a ### Fetch priority section: what the flag does, the _initialPriority / _priority HAR fields, and Chromium-only support.
• Added a #### The x-telescope-id header subsection explaining why the header exists, that it is sent to the server, that it disables the HTTP cache, and that it changes the recorded header shape.
• Added --priority to the --help block.

Behaviour change worth reviewing

Two things follow from the header no longer being injected by default.

1. HAR request headers are now the wire representation. Requests no longer pass back through a route handler, so the HAR records what actually went out rather than the set Telescope replayed:

	entries[0].request.headers
--priority	Accept, Upgrade-Insecure-Requests, User-Agent, x-telescope-id, …
default	:authority, :method, :path, :scheme, accept, …, user-agent

The default is arguably more accurate. cli.test.ts was matching 'User-Agent' case-sensitively and relying on the interception artifact, so it now matches case-insensitively per RFC 9110 §5.1. Documented in the README for anyone consuming the HAR.

2. Per-entry timing enrichment is also gated. The same correlation drives _dns_start/_connect_*/_request_*/_response_*/_resourceType/_is_lcp, because the header is what disambiguates several requests sharing one URL. duplicateRequests.test.ts — whose point is that duplicate-URL entries each get their own timings — now opts in with priority: true. Worth a look if any downstream consumer expects those fields by default.

Tests

New __tests__/priorityFlag.test.ts (11 tests):

• setupPriorityCorrelation() touches neither page.route() nor page.on() when the flag is unset or false; registers the **/* route and the requestfinished listener when true.
• Same assertions via preparePage(), so the call-site wiring is covered.
• DEFAULT_OPTIONS.priority is false; --priority round-trips into config.json.
• End-to-end against a local fixture server: no x-telescope-id header and no priority fields in the HAR by default; header present on every entry with the flag on.

priority.test.ts updated to pass priority: true.

Full suite green in headless CI mode (npm run test:ci): 16 files, 418 tests.

Refs

• Relates to Aggressive page.route disabling HTTP Cache #327

[Copilot]

Pull request overview

Makes fetch-priority collection opt-in via a new --priority flag to avoid the Playwright page.route() side effect of disabling the browser HTTP cache (notably impacting Early Hints / 103 behavior). This keeps default runs closer to real browser caching behavior while still allowing correlation-based enrichment when explicitly requested.

Changes:

• Plumbs a new priority option through types/defaults/CLI and gates request correlation + CDP priority listeners behind it.
• Updates documentation to describe --priority, the HAR extension fields, and the x-telescope-id implications.
• Adds/updates tests to verify the flag wiring and the default/no-header behavior.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/telescope/src/types.ts	Adds priority to LaunchOptions/DefaultOptions/CLIOptions types.
packages/telescope/src/testRunner.ts	Moves the catch-all route + requestfinished correlation into setupPriorityCorrelation() gated by options.priority.
packages/telescope/src/index.ts	Adds --priority Commander option and updates API note about x-telescope-id being priority-gated.
packages/telescope/src/defaultOptions.ts	Sets DEFAULT_OPTIONS.priority = false.
packages/telescope/src/config.ts	Normalizes CLI config to include priority.
packages/telescope/src/chromeRunner.ts	Gates CDP Network.* priority listeners behind options.priority (and avoids unconditional Network.enable).
packages/telescope/README.md	Documents fetch priority collection and x-telescope-id tradeoffs; adds --priority to help text.
packages/telescope/tests/priorityFlag.test.ts	New tests covering gating behavior, CLI wiring, and end-to-end header presence/absence.
packages/telescope/tests/priority.test.ts	Opts into priority collection for the priority assertions.
packages/telescope/tests/duplicateRequests.test.ts	Opts into priority/correlation since per-entry timing enrichment depends on it.
packages/telescope/tests/cli.test.ts	Makes User-Agent header matching case-insensitive to align with “wire” header casing when not routing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sergeychernyshev]

Good catch — the sentence was wrong. Fixed in 7768090.

You're right about the mechanism: setupPriorityCorrelation() is on TestRunner, and TestRunner.createPage() (the Firefox/Safari path) calls preparePage(), so the catch-all route and header injection happen on every engine. Confirmed empirically on Firefox with --priority:

header=true  _dns_start=true  _priority=false

So the header is sent and the cache is disabled, the timing correlation works, and only the priority fields are missing.

I considered restricting the correlation to Chromium so the flag really would be a no-op elsewhere, but that would break the per-entry timing enrichment (_dns_start, _connect_start, _resourceType, …) which is engine-independent and genuinely useful — duplicateRequests.test.ts depends on it and runs Firefox-only in CI. The header is the only thing that disambiguates several requests sharing a URL.

So I reworded rather than re-gated, and spelled out what each engine actually gets, including the timing fields the correlation adds everywhere.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (1)

packages/telescope/README.md:243

• The text says “Two consequences…”, but the list that follows contains three bullet points. This can confuse readers about what to expect when enabling --priority.

Two consequences are worth knowing before you enable it: