@react-native-harness/jest 1.4.0-rc.1 → 1.4.0

package/src/diagnostics/__tests__/derivers.test.ts

@@ -0,0 +1,300 @@
+import { describe, expect, it } from 'vitest';
+import { createDiagnostics, getEmitter } from '@react-native-harness/tools';
+import type { ReportableEvent } from '@react-native-harness/bundler-metro';
+import type { AppConnection } from '@react-native-harness/bridge/server';
+import type { BridgeEvents } from '@react-native-harness/bridge';
+import { observeBridgeEvents, observeMetroEvents } from '../derivers.js';
+
+type HarnessBridgeEvents = {
+  connected: (connection: AppConnection) => void;
+  disconnected: () => void;
+  event: (event: BridgeEvents) => void;
+};
+
+const createFakeBridge = () => {
+  const listeners: { [K in keyof HarnessBridgeEvents]: Set<HarnessBridgeEvents[K]> } = {
+    connected: new Set(),
+    disconnected: new Set(),
+    event: new Set(),
+  };
+
+  return {
+    on: <T extends keyof HarnessBridgeEvents>(event: T, listener: HarnessBridgeEvents[T]) => {
+      listeners[event].add(listener as never);
+    },
+    off: <T extends keyof HarnessBridgeEvents>(event: T, listener: HarnessBridgeEvents[T]) => {
+      listeners[event].delete(listener as never);
+    },
+    emitConnected: () =>
+      listeners.connected.forEach((l) =>
+        l({} as AppConnection)
+      ),
+    emitDisconnected: () => listeners.disconnected.forEach((l) => l()),
+    emitEvent: (event: BridgeEvents) => listeners.event.forEach((l) => l(event)),
+    listenerCounts: () => ({
+      connected: listeners.connected.size,
+      disconnected: listeners.disconnected.size,
+      event: listeners.event.size,
+    }),
+  };
+};
+
+describe('observeMetroEvents', () => {
+  it('is a no-op and does not subscribe when diagnostics is disabled', () => {
+    const events = getEmitter<ReportableEvent>();
+    const diagnostics = createDiagnostics({ enabled: false });
+
+    const dispose = observeMetroEvents(events, diagnostics);
+    events.emit({
+      type: 'bundle_build_started',
+      buildID: '1',
+      bundleDetails: {
+        bundleType: 'bundle',
+        dev: true,
+        entryFile: 'index.js',
+        minify: false,
+        platform: 'ios',
+      },
+    });
+
+    expect(diagnostics.flush()).toEqual([]);
+    dispose();
+  });
+
+  it('correlates bundle_build_started/done via buildID into a span', () => {
+    const events = getEmitter<ReportableEvent>();
+    const diagnostics = createDiagnostics({ enabled: true });
+    observeMetroEvents(events, diagnostics);
+
+    events.emit({
+      type: 'bundle_build_started',
+      buildID: 'build-1',
+      bundleDetails: {
+        bundleType: 'bundle',
+        dev: true,
+        entryFile: 'index.js',
+        minify: false,
+        platform: 'ios',
+      },
+    });
+    events.emit({ type: 'bundle_build_done', buildID: 'build-1' });
+
+    const entries = diagnostics.flush();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.label).toBe('metro.bundle.build');
+    expect(entries[0]?.status).toBe('ok');
+    expect(entries[0]?.attrs).toMatchObject({
+      buildID: 'build-1',
+      platform: 'ios',
+      entryFile: 'index.js',
+    });
+  });
+
+  it('records a failed span for bundle_build_failed', () => {
+    const events = getEmitter<ReportableEvent>();
+    const diagnostics = createDiagnostics({ enabled: true });
+    observeMetroEvents(events, diagnostics);
+
+    events.emit({
+      type: 'bundle_build_started',
+      buildID: 'build-2',
+      bundleDetails: {
+        bundleType: 'bundle',
+        dev: true,
+        entryFile: 'index.js',
+        minify: false,
+        platform: 'android',
+      },
+    });
+    events.emit({ type: 'bundle_build_failed', buildID: 'build-2' });
+
+    const entries = diagnostics.flush();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.status).toBe('error');
+  });
+
+  it('records a bundle_request_observed mark', () => {
+    const events = getEmitter<ReportableEvent>();
+    const diagnostics = createDiagnostics({ enabled: true });
+    observeMetroEvents(events, diagnostics);
+
+    events.emit({
+      type: 'bundle_request_observed',
+      platform: 'ios',
+      requestKind: 'app',
+      timestamp: new Date().toISOString(),
+      url: '/index.bundle',
+    });
+
+    const entries = diagnostics.flush();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.label).toBe('metro.bundle.request');
+    expect(entries[0]?.kind).toBe('mark');
+    expect(entries[0]?.attrs).toEqual({ requestKind: 'app', platform: 'ios' });
+  });
+
+  it('dispose() unsubscribes the listener', () => {
+    const events = getEmitter<ReportableEvent>();
+    const diagnostics = createDiagnostics({ enabled: true });
+    const dispose = observeMetroEvents(events, diagnostics);
+
+    dispose();
+    events.emit({
+      type: 'bundle_request_observed',
+      platform: 'ios',
+      requestKind: 'app',
+      timestamp: new Date().toISOString(),
+      url: '/index.bundle',
+    });
+
+    expect(diagnostics.flush()).toEqual([]);
+  });
+});
+
+describe('observeBridgeEvents', () => {
+  it('is a no-op and does not subscribe when diagnostics is disabled', () => {
+    const bridge = createFakeBridge();
+    const diagnostics = createDiagnostics({ enabled: false });
+
+    observeBridgeEvents(bridge, diagnostics);
+    expect(bridge.listenerCounts()).toEqual({ connected: 0, disconnected: 0, event: 0 });
+  });
+
+  it('marks bridge.connected and bridge.disconnected', () => {
+    const bridge = createFakeBridge();
+    const diagnostics = createDiagnostics({ enabled: true });
+    observeBridgeEvents(bridge, diagnostics);
+
+    bridge.emitConnected();
+    bridge.emitDisconnected();
+
+    const entries = diagnostics.flush();
+    expect(entries.map((e) => e.label)).toEqual(['bridge.connected', 'bridge.disconnected']);
+    expect(entries.every((e) => e.kind === 'mark')).toBe(true);
+  });
+
+  it('records client.bundle.module for module bundling events', () => {
+    const bridge = createFakeBridge();
+    const diagnostics = createDiagnostics({ enabled: true });
+    observeBridgeEvents(bridge, diagnostics);
+
+    bridge.emitEvent({ type: 'module-bundling-finished', file: 'a.ts', duration: 12 });
+    bridge.emitEvent({
+      type: 'module-bundling-failed',
+      file: 'b.ts',
+      duration: 5,
+      error: 'boom',
+    });
+
+    const entries = diagnostics.flush();
+    expect(entries).toHaveLength(2);
+    expect(entries[0]).toMatchObject({
+      label: 'client.bundle.module',
+      duration: 12,
+      status: 'ok',
+      attrs: { file: 'a.ts' },
+    });
+    expect(entries[1]).toMatchObject({
+      label: 'client.bundle.module',
+      duration: 5,
+      status: 'error',
+      attrs: { file: 'b.ts' },
+    });
+  });
+
+  it('records client.setup-file for setup file bundling events', () => {
+    const bridge = createFakeBridge();
+    const diagnostics = createDiagnostics({ enabled: true });
+    observeBridgeEvents(bridge, diagnostics);
+
+    bridge.emitEvent({
+      type: 'setup-file-bundling-finished',
+      file: 'setup.ts',
+      setupType: 'setupFiles',
+      duration: 20,
+    });
+
+    const entries = diagnostics.flush();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      label: 'client.setup-file',
+      duration: 20,
+      attrs: { file: 'setup.ts', setupType: 'setupFiles' },
+    });
+  });
+
+  it('records client.collect for collection-finished', () => {
+    const bridge = createFakeBridge();
+    const diagnostics = createDiagnostics({ enabled: true });
+    observeBridgeEvents(bridge, diagnostics);
+
+    bridge.emitEvent({
+      type: 'collection-finished',
+      file: 'a.test.ts',
+      duration: 8,
+      totalTests: 3,
+    });
+
+    const entries = diagnostics.flush();
+    expect(entries[0]).toMatchObject({
+      label: 'client.collect',
+      duration: 8,
+      attrs: { file: 'a.test.ts', totalTests: 3 },
+    });
+  });
+
+  it('records client.suite and client.test with status', () => {
+    const bridge = createFakeBridge();
+    const diagnostics = createDiagnostics({ enabled: true });
+    observeBridgeEvents(bridge, diagnostics);
+
+    bridge.emitEvent({
+      type: 'suite-finished',
+      file: 'a.test.ts',
+      name: 'my suite',
+      duration: 100,
+      status: 'failed',
+    });
+    bridge.emitEvent({
+      type: 'test-finished',
+      file: 'a.test.ts',
+      suite: 'my suite',
+      name: 'my test',
+      ancestorTitles: [],
+      fullName: 'my suite my test',
+      startedAt: Date.now(),
+      duration: 15,
+      status: 'passed',
+    });
+
+    const entries = diagnostics.flush();
+    expect(entries[0]).toMatchObject({ label: 'client.suite', status: 'error' });
+    expect(entries[1]).toMatchObject({ label: 'client.test', status: 'ok' });
+  });
+
+  it('anchors recorded entries near "now - duration" using the host clock', () => {
+    const bridge = createFakeBridge();
+    const diagnostics = createDiagnostics({ enabled: true });
+    observeBridgeEvents(bridge, diagnostics);
+
+    const before = Date.now();
+    bridge.emitEvent({ type: 'module-bundling-finished', file: 'a.ts', duration: 50 });
+    const after = Date.now();
+
+    const [entry] = diagnostics.flush();
+    expect(entry?.startTime).toBeGreaterThanOrEqual(before - 50 - 5);
+    expect(entry?.startTime).toBeLessThanOrEqual(after - 50 + 5);
+  });
+
+  it('dispose() unsubscribes all listeners', () => {
+    const bridge = createFakeBridge();
+    const diagnostics = createDiagnostics({ enabled: true });
+    const dispose = observeBridgeEvents(bridge, diagnostics);
+
+    dispose();
+    expect(bridge.listenerCounts()).toEqual({ connected: 0, disconnected: 0, event: 0 });
+
+    bridge.emitConnected();
+    expect(diagnostics.flush()).toEqual([]);
+  });
+});

package/src/diagnostics/__tests__/report.test.ts

@@ -0,0 +1,128 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { DiagnosticEntry } from '@react-native-harness/tools';
+import { printSummary, writeTraceFile } from '../report.js';
+
+const makeSpanEntry = (
+  overrides: Partial<DiagnosticEntry> = {},
+): DiagnosticEntry => ({
+  label: 'metro.bundle.build',
+  startTime: 1_000,
+  duration: 250,
+  status: 'ok',
+  kind: 'span',
+  ...overrides,
+});
+
+describe('writeTraceFile', () => {
+  let projectRoot: string;
+
+  beforeEach(async () => {
+    projectRoot = await fs.mkdtemp(
+      path.join(os.tmpdir(), 'react-native-harness-report-test-'),
+    );
+  });
+
+  afterEach(async () => {
+    await fs.rm(projectRoot, { recursive: true, force: true });
+  });
+
+  it('writes a Chrome Trace Event JSON file under .harness/diagnostics', async () => {
+    const entries = [
+      makeSpanEntry({ attrs: { file: 'a.test.ts' } }),
+      makeSpanEntry({
+        label: 'bridge.connected',
+        duration: 0,
+        kind: 'mark',
+      }),
+    ];
+
+    const filePath = await writeTraceFile(entries, {
+      projectRoot,
+      runId: 'run-123',
+    });
+
+    expect(filePath).toBe(
+      path.join(projectRoot, '.harness', 'diagnostics', 'run-123.json'),
+    );
+
+    const raw = await fs.readFile(filePath, 'utf-8');
+    const parsed = JSON.parse(raw) as { traceEvents: Array<Record<string, unknown>> };
+
+    expect(parsed.traceEvents).toHaveLength(2);
+    expect(parsed.traceEvents[0]).toMatchObject({
+      name: 'metro.bundle.build',
+      ph: 'X',
+      ts: 1_000 * 1000,
+      dur: 250 * 1000,
+      pid: 1,
+      tid: 1,
+      args: { file: 'a.test.ts' },
+    });
+    expect(parsed.traceEvents[1]).toMatchObject({
+      name: 'bridge.connected',
+      ph: 'i',
+      s: 'g',
+    });
+  });
+
+  it('creates the diagnostics directory recursively when missing', async () => {
+    const filePath = await writeTraceFile([makeSpanEntry()], {
+      projectRoot,
+      runId: 'run-456',
+    });
+
+    const stat = await fs.stat(filePath);
+    expect(stat.isFile()).toBe(true);
+  });
+});
+
+describe('printSummary', () => {
+  it('does nothing when there are no entries', () => {
+    const lines: string[] = [];
+    printSummary([], (line) => lines.push(line));
+    expect(lines).toEqual([]);
+  });
+
+  it('groups by top-level namespace and sorts labels by total duration desc', () => {
+    const lines: string[] = [];
+    printSummary(
+      [
+        makeSpanEntry({ label: 'metro.bundle.build', duration: 100 }),
+        makeSpanEntry({ label: 'metro.bundle.build', duration: 200 }),
+        makeSpanEntry({ label: 'metro.init', duration: 50 }),
+        makeSpanEntry({ label: 'client.test', duration: 5000 }),
+      ],
+      (line) => lines.push(line),
+    );
+
+    const metroHeaderIndex = lines.indexOf('  metro');
+    const clientHeaderIndex = lines.indexOf('  client');
+    expect(metroHeaderIndex).toBeGreaterThanOrEqual(0);
+    expect(clientHeaderIndex).toBeGreaterThanOrEqual(0);
+
+    const bundleLine = lines.find((l) => l.includes('metro.bundle.build'));
+    expect(bundleLine).toContain('count=2');
+    expect(bundleLine).toContain('total=300ms');
+    expect(bundleLine).toContain('max=200ms');
+
+    const clientLine = lines.find((l) => l.includes('client.test'));
+    expect(clientLine).toContain('total=5.0s');
+  });
+
+  it('formats sub-second durations in ms and second+ durations in s', () => {
+    const lines: string[] = [];
+    printSummary(
+      [
+        makeSpanEntry({ label: 'a.b', duration: 999 }),
+        makeSpanEntry({ label: 'a.c', duration: 1500 }),
+      ],
+      (line) => lines.push(line),
+    );
+
+    expect(lines.find((l) => l.includes('a.b'))).toContain('999ms');
+    expect(lines.find((l) => l.includes('a.c'))).toContain('1.5s');
+  });
+});

package/src/diagnostics/derivers.ts

@@ -0,0 +1,170 @@
+import type { Diagnostics, DiagnosticSpan } from '@react-native-harness/tools';
+import type { HarnessBridge } from '@react-native-harness/bridge/server';
+import type { BridgeEvents } from '@react-native-harness/bridge';
+import type { MetroInstance, ReportableEvent } from '@react-native-harness/bundler-metro';
+
+/**
+ * Span/mark derivers translate existing domain event streams (Metro build
+ * events, bridge/device events) into diagnostics entries. This is the only
+ * place in the jest package that maps event shapes to diagnostic labels -
+ * business logic elsewhere stays free of diagnostics calls.
+ */
+
+const noopDispose = (): void => undefined;
+
+/**
+ * Observes Metro's reporter event stream and derives:
+ * - `metro.bundle.build` spans, correlated by `buildID` across
+ *   bundle_build_started -> bundle_build_done|bundle_build_failed.
+ * - `metro.bundle.request` marks from bundle_request_observed events.
+ */
+export const observeMetroEvents = (
+  events: MetroInstance['events'],
+  diagnostics: Diagnostics
+): (() => void) => {
+  if (!diagnostics.enabled) {
+    return noopDispose;
+  }
+
+  const inflightBuilds = new Map<string, DiagnosticSpan>();
+
+  const listener = (event: ReportableEvent): void => {
+    switch (event.type) {
+      case 'bundle_build_started': {
+        const span = diagnostics.start('metro.bundle.build', {
+          buildID: event.buildID,
+          platform: event.bundleDetails.platform,
+          entryFile: event.bundleDetails.entryFile,
+          dev: event.bundleDetails.dev,
+        });
+        inflightBuilds.set(event.buildID, span);
+        return;
+      }
+      case 'bundle_build_done': {
+        const span = inflightBuilds.get(event.buildID);
+        inflightBuilds.delete(event.buildID);
+        span?.end();
+        return;
+      }
+      case 'bundle_build_failed': {
+        const span = inflightBuilds.get(event.buildID);
+        inflightBuilds.delete(event.buildID);
+        span?.fail(new Error(`Metro bundle build ${event.buildID} failed`));
+        return;
+      }
+      case 'bundle_request_observed': {
+        diagnostics.mark('metro.bundle.request', {
+          requestKind: event.requestKind,
+          platform: event.platform,
+        });
+        return;
+      }
+      default:
+        return;
+    }
+  };
+
+  events.addListener(listener);
+  return () => {
+    events.removeListener(listener);
+  };
+};
+
+type MinimalBridge = Pick<HarnessBridge, 'on' | 'off'>;
+
+/**
+ * Observes bridge connection lifecycle and device-reported bridge events and
+ * derives:
+ * - `bridge.connected` / `bridge.disconnected` marks.
+ * - `client.bundle.module`, `client.setup-file`, `client.collect`,
+ *   `client.suite`, `client.test` completed spans, recorded via
+ *   diagnostics.record() since these events arrive with a `duration` already
+ *   measured on the (unsynced) device clock; we anchor them at host receipt
+ *   time instead of trusting the device's absolute clock.
+ */
+export const observeBridgeEvents = (
+  bridge: MinimalBridge,
+  diagnostics: Diagnostics
+): (() => void) => {
+  if (!diagnostics.enabled) {
+    return noopDispose;
+  }
+
+  const onConnected = (): void => {
+    diagnostics.mark('bridge.connected');
+  };
+
+  const onDisconnected = (): void => {
+    diagnostics.mark('bridge.disconnected');
+  };
+
+  const onEvent = (event: BridgeEvents): void => {
+    switch (event.type) {
+      case 'module-bundling-finished':
+        diagnostics.record({
+          label: 'client.bundle.module',
+          duration: event.duration,
+          attrs: { file: event.file },
+        });
+        return;
+      case 'module-bundling-failed':
+        diagnostics.record({
+          label: 'client.bundle.module',
+          duration: event.duration,
+          attrs: { file: event.file },
+          status: 'error',
+        });
+        return;
+      case 'setup-file-bundling-finished':
+        diagnostics.record({
+          label: 'client.setup-file',
+          duration: event.duration,
+          attrs: { file: event.file, setupType: event.setupType },
+        });
+        return;
+      case 'setup-file-bundling-failed':
+        diagnostics.record({
+          label: 'client.setup-file',
+          duration: event.duration,
+          attrs: { file: event.file, setupType: event.setupType },
+          status: 'error',
+        });
+        return;
+      case 'collection-finished':
+        diagnostics.record({
+          label: 'client.collect',
+          duration: event.duration,
+          attrs: { file: event.file, totalTests: event.totalTests },
+        });
+        return;
+      case 'suite-finished':
+        diagnostics.record({
+          label: 'client.suite',
+          duration: event.duration,
+          attrs: { file: event.file, name: event.name, status: event.status },
+          status: event.status === 'failed' ? 'error' : 'ok',
+        });
+        return;
+      case 'test-finished':
+        diagnostics.record({
+          label: 'client.test',
+          duration: event.duration,
+          attrs: { file: event.file, name: event.name, status: event.status },
+          status: event.status === 'failed' ? 'error' : 'ok',
+        });
+        return;
+      default:
+        return;
+    }
+  };
+
+  bridge.on('connected', onConnected);
+  bridge.on('disconnected', onDisconnected);
+  bridge.on('event', onEvent);
+
+  return () => {
+    bridge.off('connected', onConnected);
+    bridge.off('disconnected', onDisconnected);
+    bridge.off('event', onEvent);
+  };
+};

package/src/diagnostics/index.ts

@@ -0,0 +1,2 @@
+export { observeMetroEvents, observeBridgeEvents } from './derivers.js';
+export { writeTraceFile, printSummary } from './report.js';