chore: stabilize integration test suite

.gitignore

@@ -30,6 +30,7 @@ site/src/**/*.md
 .verdaccio-storage
 .eslintcache
 _test_out/**
+tests/unit/utils/tmp
 *.crt
 *.key
 

src/utils/telemetry/report-error.ts

@@ -22,7 +22,7 @@ const dirPath = dirname(fileURLToPath(import.meta.url))
  */
 // @ts-expect-error TS(7006) FIXME: Parameter 'error' implicitly has an 'any' type.
 export const reportError = async function (error, config = {}) {
-  if (isCI) {
+  if (isCI || process.env.CI) {
     return
   }
   // convert a NotifiableError to an error class

tests/integration/commands/dev/dev.test.ts

@@ -382,14 +382,15 @@ describe.concurrent('command/dev', () => {
     t.expect(nodeVer).toBeGreaterThanOrEqual(18)
 
     await withSiteBuilder(t, async (builder) => {
+      const targetPort = await getPort()
       const externalServer = startExternalServer({
         host: '127.0.0.1',
-        port: 4567,
+        port: targetPort,
       })
       await builder.build()
 
       await withDevServer(
-        { cwd: builder.directory, command: 'node', framework: '#custom', targetPort: 4567, skipWaitPort: true },
+        { cwd: builder.directory, command: 'node', framework: '#custom', targetPort, skipWaitPort: true },
         async (server) => {
           const response = await fetch(`${server.url}/test`)
           t.expect(response.status).toBe(200)
@@ -828,13 +829,15 @@ describe.concurrent('command/dev', () => {
 
   test('deploy environment variables injected by onDev plugin hooks are injected into functions', async (t) => {
     await withSiteBuilder(t, async (builder) => {
+      const targetPort = await getPort()
+
       await builder
         .withNetlifyToml({
           config: {
             plugins: [{ package: './plugins/plugin' }],
             dev: {
               command: 'node index.mjs',
-              targetPort: 4445,
+              targetPort,
             },
           },
         })
@@ -889,7 +892,7 @@ describe.concurrent('command/dev', () => {
                 res.end();
               })
 
-              server.listen(4445)
+              server.listen(${targetPort.toString()})
               `,
         })
         .build()

tests/integration/commands/dev/redirects.test.ts

@@ -1,3 +1,6 @@
+import { readFile, writeFile } from 'fs/promises'
+import { join } from 'path'
+
 import getPort from 'get-port'
 import fetch from 'node-fetch'
 import { describe, expect, test } from 'vitest'
@@ -32,27 +35,50 @@ describe('redirects', async () => {
     })
   })
 
-  await setupFixtureTests('next-app', { devServer: { env: { NETLIFY_DEV_SERVER_CHECK_SSG_ENDPOINTS: 1 } } }, () => {
-    test<FixtureTestContext>('should prefer local files instead of redirect when not forced', async ({ devServer }) => {
-      const response = await fetch(`http://localhost:${devServer!.port}/test.txt`, {})
-
-      expect(response.status).toBe(200)
-
-      const result = await response.text()
-      expect(result.trim()).toEqual('hello world')
-    })
-
-    test<FixtureTestContext>('should check for the dynamic page existence before doing redirect', async ({
-      devServer,
-    }) => {
-      const response = await fetch(`http://localhost:${devServer!.port}/`, {})
-
-      expect(response.status).toBe(200)
-
-      const result = await response.text()
-      expect(result.toLowerCase()).not.toContain('netlify')
-    })
-  })
+  await setupFixtureTests(
+    'next-app',
+    {
+      devServer: { env: { NETLIFY_DEV_SERVER_CHECK_SSG_ENDPOINTS: 1 } },
+      setup: async ({ fixture }) => {
+        const targetPort = await getPort()
+        const packageJsonPath = join(fixture.directory, 'package.json')
+        const netlifyTomlPath = join(fixture.directory, 'netlify.toml')
+        const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8')) as { scripts: { dev: string } }
+
+        packageJson.scripts.dev = `next dev -p ${targetPort.toString()}`
+        await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`)
+        await writeFile(
+          netlifyTomlPath,
+          (
+            await readFile(netlifyTomlPath, 'utf8')
+          ).replace('targetPort = 6123', `targetPort = ${targetPort.toString()}`),
+        )
+      },
+    },
+    () => {
+      test<FixtureTestContext>('should prefer local files instead of redirect when not forced', async ({
+        devServer,
+      }) => {
+        const response = await fetch(`http://localhost:${devServer!.port}/test.txt`, {})
+
+        expect(response.status).toBe(200)
+
+        const result = await response.text()
+        expect(result.trim()).toEqual('hello world')
+      })
+
+      test<FixtureTestContext>('should check for the dynamic page existence before doing redirect', async ({
+        devServer,
+      }) => {
+        const response = await fetch(`http://localhost:${devServer!.port}/`, {})
+
+        expect(response.status).toBe(200)
+
+        const result = await response.text()
+        expect(result.toLowerCase()).not.toContain('netlify')
+      })
+    },
+  )
 
   test('should not check the endpoint existence for hidden proxies', async (t) => {
     await withSiteBuilder(t, async (builder) => {

tests/integration/commands/functions-serve/functions-serve.test.ts

@@ -17,19 +17,18 @@ import {
   createAIGatewayTestData,
 } from '../../utils/ai-gateway-helpers.js'
 
-const DEFAULT_PORT = 9999
 const SERVE_TIMEOUT = 180_000
 
 const withFunctionsServer = async (
   {
     args = [],
     builder,
-    port = DEFAULT_PORT,
+    port,
     env = {},
   }: {
     args?: string[]
     builder: SiteBuilder
-    port?: number
+    port: number
     env?: NodeJS.ProcessEnv
   },
   testHandler: () => Promise<unknown>,
@@ -74,8 +73,9 @@ describe.concurrent('functions:serve command', () => {
         })
         .build()
 
-      await withFunctionsServer({ builder }, async () => {
-        const response = await fetch(`http://localhost:9999/.netlify/functions/ping`)
+      const port = await getPort()
+      await withFunctionsServer({ builder, args: ['--port', port.toString()], port }, async () => {
+        const response = await fetch(`http://localhost:${port.toString()}/.netlify/functions/ping`)
         t.expect(await response.text()).toEqual('ping')
       })
     })

tests/integration/framework-detection.test.ts

@@ -1,4 +1,5 @@
 import execa from 'execa'
+import getPort from 'get-port'
 import fetch from 'node-fetch'
 import { describe, test } from 'vitest'
 
@@ -89,6 +90,7 @@ describe.concurrent('frameworks/framework-detection', () => {
 
   test('should warn if using static server and `targetPort` is configured', async (t) => {
     await withSiteBuilder(t, async (builder) => {
+      const targetPort = await getPort()
       await builder
         .withContentFile({
           path: 'public/index.html',
@@ -97,7 +99,7 @@ describe.concurrent('frameworks/framework-detection', () => {
         .build()
 
       await withDevServer(
-        { cwd: builder.directory, args: ['--dir', 'public', '--target-port', '3000'] },
+        { cwd: builder.directory, args: ['--dir', 'public', '--target-port', targetPort.toString()] },
         async ({ output, url }) => {
           const response = await fetch(url)
           const responseContent = await response.text()
@@ -111,11 +113,12 @@ describe.concurrent('frameworks/framework-detection', () => {
 
   test('should run `command` when both `command` and `targetPort` are configured', async (t) => {
     await withSiteBuilder(t, async (builder) => {
+      const targetPort = await getPort()
       await builder.withNetlifyToml({ config: { build: { publish: 'public' } } }).build()
 
       try {
         await withDevServer(
-          { cwd: builder.directory, args: ['--command', 'echo hello', '--target-port', '3000'] },
+          { cwd: builder.directory, args: ['--command', 'echo hello', '--target-port', targetPort.toString()] },
           async () => {},
           true,
         )
@@ -185,10 +188,15 @@ describe.concurrent('frameworks/framework-detection', () => {
 
   test('should throw if framework=#custom but command is missing', async (t) => {
     await withSiteBuilder(t, async (builder) => {
+      const targetPort = await getPort()
       await builder.withNetlifyToml({ config: { dev: { framework: '#custom' } } }).build()
 
       try {
-        await withDevServer({ cwd: builder.directory, args: ['--target-port', '3000'] }, async () => {}, true)
+        await withDevServer(
+          { cwd: builder.directory, args: ['--target-port', targetPort.toString()] },
+          async () => {},
+          true,
+        )
         t.expect.unreachable()
       } catch (err) {
         t.expect(err).toHaveProperty('stdout')
@@ -217,11 +225,12 @@ describe.concurrent('frameworks/framework-detection', () => {
 
   test('should start custom command if framework=#custom, command and targetPort are configured', async (t) => {
     await withSiteBuilder(t, async (builder) => {
+      const targetPort = await getPort()
       await builder.withNetlifyToml({ config: { dev: { framework: '#custom', publish: 'public' } } }).build()
 
       try {
         await withDevServer(
-          { cwd: builder.directory, args: ['--command', 'echo hello', '--target-port', '3000'] },
+          { cwd: builder.directory, args: ['--command', 'echo hello', '--target-port', targetPort.toString()] },
           async () => {},
           true,
         )
@@ -237,6 +246,7 @@ describe.concurrent('frameworks/framework-detection', () => {
 
   test(`should print specific error when command doesn't exist`, async (t) => {
     await withSiteBuilder(t, async (builder) => {
+      const targetPort = await getPort()
       await builder.build()
 
       try {
@@ -247,7 +257,7 @@ describe.concurrent('frameworks/framework-detection', () => {
               '--command',
               'oops-i-did-it-again forgot-to-use-a-valid-command',
               '--target-port',
-              '3000',
+              targetPort.toString(),
               '--framework',
               '#custom',
             ],
@@ -345,11 +355,12 @@ describe.concurrent('frameworks/framework-detection', () => {
 
   test('should not run framework detection if command and targetPort are configured', async (t) => {
     await withSiteBuilder(t, async (builder) => {
+      const targetPort = await getPort()
       await builder.withContentFile({ path: 'config.toml', content: '' }).build()
 
       try {
         await withDevServer(
-          { cwd: builder.directory, args: ['--command', 'echo hello', '--target-port', '3000'] },
+          { cwd: builder.directory, args: ['--command', 'echo hello', '--target-port', targetPort.toString()] },
           async () => {},
           true,
         )

tests/integration/utils/dev-server.ts

@@ -1,3 +1,4 @@
+import { readdir, readFile } from 'node:fs/promises'
 import path from 'node:path'
 import process from 'node:process'
 
@@ -14,10 +15,21 @@ export const getExecaOptions = ({ cwd, env }: { cwd: string; env: NodeJS.Process
 
   const { LANG, LC_ALL, ...baseEnv } = process.env
 
+  // Diagnostics for the Node 24 serve-mode hang. The trace flags surface any
+  // uncaught exception, deprecation warning, or process.exit. --report-on-signal
+  // makes Node emit a full diagnostic report (stacks + libuv handles) on SIGUSR2,
+  // written to a file in cwd. The test util sends SIGUSR2 just before the
+  // start-timeout fires so the report captures *what* the process is stuck on.
+  // Note: --report-on-fatalerror, --report-uncaught-exception, and
+  // --report-filename are NOT permitted in NODE_OPTIONS (Worker threads reject
+  // env vars containing them), so we keep this list to the allowed subset.
+  const traceFlags = '--trace-warnings --trace-uncaught --trace-exit --report-on-signal --report-signal=SIGUSR2'
+  const nodeOptions = baseEnv.NODE_OPTIONS ? `${baseEnv.NODE_OPTIONS} ${traceFlags}` : traceFlags
+
   return {
     cwd,
     extendEnv: false,
-    env: { ...baseEnv, BROWSER: 'none', ...env },
+    env: { ...baseEnv, BROWSER: 'none', NODE_OPTIONS: nodeOptions, ...env },
     encoding: 'utf8',
   }
 }
@@ -70,7 +82,7 @@ const startServer = async ({
   serve = false,
   skipWaitPort = false,
   targetPort,
-}: DevServerOptions): Promise<DevServer | { timeout: boolean; output: string }> => {
+}: DevServerOptions): Promise<DevServer | { timeout: boolean; output: string; error?: string; report?: string }> => {
   const port = await getPort()
   const host = 'localhost'
   const url = `http://${host}:${port}`
@@ -171,12 +183,62 @@ const startServer = async ({
         })
       }
     })
-    ps.catch((error) => !selfKilled && reject(error))
+    // The subprocess can exit cleanly (code 0) without ever emitting
+    // "Local dev server ready" — when that happens the promise above would hang until
+    // SERVER_START_TIMEOUT. Detect both clean and error exits and reject with the
+    // captured output so the failure is visible immediately.
+    ps.then(
+      (result) => {
+        if (!selfKilled) {
+          reject(
+            new Error(
+              `Dev server subprocess exited (code=${
+                result.exitCode
+              }) before "Local dev server ready" was emitted.\nstdout:\n${outputBuffer.join(
+                '',
+              )}\nstderr:\n${errorBuffer.join('')}`,
+            ),
+          )
+        }
+      },
+      (error: unknown) => {
+        if (!selfKilled) {
+          reject(error instanceof Error ? error : new Error(String(error)))
+        }
+      },
+    )
   })
 
   return await pTimeout(serverPromise, {
     milliseconds: SERVER_START_TIMEOUT,
-    fallback: () => ({ timeout: true, output: outputBuffer.join('') }),
+    fallback: async () => {
+      // Ask the (presumed-hung) subprocess to write a Node diagnostic report
+      // (stack traces + libuv handle state — i.e. *what* the process is stuck on).
+      // The report is written to a file in the subprocess's cwd; we read it
+      // back below.
+      let diagnosticReport = ''
+      if (ps.pid != null && !ps.killed) {
+        try {
+          process.kill(ps.pid, 'SIGUSR2')
+          await new Promise((resolve) => setTimeout(resolve, 2_000))
+          const entries = await readdir(cwd)
+          const reports = entries.filter((name) => name.startsWith('report.') && name.endsWith('.json')).sort()
+          if (reports.length > 0) {
+            const last = reports[reports.length - 1]
+            diagnosticReport = await readFile(path.join(cwd, last), 'utf8')
+          }
+        } catch {
+          // process may have already exited, or the report write may have failed —
+          // either way we want to fall through and surface what we have
+        }
+      }
+      return {
+        timeout: true,
+        output: outputBuffer.join(''),
+        error: errorBuffer.join(''),
+        report: diagnosticReport,
+      }
+    },
   })
 }
 
@@ -187,12 +249,14 @@ export const startDevServer = async (options: DevServerOptions, expectFailure?:
     try {
       // do not use destruction, as we use getters which otherwise would be evaluated here
       const devServer = await startServer({ ...options, expectFailure })
-      // @ts-expect-error TS(2339) FIXME: Property 'timeout' does not exist on type 'DevServ... Remove this comment to see the full error message
-      if (devServer.timeout) {
-        throw new Error(`Timed out starting dev server.\nServer Output:\n${devServer.output}`)
+      if ('timeout' in devServer && devServer.timeout) {
+        throw new Error(
+          `Timed out starting dev server.\nServer Output:\n${devServer.output}\nServer Error:\n${
+            devServer.error ?? ''
+          }\nDiagnostic Report:\n${devServer.report ?? '(none captured)'}`,
+        )
       }
-      // @ts-expect-error TS(2322) FIXME: Type 'DevServer | { timeout: boolean; output: stri... Remove this comment to see the full error message
-      return devServer
+      return devServer as DevServer
     } catch (error) {
       if (attempt === maxAttempts || expectFailure) {
         throw error