test(vitest-browser): state-based integration suites for GenericViewport and tools

.gitignore

@@ -78,3 +78,7 @@ CLAUDE.md
 vtk-js/
 .ohif-downstream/
 auth.json
+
+# Vitest browser mode run artifacts
+.vitest-attachments/
+tests/vitest-browser/__screenshots__/

tests/dicomImageLoaderWADOURI.spec.ts

@@ -5,10 +5,16 @@ import {
   visitExample,
   screenShotPaths,
   waitForImageRendered,
+  retryRemoteFixtures,
 } from './utils/index';
 import { dicomDimensions } from '../packages/dicomImageLoader/examples/dicomImageLoaderWADOURI/dicomDimensions';
 
 test.beforeEach(async ({ page }) => {
+  // Every image in this example is fetched over HTTP from
+  // raw.githubusercontent.com, which intermittently rate-limits/drops requests
+  // under the parallel workers on the self-hosted runner. Retry those fetches
+  // with backoff so a single dropped response doesn't fail the image load.
+  await retryRemoteFixtures(page);
   await visitExample(page, 'dicomImageLoaderWADOURI');
 });
 
@@ -86,6 +92,11 @@ async function selectImageAndWaitForRender(page: Page, imagePath: string) {
     () => page.locator('#imageSelector').selectOption(imagePath),
     {
       expectedImageId: getExpectedWadoImageId(imagePath),
+      // Larger budget than the 30s default: the large TG18 1k/2k images can
+      // legitimately take a while to download+decode on the self-hosted
+      // runner, and retryRemoteFixtures may add a few seconds of backoff on a
+      // transient GitHub-raw failure.
+      timeout: 60000,
     }
   );
 

tests/genericViewport/genericDicomImageLoaderWADOURI.spec.ts

@@ -5,6 +5,7 @@ import {
   createExampleUrl,
   screenShotPaths,
   waitForImageRendered,
+  retryRemoteFixtures,
 } from '../utils/index';
 import { dicomDimensions } from '../../packages/dicomImageLoader/examples/dicomImageLoaderWADOURI/dicomDimensions';
 
@@ -74,6 +75,11 @@ async function selectImageAndWaitForRender(page: Page, imagePath: string) {
     () => page.locator('#imageSelector').selectOption(imagePath),
     {
       expectedImageId: getExpectedWadoImageId(imagePath),
+      // Larger budget than the 30s default: the large TG18 1k/2k images can
+      // legitimately take a while to download+decode on the self-hosted
+      // runner, and retryRemoteFixtures may add a few seconds of backoff on a
+      // transient GitHub-raw failure.
+      timeout: 60000,
     }
   );
 
@@ -84,6 +90,11 @@ async function selectImageAndWaitForRender(page: Page, imagePath: string) {
 }
 
 test.beforeEach(async ({ page }) => {
+  // Every image in this example is fetched over HTTP from
+  // raw.githubusercontent.com, which intermittently rate-limits/drops requests
+  // under the parallel workers on the self-hosted runner. Retry those fetches
+  // with backoff so a single dropped response doesn't fail the image load.
+  await retryRemoteFixtures(page);
   const url = createExampleUrl(EXAMPLE + '.html');
   url.searchParams.set('type', 'next');
   await page.goto(url.toString());

tests/utils/index.ts

@@ -12,6 +12,7 @@ export { createExampleUrl } from './createExampleUrl';
 export { getSegmentationActorClassNames } from './getSegmentationActorClassNames';
 export { expectGenericViewportRuntime } from './expectGenericViewportRuntime';
 export { waitForImageRendered } from './waitForImageRendered';
+export { retryRemoteFixtures } from './retryRemoteFixtures';
 export {
   setupRenderTracking,
   waitForViewportsRendered,

tests/utils/retryRemoteFixtures.ts

@@ -0,0 +1,83 @@
+import type { APIResponse, Page, Route } from '@playwright/test';
+
+const DEFAULT_HOSTS = [/raw\.githubusercontent\.com/];
+
+interface RetryRemoteFixturesOptions {
+  /** Total attempts (including the first) before giving up. Default 4. */
+  attempts?: number;
+  /** Host patterns to intercept. Default: raw.githubusercontent.com. */
+  hosts?: RegExp[];
+  /** Per-attempt fetch timeout in ms. Default 20000. */
+  perAttemptTimeoutMs?: number;
+}
+
+/**
+ * DICOM fixtures for the loader examples are fetched over HTTP from
+ * raw.githubusercontent.com — most images from the cornerstone3D repo, the
+ * TG18 set from the external OHIF/viewer-testdata repo. Under the parallel
+ * Playwright workers on the self-hosted runner, GitHub raw intermittently
+ * rate-limits (429) or drops these requests. The loader issues a single
+ * XMLHttpRequest per image with no retry (see
+ * packages/dicomImageLoader/src/imageLoader/internal/xhrRequest.ts), so one
+ * bad response fails the whole image load and surfaces as a flaky
+ * `waitForImageRendered` timeout.
+ *
+ * Intercept those requests and retry them with exponential backoff from the
+ * Node side via `route.fetch`, then replay the successful response to the
+ * browser. Retries happen off the browser's single-shot XHR, the product code
+ * is untouched, and the example's public URLs are left as-is so the deployed
+ * docs demo is unaffected. Range requests are preserved because `route.fetch`
+ * forwards the original request (headers included).
+ *
+ * Install in a spec's `beforeEach` BEFORE navigating to the example.
+ */
+export async function retryRemoteFixtures(
+  page: Page,
+  options: RetryRemoteFixturesOptions = {}
+): Promise<void> {
+  const {
+    attempts = 4,
+    hosts = DEFAULT_HOSTS,
+    perAttemptTimeoutMs = 20000,
+  } = options;
+
+  await page.route(
+    (url) => hosts.some((host) => host.test(url.href)),
+    async (route: Route) => {
+      let lastResponse: APIResponse | undefined;
+
+      for (let attempt = 0; attempt < attempts; attempt++) {
+        try {
+          const response = await route.fetch({ timeout: perAttemptTimeoutMs });
+          const status = response.status();
+
+          // Only 429 and 5xx are transient; anything else (2xx, 3xx, 4xx
+          // other than 429) is a real answer we should replay immediately.
+          if (status !== 429 && status < 500) {
+            await route.fulfill({ response });
+            return;
+          }
+
+          lastResponse = response;
+        } catch {
+          // Network error / timeout: fall through to backoff and retry.
+        }
+
+        // Backoff after every failed attempt except when we are about to give
+        // up, so the caller's render-gate budget is not spent needlessly.
+        if (attempt < attempts - 1) {
+          const backoffMs = 500 * 2 ** attempt;
+          await new Promise((resolve) => setTimeout(resolve, backoffMs));
+        }
+      }
+
+      // Retries exhausted. Replay the last transient response if we have one,
+      // otherwise let the request proceed so the real network error surfaces.
+      if (lastResponse) {
+        await route.fulfill({ response: lastResponse });
+      } else {
+        await route.continue();
+      }
+    }
+  );
+}