fix: (vite-dev-server) wait for support file (#33487)

Author: mschile

cli/CHANGELOG.md

@@ -8,6 +8,7 @@
 **Bugfixes:**
 
  - Increased the limit for decrypted payloads to support large `cy.prompt` requests and responses. Fixed in [#33619](https://github.com/cypress-io/cypress/pull/33619).
+ - Fixed a race condition in `@cypress/vite-dev-server` where the Cypress iframe could attempt to import the support file before Vite had finished serving it, causing intermittent "Failed to fetch dynamically imported module" errors in component tests. The dev server now waits until the support file URL returns a successful response before signaling that it is ready. Addressed in [#33487](https://github.com/cypress-io/cypress/pull/33487).
 
 ## 15.14.0
 

npm/vite-dev-server/src/devServer.ts

@@ -3,6 +3,7 @@ import semverMajor from 'semver/functions/major.js'
 import type { UserConfig } from 'vite-7'
 import { getVite, Vite_7, Vite_8 } from './getVite.js'
 import { createViteDevServerConfig, isVite8 } from './resolveConfig.js'
+import { getSupportFileRelativePath, waitUntilUrlReady } from './waitForSupportFile.js'
 
 const debug = debugFn('cypress:vite-dev-server:devServer')
 
@@ -38,14 +39,25 @@ export async function devServer (config: ViteDevServerConfig): Promise<Cypress.R
   debug('Vite server created')
 
   await server.listen()
-  const { port } = server.config.server
+  const { port, host } = server.config.server
 
   if (!port) {
     throw new Error('Missing vite dev server port.')
   }
 
   debug('Successfully launched the vite server on port', port)
 
+  const supportPath = getSupportFileRelativePath(config.cypressConfig)
+
+  if (supportPath) {
+    const baseUrl = `http://${typeof host === 'string' ? host : '127.0.0.1'}:${port}`
+    const supportFileUrl = new URL(supportPath, `${baseUrl}/`).href
+
+    debug('Waiting until support file is servable', supportFileUrl)
+    await waitUntilUrlReady(supportFileUrl)
+    debug('Support file is ready')
+  }
+
   return {
     port,
     // Close is for unit testing only. We kill this child process which will handle the closing of the server

npm/vite-dev-server/src/waitForSupportFile.ts

@@ -0,0 +1,72 @@
+/**
+ * Wait until the Vite dev server can serve the support file (HTTP 200).
+ * This makes the "dev server ready" signal deterministic and avoids the race
+ * where the iframe loads before the server has finished serving the module.
+ */
+
+const DEFAULT_MAX_ATTEMPTS = 30
+const DEFAULT_DELAY_MS = 200
+
+interface WaitUntilUrlReadyOptions {
+  maxAttempts?: number
+  delayMs?: number
+}
+
+/**
+ * Build the support file path (same logic as client/initCypressTests.js)
+ * so we poll the same URL the browser will request.
+ */
+export function getSupportFileRelativePath (cypressConfig: Cypress.PluginConfigOptions): string {
+  const { projectRoot, supportFile, devServerPublicPathRoute } = cypressConfig
+
+  if (!supportFile) {
+    return ''
+  }
+
+  let supportRelativeToProjectRoot = supportFile.replace(projectRoot, '')
+
+  if (cypressConfig.platform === 'win32') {
+    const platformProjectRoot = projectRoot.replace(/\//g, '\\')
+
+    supportRelativeToProjectRoot = supportFile.replace(platformProjectRoot, '')
+    supportRelativeToProjectRoot = supportRelativeToProjectRoot.replace(/\\/g, '/')
+  }
+
+  const devServerPublicPathBase = devServerPublicPathRoute === '' ? '.' : devServerPublicPathRoute
+
+  return `${devServerPublicPathBase}${supportRelativeToProjectRoot}`
+}
+
+/**
+ * Poll a URL until it returns a 2xx response or we exceed maxAttempts.
+ */
+export async function waitUntilUrlReady (
+  url: string,
+  options: WaitUntilUrlReadyOptions = {},
+): Promise<void> {
+  const { maxAttempts = DEFAULT_MAX_ATTEMPTS, delayMs = DEFAULT_DELAY_MS } = options
+
+  let lastError: Error | undefined
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const res = await fetch(url)
+
+      if (res.ok) {
+        return
+      }
+
+      lastError = new Error(`Support file URL returned ${res.status}`)
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err))
+    }
+
+    if (attempt < maxAttempts) {
+      await new Promise((resolve) => setTimeout(resolve, delayMs))
+    }
+  }
+
+  throw new Error(
+    `Vite dev server did not become ready in time (${maxAttempts} attempts). ${lastError?.message ?? ''}`,
+  )
+}

npm/vite-dev-server/test/waitForSupportFile.spec.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { getSupportFileRelativePath, waitUntilUrlReady } from '../src/waitForSupportFile'
+
+describe('waitForSupportFile', () => {
+  describe('getSupportFileRelativePath', () => {
+    it('builds path matching client logic when devServerPublicPathRoute is set', () => {
+      const cypressConfig = {
+        projectRoot: '/users/proj',
+        supportFile: '/users/proj/cypress/support/component.ts',
+        devServerPublicPathRoute: '/__cypress/src',
+        platform: 'darwin',
+      } as Cypress.PluginConfigOptions
+
+      expect(getSupportFileRelativePath(cypressConfig)).toBe('/__cypress/src/cypress/support/component.ts')
+    })
+
+    it('returns empty string when supportFile is not set', () => {
+      const cypressConfig = {
+        projectRoot: '/users/proj',
+        supportFile: undefined,
+        devServerPublicPathRoute: '/__cypress/src',
+        platform: 'darwin',
+      } as Cypress.PluginConfigOptions
+
+      expect(getSupportFileRelativePath(cypressConfig)).toBe('')
+    })
+
+    it('handles win32 paths with backslashes', () => {
+      const cypressConfig = {
+        projectRoot: 'C:\\users\\proj',
+        supportFile: 'C:\\users\\proj\\cypress\\support\\component.ts',
+        devServerPublicPathRoute: '/__cypress/src',
+        platform: 'win32',
+      } as Cypress.PluginConfigOptions
+
+      expect(getSupportFileRelativePath(cypressConfig)).toBe('/__cypress/src/cypress/support/component.ts')
+    })
+
+    it('uses relative path when devServerPublicPathRoute is empty', () => {
+      const cypressConfig = {
+        projectRoot: '/users/proj',
+        supportFile: '/users/proj/cypress/support/component.ts',
+        devServerPublicPathRoute: '',
+        platform: 'darwin',
+      } as Cypress.PluginConfigOptions
+
+      expect(getSupportFileRelativePath(cypressConfig)).toBe('./cypress/support/component.ts')
+    })
+  })
+
+  describe('waitUntilUrlReady', () => {
+    beforeEach(() => {
+      vi.stubGlobal('fetch', vi.fn())
+    })
+
+    afterEach(() => {
+      vi.unstubAllGlobals()
+    })
+
+    it('resolves when URL returns 200', async () => {
+      const fetchMock = vi.mocked(fetch)
+
+      fetchMock.mockResolvedValue({ ok: true } as Response)
+
+      await expect(waitUntilUrlReady('http://127.0.0.1:5173/__cypress/src/cypress/support/component.ts')).resolves.toBeUndefined()
+      expect(fetchMock).toHaveBeenCalledTimes(1)
+    })
+
+    it('retries until 200 then resolves', async () => {
+      const fetchMock = vi.mocked(fetch)
+
+      fetchMock
+      .mockResolvedValueOnce({ ok: false, status: 503 } as Response)
+      .mockResolvedValueOnce({ ok: true } as Response)
+
+      await expect(
+        waitUntilUrlReady('http://127.0.0.1:5173/ready', { maxAttempts: 3, delayMs: 1 }),
+      ).resolves.toBeUndefined()
+
+      expect(fetchMock).toHaveBeenCalledTimes(2)
+    })
+
+    it('throws after maxAttempts if URL never returns 2xx', async () => {
+      const fetchMock = vi.mocked(fetch)
+
+      fetchMock.mockResolvedValue({ ok: false, status: 404 } as Response)
+
+      await expect(
+        waitUntilUrlReady('http://127.0.0.1:5173/missing', { maxAttempts: 2, delayMs: 1 }),
+      ).rejects.toThrow(/did not become ready in time/)
+
+      expect(fetchMock).toHaveBeenCalledTimes(2)
+    })
+  })
+})