Add PerfKit integration contract tests by dangayle · Pull Request #3774 · Shopify/hydrogen

dangayle · 2026-06-01T23:58:24Z

What this PR does

PerfKit.tsx had zero tests, so if someone accidentally changed a label, broke the load order, or stopped pinging PerfKit on navigation, nothing would catch it — it would just silently ship broken.

This PR adds a safety net. Three small things:

Writes the rules down as tests. A new PerfKit.test.tsx checks the adapter still does exactly what it should — loads the right script URL, sets the right data-* labels, waits until the script is loaded before wiring anything up, and calls PerfKit on the five view events. If anyone breaks the contract later, the test fails.
Names the PerfKit URL (PERF_KIT_URL) so the test can point at it, and so changing that URL becomes a deliberate, reviewed edit instead of a quiet one.
Tidies one line — groups the data-* labels into a single object so the test can read them. No behavior change.

That's the whole PR. No new features, nothing users see, no version bump. It's purely a guard so Hydrogen can't accidentally break its own PerfKit wiring.

What the tests lock down

PerfKit.test.tsx (PerfKit is mocked at the network level — the real script is never downloaded):

Requests the pinned PerfKit SPA script URL.
Passes the required data-* labels exactly: data-application=hydrogen, data-spa-mode=true, parsed data-shop-id, data-storefront-id (from hydrogenSubchannelId), data-monorail-region=global, data-resource-timing-sampling-rate=100.
Parses the shop id out of the shop GID.
Registers Internal_Shopify_Perf_Kit.
Does not wire anything while the script is still loading, and not on error — only after it's done.
Wires all five view subscriptions (page_viewed, product_viewed, collection_viewed, search_viewed, cart_viewed).
Calls ready() exactly once, after wiring.
Doesn't wire twice across a loading → done transition (the re-render guard).
page_viewed → window.PerfKit.navigate(); product/collection/search/cart → setPageType(...).
Doesn't throw if window.PerfKit isn't there yet (script-load race).

About versions

The PerfKit script URL is pinned in PERF_KIT_URL and asserted exactly in the test:
https://cdn.shopify.com/shopifycloud/perf-kit/shopify-perf-kit-spa.min.js

Heads-up for reviewers: this URL is not stable across Hydrogen versions (older builds used a versioned URL like shopify-perf-kit-1.0.1.min.js; the current build uses the unversioned -spa bundle), and window.PerfKit exposes no runtime version. This PR just pins the current -spa build. Giving PerfKit an explicit version/capability signal is a separate, cross-team follow-up.

Scope / impact

Non-user-facing. PERF_KIT_URL is module-local — nothing new is exported from the package entrypoint. No runtime behavior change. No semver bump (empty changeset).
Touches 3 files: PerfKit.tsx, PerfKit.test.tsx (new), and an empty changeset.

Checks run

pnpm --dir packages/hydrogen typecheck ✅
pnpm --dir packages/hydrogen test ✅ — 58 files, 548 tests
pnpm --dir packages/hydrogen exec vitest run src/analytics-manager/PerfKit.test.tsx ✅ — 16 tests
eslint + prettier on changed files ✅

Follow-ups (separate, not in this PR)

Skeleton e2e coverage proving the default Hydrogen app emits the contract end to end.
An explicit PerfKit version/capability signal so version checks can be deterministic.

Requested by Dan Gayle dan.gayle@shopify.com

shopify · 2026-06-01T23:59:44Z

Oxygen deployed a preview of your add-analytics-perfkit-diagnostics branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	June 15, 2026 3:42 PM

Learn more about Hydrogen's GitHub integration.

Lock down the deterministic Hydrogen <-> PerfKit contract with dedicated tests, without changing runtime behavior: - Export the pinned PERF_KIT_URL constant (shopify-perf-kit-spa.min.js) so the exact SPA script URL is asserted in tests; bumping it is now a deliberate, reviewed change. - Memoize the data-* attributes object (stable identity; lets tests assert the exact attributes). No behavior change. - PerfKit.test.tsx covers: SPA script URL; exact data-* attributes; shop GID parsing; storefront id from hydrogenSubchannelId; Internal_Shopify_Perf_Kit registration; no wiring while loading/error; wiring only after done; all five view subscriptions; ready() once after wiring; no double-wire across a loading->done transition; page_viewed -> navigate(); product/collection/ search/cart -> setPageType(...); no throw when window.PerfKit is absent. Non-user-facing, nothing exported from the package entrypoint, no semver change (empty changeset). Requested by Dan Gayle <dan.gayle@shopify.com>

andguy95

This change set should create a patch version of package

Per PR review: the PR touches PerfKit.tsx (exports PERF_KIT_URL, memoizes attributes), so it needs a patch changeset rather than an empty one.

dangayle · 2026-06-08T17:04:04Z

Remove which part? There is a small public change to perfkit itself that isn't a test.

…

On Mon, Jun 8, 2026 at 9:32 AM freddie ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In .changeset/perfkit-contract-tests.md <#3774 (comment)>: > @@ -0,0 +1,5 @@ +--- ***@***.***/hydrogen": patch +--- + +Add PerfKit integration contract tests and export the internal `PERF_KIT_URL` constant; the PerfKit script `data-*` attributes are now memoized. This locks down the deterministic PerfKit contract (pinned SPA script URL, required `data-*` attributes, subscription wiring/readiness, and `navigate()` / `setPageType(...)` on the view events) so it can't regress. No change to runtime behavior. tests are not user facing changes, pls remove — Reply to this email directly, view it on GitHub <#3774?email_source=notifications&email_token=AAA7US6BCDYWTEIIFNPH6PL463TAJA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTINBVGE2DINRQGQY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#pullrequestreview-4451446041>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAA7US5ANCPVAIDOJFA7W23463TAJAVCNFSM6AAAAACZWKB4UKVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHM2DINJRGQ2DMMBUGE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

Co-authored-by: freddie <freddieshaihulud@gmail.com>

fredericoo · 2026-06-15T13:35:42Z

+      expect(subscribedEvents).toHaveLength(5);
+    });
+
+    it('calls ready() once, after subscriptions are wired', () => {


blocking: this test says ready() happens after subscriptions are wired, but it only checks that ready() was called once.

If the implementation moved ready() before the subscribe(...) calls, this test would still pass. Since this is new contract coverage, let's assert the ordering too, using Vitest's mock invocation order.

fredericoo · 2026-06-15T13:35:42Z

+
+      // A subsequent re-render must not re-wire — the loadedEvent.current guard
+      // is what prevents it once deps stop changing.
+      rerender(<PerfKit shop={SHOP} />);


blocking: this doesn't actually exercise the loadedEvent.current guard.

On the final rerender, the effect deps are unchanged (subscribe, ready, and scriptStatus are the same values), so React doesn't rerun the effect at all. If someone removed the guard, this test would still pass.

Let's force a dependency change after the first successful wiring - e.g. done -> loading -> done - and assert the subscription count stays at 5 on the second done.

fredericoo · 2026-06-15T13:35:42Z

+      expect(setPageType).toHaveBeenCalledWith(pageType);
+    });
+
+    it('does not throw when window.PerfKit is absent (script-load race)', () => {


non-blocking: this only exercises the page_viewed callback while window.PerfKit is absent.

The implementation uses optional chaining for all five callbacks, so it would be nice to iterate through every subscribed callback here and assert none of them throw. Otherwise a future unsafe setPageType(...) callback could slip through while this test still passes.

fredericoo · 2026-06-15T13:38:15Z

+
+      // A subsequent re-render must not re-wire — the loadedEvent.current guard
+      // is what prevents it once deps stop changing.
+      rerender(<PerfKit shop={SHOP} />);


blocking: this does not actually exercise the loadedEvent.current guard.

On the final rerender, the effect deps are unchanged (subscribe, ready, and scriptStatus are the same values), so React does not rerun the effect at all. If someone removed the guard, this test would still pass.

We should force a dependency change after the first successful wiring - e.g. done -> loading -> done - and assert the subscription count stays at 5 on the second done.

dangayle force-pushed the add-analytics-perfkit-diagnostics branch from d6e6b62 to da534b6 Compare June 2, 2026 01:17

dangayle changed the title ~~Add Hydrogen analytics and PerfKit diagnostic foundation~~ Add PerfKit integration contract tests Jun 2, 2026

dangayle marked this pull request as ready for review June 3, 2026 23:00

dangayle requested a review from a team as a code owner June 3, 2026 23:00

andguy95 approved these changes Jun 4, 2026

View reviewed changes

Comment thread .changeset/perfkit-contract-tests.md

andguy95 requested changes Jun 4, 2026

View reviewed changes

Changeset: bump @Shopify/hydrogen patch (PerfKit.tsx is modified)

3ca15c8

Per PR review: the PR touches PerfKit.tsx (exports PERF_KIT_URL, memoizes attributes), so it needs a patch changeset rather than an empty one.

andguy95 approved these changes Jun 4, 2026

View reviewed changes

freddieshaihulud reviewed Jun 8, 2026

View reviewed changes

Comment thread .changeset/perfkit-contract-tests.md Outdated

freddieshaihulud reviewed Jun 8, 2026

View reviewed changes

Comment thread .changeset/perfkit-contract-tests.md Outdated

fredericoo and others added 2 commits June 15, 2026 11:23

Update .changeset/perfkit-contract-tests.md

6181b7b

Co-authored-by: freddie <freddieshaihulud@gmail.com>

Merge branch 'main' into add-analytics-perfkit-diagnostics

77eca7e

fredericoo requested changes Jun 15, 2026

View reviewed changes

Apply suggestion from @fredericoo

a02d78b

fredericoo reviewed Jun 15, 2026

View reviewed changes

Comment thread packages/hydrogen/src/analytics-manager/PerfKit.tsx Outdated

fix: sampling to 10

3ddc3aa

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add PerfKit integration contract tests#3774

Add PerfKit integration contract tests#3774
dangayle wants to merge 6 commits into
mainfrom
add-analytics-perfkit-diagnostics

dangayle commented Jun 1, 2026 •

edited

Loading

Uh oh!

shopify Bot commented Jun 1, 2026 •

edited

Loading

Uh oh!

Uh oh!

andguy95 left a comment •

edited

Loading

Uh oh!

Uh oh!

dangayle commented Jun 8, 2026 via email

Uh oh!

Uh oh!

Uh oh!

fredericoo Jun 15, 2026

Uh oh!

fredericoo Jun 15, 2026

Uh oh!

fredericoo Jun 15, 2026

Uh oh!

fredericoo Jun 15, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

dangayle commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does

What the tests lock down

About versions

Scope / impact

Checks run

Follow-ups (separate, not in this PR)

Uh oh!

shopify Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

andguy95 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dangayle commented Jun 8, 2026 via email

Uh oh!

Uh oh!

Uh oh!

fredericoo Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

fredericoo Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

fredericoo Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

fredericoo Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dangayle commented Jun 1, 2026 •

edited

Loading

shopify Bot commented Jun 1, 2026 •

edited

Loading

andguy95 left a comment •

edited

Loading