feat(test-utils): Add Spotlight support for E2E tests

- Add @spotlightjs/spotlight dependency to test-utils
- Create spotlight.ts with startSpotlight() and event waiting helpers
- Add Spotlight mode to getPlaywrightConfig() via useSpotlight option
- Migrate react-router-7-lazy-routes test app as proof of concept
  - Use DSN workaround (http://spotlight@localhost:8969/0)
  - Remove custom event proxy in favor of Spotlight
  - Update tests to use waitForSpotlightTransaction

This migration eliminates the custom event proxy server which had
timing issues causing flaky tests. Spotlight provides a more robust
solution for capturing and streaming Sentry events during E2E tests.

Author: BYK

dev-packages/e2e-tests/test-applications/react-router-7-lazy-routes/package.json

@@ -44,6 +44,7 @@
   "devDependencies": {
     "@playwright/test": "~1.56.0",
     "@sentry-internal/test-utils": "link:../../../test-utils",
+    "@spotlightjs/spotlight": "^4.7.2",
     "serve": "14.0.1",
     "npm-run-all2": "^6.2.0"
   },

dev-packages/e2e-tests/test-applications/react-router-7-lazy-routes/playwright.config.mjs

@@ -1,7 +1,7 @@
 import { getPlaywrightConfig } from '@sentry-internal/test-utils';
 
 const config = getPlaywrightConfig({
-  startCommand: `pnpm start`,
+  useSpotlight: true,
 });
 
 export default config;

dev-packages/e2e-tests/test-applications/react-router-7-lazy-routes/src/index.tsx

@@ -55,9 +55,13 @@ function getRuntimeConfig(): { lazyRouteTimeout?: number; idleTimeout?: number }
 
 const runtimeConfig = getRuntimeConfig();
 
+// Use Spotlight DSN workaround - this makes the SDK send events directly to Spotlight
+// Spotlight runs on port 8969 by default and captures all Sentry events
+const SPOTLIGHT_DSN = 'http://spotlight@localhost:8969/0';
+
 Sentry.init({
   environment: 'qa', // dynamic sampling bias to keep transactions
-  dsn: process.env.REACT_APP_E2E_TEST_DSN,
+  dsn: SPOTLIGHT_DSN,
   integrations: [
     Sentry.reactRouterV7BrowserTracingIntegration({
       useEffect: React.useEffect,
@@ -75,8 +79,6 @@ Sentry.init({
   // for finer control
   tracesSampleRate: 1.0,
   release: 'e2e-test',
-
-  tunnel: 'http://localhost:3031',
 });
 
 const sentryCreateBrowserRouter = Sentry.wrapCreateBrowserRouterV7(createBrowserRouter);

dev-packages/e2e-tests/test-applications/react-router-7-lazy-routes/start-event-proxy.mjs

@@ -1,8 +1,8 @@
 import { expect, test } from '@playwright/test';
-import { waitForTransaction } from '@sentry-internal/test-utils';
+import { waitForSpotlightTransaction } from '@sentry-internal/test-utils';
 
 test('lazyRouteTimeout: Routes load within timeout window', async ({ page }) => {
-  const transactionPromise = waitForTransaction('react-router-7-lazy-routes', async transactionEvent => {
+  const transactionPromise = waitForSpotlightTransaction(async transactionEvent => {
     return (
       !!transactionEvent?.transaction &&
       transactionEvent.contexts?.trace?.op === 'navigation' &&
@@ -27,7 +27,7 @@ test('lazyRouteTimeout: Routes load within timeout window', async ({ page }) =>
 });
 
 test('lazyRouteTimeout: Infinity timeout always waits for routes', async ({ page }) => {
-  const transactionPromise = waitForTransaction('react-router-7-lazy-routes', async transactionEvent => {
+  const transactionPromise = waitForSpotlightTransaction(async transactionEvent => {
     return (
       !!transactionEvent?.transaction &&
       transactionEvent.contexts?.trace?.op === 'navigation' &&
@@ -51,7 +51,7 @@ test('lazyRouteTimeout: Infinity timeout always waits for routes', async ({ page
 });
 
 test('idleTimeout: Captures all activity with increased timeout', async ({ page }) => {
-  const transactionPromise = waitForTransaction('react-router-7-lazy-routes', async transactionEvent => {
+  const transactionPromise = waitForSpotlightTransaction(async transactionEvent => {
     return (
       !!transactionEvent?.transaction &&
       transactionEvent.contexts?.trace?.op === 'navigation' &&
@@ -79,7 +79,7 @@ test('idleTimeout: Captures all activity with increased timeout', async ({ page
 });
 
 test('idleTimeout: Finishes prematurely with low timeout', async ({ page }) => {
-  const transactionPromise = waitForTransaction('react-router-7-lazy-routes', async transactionEvent => {
+  const transactionPromise = waitForSpotlightTransaction(async transactionEvent => {
     return (
       !!transactionEvent?.transaction &&
       transactionEvent.contexts?.trace?.op === 'navigation' &&
@@ -107,7 +107,7 @@ test('idleTimeout: Finishes prematurely with low timeout', async ({ page }) => {
 });
 
 test('idleTimeout: Pageload on deeply nested route', async ({ page }) => {
-  const pageloadPromise = waitForTransaction('react-router-7-lazy-routes', async transactionEvent => {
+  const pageloadPromise = waitForSpotlightTransaction(async transactionEvent => {
     return (
       !!transactionEvent?.transaction &&
       transactionEvent.contexts?.trace?.op === 'pageload' &&

dev-packages/e2e-tests/test-applications/react-router-7-lazy-routes/tests/timeout-behaviour.test.ts

@@ -49,6 +49,7 @@
   "devDependencies": {
     "@playwright/test": "~1.56.0",
     "@sentry/core": "10.30.0",
+    "@spotlightjs/spotlight": "^4.7.2",
     "eslint-plugin-regexp": "^1.15.0"
   },
   "volta": {

dev-packages/e2e-tests/test-applications/react-router-7-lazy-routes/tests/transactions.test.ts

@@ -9,5 +9,16 @@ export {
   waitForPlainRequest,
 } from './event-proxy-server';
 
+export {
+  startSpotlight,
+  getSpotlightDsn,
+  waitForEnvelopeItem as waitForSpotlightEnvelopeItem,
+  waitForError as waitForSpotlightError,
+  waitForSession as waitForSpotlightSession,
+  waitForTransaction as waitForSpotlightTransaction,
+  clearEventBuffer as clearSpotlightEventBuffer,
+  getCurrentSpotlightInstance,
+} from './spotlight';
+
 export { getPlaywrightConfig } from './playwright-config';
 export { createBasicSentryServer } from './server';

dev-packages/test-utils/package.json

@@ -1,20 +1,34 @@
 import type { PlaywrightTestConfig } from '@playwright/test';
 
+interface PlaywrightConfigOptions {
+  /** Command to start the test app (not needed when using Spotlight) */
+  startCommand?: string;
+  /** Port for the test app */
+  port?: number;
+  /** Port for the event proxy (legacy mode only) */
+  eventProxyPort?: number;
+  /** Path to the event proxy file (legacy mode only) */
+  eventProxyFile?: string;
+  /**
+   * Use Spotlight instead of the custom event proxy server.
+   * When enabled, Spotlight will automatically run the app and capture events.
+   * The app's Sentry SDK should use the DSN workaround: http://spotlight@localhost:PORT/0
+   */
+  useSpotlight?: boolean;
+  /** Port for Spotlight sidecar. Defaults to 8969. Use 0 for dynamic port. */
+  spotlightPort?: number;
+  /** Enable debug output for Spotlight */
+  spotlightDebug?: boolean;
+}
+
 /** Get a playwright config to use in an E2E test app. */
 export function getPlaywrightConfig(
-  options?: {
-    startCommand?: string;
-    port?: number;
-    eventProxyPort?: number;
-    eventProxyFile?: string;
-  },
+  options?: PlaywrightConfigOptions,
   overwriteConfig?: Partial<PlaywrightTestConfig>,
 ): PlaywrightTestConfig {
   const testEnv = process.env['TEST_ENV'] || 'production';
   const appPort = options?.port || 3030;
-  const eventProxyPort = options?.eventProxyPort || 3031;
-  const eventProxyFile = options?.eventProxyFile || 'start-event-proxy.mjs';
-  const startCommand = options?.startCommand;
+  const useSpotlight = options?.useSpotlight || false;
 
   /**
    * See https://playwright.dev/docs/test-configuration.
@@ -71,31 +85,63 @@ export function getPlaywrightConfig(
     ],
 
     /* Run your local dev server before starting the tests */
-    webServer: [
-      {
-        command: `node ${eventProxyFile}`,
-        port: eventProxyPort,
-        stdout: 'pipe',
-        stderr: 'pipe',
-      },
-    ],
+    webServer: [],
   };
 
-  if (startCommand) {
-    // @ts-expect-error - we set `config.webserver` to an array above.
-    // TS just can't infer that and thinks it could also be undefined or an object.
+  if (useSpotlight) {
+    // Spotlight mode: Use Spotlight to run the app and capture events
+    // Spotlight auto-detects the start script from package.json
+    const spotlightPort = options?.spotlightPort ?? 8969;
+    const spotlightArgs = ['-f', 'json'];
+
+    if (spotlightPort !== 0) {
+      spotlightArgs.push('-p', String(spotlightPort));
+    }
+
+    if (options?.spotlightDebug) {
+      spotlightArgs.push('-d');
+    }
+
+    // @ts-expect-error - we set `config.webserver` to an array above
     config.webServer.push({
-      command: startCommand,
+      command: `yarn spotlight run ${spotlightArgs.join(' ')}`,
       port: appPort,
       stdout: 'pipe',
       stderr: 'pipe',
       env: {
-        // Inherit all environment variables from the parent process
-        // This is needed for env vars like NEXT_PUBLIC_SENTRY_SPOTLIGHT to be passed through
         ...process.env,
         PORT: appPort.toString(),
       },
     });
+  } else {
+    // Legacy mode: Use custom event proxy server
+    const eventProxyPort = options?.eventProxyPort || 3031;
+    const eventProxyFile = options?.eventProxyFile || 'start-event-proxy.mjs';
+    const startCommand = options?.startCommand;
+
+    // @ts-expect-error - we set `config.webserver` to an array above
+    config.webServer.push({
+      command: `node ${eventProxyFile}`,
+      port: eventProxyPort,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    if (startCommand) {
+      // @ts-expect-error - we set `config.webserver` to an array above
+      config.webServer.push({
+        command: startCommand,
+        port: appPort,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: {
+          // Inherit all environment variables from the parent process
+          // This is needed for env vars like NEXT_PUBLIC_SENTRY_SPOTLIGHT to be passed through
+          ...process.env,
+          PORT: appPort.toString(),
+        },
+      });
+    }
   }
 
   return {