Merge remote-tracking branch 'origin/main' into otelbot/spec-integration-v1.55.0-dev

Author: otelbot[bot]

content/en/site/_index.md

@@ -32,8 +32,8 @@ Tentatively planned content organization:
 - [**Build**](./build/) — Tooling, local development setup, CI/CD workflows,
   deployment environments, and automation details.
 - **Deployment** — Deployment-specific behavior for the OpenTelemetry website.
-- **Quality** — Link checking, accessibility standards, tests, review practices,
-  and other quality-related processes.
+- [**Testing**](./testing/) — Link checking, accessibility standards, tests,
+  review practices, and other quality-related processes.
 - **Roadmap** — Milestones, backlog, priorities, technical debt, and
   design/implementation decisions.
 

content/en/site/testing/_index.md

@@ -0,0 +1,48 @@
+---
+title: Testing
+description: Checking and testing strategies, processes, and test pages.
+---
+
+This section contains checking and testing strategies, processes, and test pages
+used by website tests and deployed live checks.
+
+> This section is under construction.
+
+## Test assertions
+
+### Goal
+
+When a test fails, the output should make it obvious what was being checked and
+show a clear diff between actual and expected values, without long hand-written
+messages.
+
+For example, avoid:
+
+```js
+assert.ok(a === b, `expected ${a} to be ${b}`);
+```
+
+Instead favor:
+
+```js
+assert.strictEqual(status, expectedStatus, 'HTTP status');
+```
+
+### Guidance
+
+The points below use Node's built-in `node:test` runner and `assert` API because
+that is what several of our test suites use. The same ideas apply in other test
+frameworks: prefer assertions that produce tight diffs, keep failure context
+short and specific, and extract shared helpers when the same check repeats.
+
+1. Prefer `assert.strictEqual` over `assert.equal` for primitive checks where
+   strictness and diff quality matter.
+2. Add a short third argument as context, for example `HTTP status`,
+   `Content-Type`, `Location`, `Request body`.
+3. Use `assert.match` when a regular expression can capture the intent more
+   clearly than `includes` or chained `ok` logic.
+4. Put shared assertion helpers in a module imported by the test suites that use
+   them, colocated with those tests instead of copy-pasted across files. Other
+   small, test-only utilities can live in the same module when it stays focused
+   (for example `assertVaryIncludesAccept` in
+   `netlify/edge-functions/lib/test-helpers.ts`).

content/en/site/testing/tests/_index.md

@@ -0,0 +1,5 @@
+---
+title: Test pages
+---
+
+This section contains low-impact pages reserved for deployed live checks.

content/en/site/testing/tests/no-md.md

@@ -0,0 +1,6 @@
+---
+title: HTML-only test page
+outputs: [HTML]
+---
+
+This is a test page.

content/en/site/testing/tests/regular.md

@@ -0,0 +1,5 @@
+---
+title: Regular test page
+---
+
+This is a test page.

netlify/edge-functions/asset-tracking/README.md

@@ -5,12 +5,16 @@ tests.
 
 It tracks explicit asset-path requests by extension using `context.next()`
 (currently `*.md` and `*.txt`) and emits GA4 `asset_fetch` events for tracked
-`GET` requests regardless of response status.
+`GET` requests regardless of response status. Emitted events set `event_emitter`
+to `tracking`.
 
 If the request includes `X-Asset-Fetch-Ga-Info`, the function treats it as an
 internal subrequest and skips tracking. This prevents duplicate events when
 `markdown-negotiation` fetches sibling `index.md` assets internally.
 
+Responses also include `X-Asset-Fetch-Ga-Info` for coarse sanity-checking of the
+derived GA path and local GA-event candidate/config state.
+
 ### Live tests
 
 To run the live checks over a server:

netlify/edge-functions/asset-tracking/index.test.ts

@@ -14,65 +14,15 @@ import {
   ASSET_FETCH_GA_INFO_HEADER,
   INTERNAL_ASSET_FETCH_GA_INFO_VALUE,
 } from '../lib/ga4-asset-fetch.ts';
+import {
+  assertAssetFetchGa4Event,
+  createWaitUntilSpy,
+  firstAssetFetchEvent,
+  setupGa4CapturingFetchMock,
+  setupNetlifyEnv,
+} from '../lib/test-helpers.ts';
 import assetTracking, { shouldTrackAssetFetch } from './index.ts';
 
-function setupNetlifyEnv(t: { after: (fn: () => void) => void }) {
-  const g = globalThis as Record<string, unknown>;
-  const originalNetlify = g.Netlify;
-  t.after(() => {
-    g.Netlify = originalNetlify;
-  });
-
-  g.Netlify = {
-    env: {
-      get: (name: string) => {
-        if (name === 'HUGO_SERVICES_GOOGLEANALYTICS_ID') return 'G-TEST';
-        if (name === 'GA4_API_SECRET') return 'secret';
-        return undefined;
-      },
-    },
-  };
-}
-
-function setupFetchMock(t: { after: (fn: () => void) => void }) {
-  const originalFetch = globalThis.fetch;
-  t.after(() => {
-    globalThis.fetch = originalFetch;
-  });
-
-  const ga4Bodies: Record<string, unknown>[] = [];
-
-  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
-    const url =
-      input instanceof URL
-        ? input.toString()
-        : typeof input === 'string'
-          ? input
-          : input.url;
-
-    if (url.includes('google-analytics.com')) {
-      if (init?.body) {
-        ga4Bodies.push(JSON.parse(init.body as string));
-      }
-      return new Response('', { status: 200 });
-    }
-
-    return new Response('unexpected fetch', { status: 500 });
-  }) as typeof fetch;
-
-  return ga4Bodies;
-}
-
-function createWaitUntilSpy() {
-  const promises: Promise<unknown>[] = [];
-  return {
-    waitUntil: (p: Promise<unknown>) => {
-      promises.push(p);
-    },
-    flush: () => Promise.all(promises),
-  };
-}
-
 test('shouldTrackAssetFetch accepts GET .md requests', () => {
   const request = new Request(
     'https://example.com/docs/concepts/resources/index.md',
@@ -82,7 +32,11 @@ test('shouldTrackAssetFetch accepts GET .md requests', () => {
     status: 200,
   });
 
-  assert.equal(shouldTrackAssetFetch(request, response), true);
+  assert.strictEqual(
+    shouldTrackAssetFetch(request, response),
+    true,
+    'shouldTrackAssetFetch',
+  );
 });
 
 test('shouldTrackAssetFetch accepts GET .txt requests', () => {
@@ -92,7 +46,11 @@ test('shouldTrackAssetFetch accepts GET .txt requests', () => {
     status: 200,
   });
 
-  assert.equal(shouldTrackAssetFetch(request, response), true);
+  assert.strictEqual(
+    shouldTrackAssetFetch(request, response),
+    true,
+    'shouldTrackAssetFetch',
+  );
 });
 
 test('shouldTrackAssetFetch returns false for internal marked requests', () => {
@@ -109,7 +67,11 @@ test('shouldTrackAssetFetch returns false for internal marked requests', () => {
     status: 200,
   });
 
-  assert.equal(shouldTrackAssetFetch(request, response), false);
+  assert.strictEqual(
+    shouldTrackAssetFetch(request, response),
+    false,
+    'shouldTrackAssetFetch',
+  );
 });
 
 test('shouldTrackAssetFetch returns false for non-GET methods', () => {
@@ -123,7 +85,11 @@ test('shouldTrackAssetFetch returns false for non-GET methods', () => {
       status: 200,
     });
 
-    assert.equal(shouldTrackAssetFetch(request, response), false);
+    assert.strictEqual(
+      shouldTrackAssetFetch(request, response),
+      false,
+      'shouldTrackAssetFetch',
+    );
   }
 });
 
@@ -137,7 +103,11 @@ test('shouldTrackAssetFetch accepts non-2xx responses for tracked assets', () =>
       status,
     });
 
-    assert.equal(shouldTrackAssetFetch(request, response), true);
+    assert.strictEqual(
+      shouldTrackAssetFetch(request, response),
+      true,
+      'shouldTrackAssetFetch',
+    );
   }
 });
 
@@ -150,7 +120,11 @@ test('shouldTrackAssetFetch accepts non-markdown content type for tracked assets
     status: 200,
   });
 
-  assert.equal(shouldTrackAssetFetch(request, response), true);
+  assert.strictEqual(
+    shouldTrackAssetFetch(request, response),
+    true,
+    'shouldTrackAssetFetch',
+  );
 });
 
 test('shouldTrackAssetFetch returns false for non-tracked extensions', () => {
@@ -162,12 +136,16 @@ test('shouldTrackAssetFetch returns false for non-tracked extensions', () => {
     status: 200,
   });
 
-  assert.equal(shouldTrackAssetFetch(request, response), false);
+  assert.strictEqual(
+    shouldTrackAssetFetch(request, response),
+    false,
+    'shouldTrackAssetFetch',
+  );
 });
 
 test('handler emits asset_fetch for explicit .md requests', async (t) => {
   setupNetlifyEnv(t);
-  const ga4Bodies = setupFetchMock(t);
+  const ga4Bodies = setupGa4CapturingFetchMock(t);
   const spy = createWaitUntilSpy();
 
   const response = await assetTracking(
@@ -184,24 +162,28 @@ test('handler emits asset_fetch for explicit .md requests', async (t) => {
 
   await spy.flush();
 
-  assert.equal(response.status, 200);
-  assert.equal(ga4Bodies.length, 1);
-
-  const event = (
-    ga4Bodies[0].events as { name: string; params: Record<string, string> }[]
-  )[0];
-  assert.equal(event.name, 'asset_fetch');
-  assert.equal(event.params.asset_group, 'markdown');
-  assert.equal(event.params.asset_path, '/docs/concepts/resources/index.md');
-  assert.equal(event.params.asset_ext, 'md');
-  assert.equal(event.params.content_type, 'text/markdown');
-  assert.equal(event.params.status_code, '200');
-  assert.ok(!('original_path' in event.params));
+  assert.strictEqual(response.status, 200, 'HTTP status');
+  assert.strictEqual(
+    response.headers.get('x-asset-fetch-ga-info'),
+    '/docs/concepts/resources/index.md;ga-event-candidate,config-present',
+    'X-Asset-Fetch-Ga-Info',
+  );
+
+  assertAssetFetchGa4Event(
+    firstAssetFetchEvent(ga4Bodies),
+    {
+      asset_path: '/docs/concepts/resources/index.md',
+      content_type: 'text/markdown',
+      status_code: '200',
+      event_emitter: 'tracking',
+    },
+    { expectOriginalPathAbsent: true },
+  );
 });
 
 test('handler emits asset_fetch for explicit .txt requests', async (t) => {
   setupNetlifyEnv(t);
-  const ga4Bodies = setupFetchMock(t);
+  const ga4Bodies = setupGa4CapturingFetchMock(t);
   const spy = createWaitUntilSpy();
 
   const response = await assetTracking(
@@ -218,24 +200,23 @@ test('handler emits asset_fetch for explicit .txt requests', async (t) => {
 
   await spy.flush();
 
-  assert.equal(response.status, 200);
-  assert.equal(ga4Bodies.length, 1);
-
-  const event = (
-    ga4Bodies[0].events as { name: string; params: Record<string, string> }[]
-  )[0];
-  assert.equal(event.name, 'asset_fetch');
-  assert.equal(event.params.asset_group, 'text');
-  assert.equal(event.params.asset_path, '/llms.txt');
-  assert.equal(event.params.asset_ext, 'txt');
-  assert.equal(event.params.content_type, 'text/plain');
-  assert.equal(event.params.status_code, '200');
-  assert.ok(!('original_path' in event.params));
+  assert.strictEqual(response.status, 200, 'HTTP status');
+
+  assertAssetFetchGa4Event(
+    firstAssetFetchEvent(ga4Bodies),
+    {
+      asset_path: '/llms.txt',
+      content_type: 'text/plain',
+      status_code: '200',
+      event_emitter: 'tracking',
+    },
+    { expectOriginalPathAbsent: true },
+  );
 });
 
 test('handler skips asset_fetch for internal marked explicit .md requests', async (t) => {
   setupNetlifyEnv(t);
-  const ga4Bodies = setupFetchMock(t);
+  const ga4Bodies = setupGa4CapturingFetchMock(t);
   const spy = createWaitUntilSpy();
 
   const response = await assetTracking(
@@ -256,13 +237,18 @@ test('handler skips asset_fetch for internal marked explicit .md requests', asyn
 
   await spy.flush();
 
-  assert.equal(response.status, 200);
-  assert.equal(ga4Bodies.length, 0);
+  assert.strictEqual(response.status, 200, 'HTTP status');
+  assert.strictEqual(ga4Bodies.length, 0, 'GA4 body count');
+  assert.strictEqual(
+    response.headers.get('x-asset-fetch-ga-info'),
+    'none: internal subrequest',
+    'X-Asset-Fetch-Ga-Info',
+  );
 });
 
 test('handler emits asset_fetch for explicit .md requests regardless of response status', async (t) => {
   setupNetlifyEnv(t);
-  const ga4Bodies = setupFetchMock(t);
+  const ga4Bodies = setupGa4CapturingFetchMock(t);
   const spy = createWaitUntilSpy();
 
   const response = await assetTracking(
@@ -279,16 +265,12 @@ test('handler emits asset_fetch for explicit .md requests regardless of response
 
   await spy.flush();
 
-  assert.equal(response.status, 404);
-  assert.equal(ga4Bodies.length, 1);
-
-  const event = (
-    ga4Bodies[0].events as { name: string; params: Record<string, string> }[]
-  )[0];
-  assert.equal(event.name, 'asset_fetch');
-  assert.equal(event.params.asset_group, 'markdown');
-  assert.equal(event.params.asset_path, '/docs/concepts/resources/index.md');
-  assert.equal(event.params.asset_ext, 'md');
-  assert.equal(event.params.content_type, 'text/plain');
-  assert.equal(event.params.status_code, '404');
+  assert.strictEqual(response.status, 404, 'HTTP status');
+
+  assertAssetFetchGa4Event(firstAssetFetchEvent(ga4Bodies), {
+    asset_path: '/docs/concepts/resources/index.md',
+    content_type: 'text/plain',
+    status_code: '404',
+    event_emitter: 'tracking',
+  });
 });