fix: assign random ports for e2e tests (#4676)

This is a follow on from #4653

This PR resolves flaky E2E tests caused by port collisions when running
tests in parallel.

Instead of deriving ports from package names (which can collide), this
new approach assigns a random, available port to each test server
instance.

Key Changes:

- Random Port Allocation: Each test server (Playwright, dummy servers)
gets a unique, random port at startup.
- File-based Sync: The server writes its assigned port to a port.txt
file in its test project directory, this is kept unique through using
the package name or another input string for the file name.
- Test Runner Sync: The test runner reads the port from that file to
build the correct URL.
- Automatic Cleanup: All port files are deleted at the start of each
test:e2e run to ensure fresh ports.

Local parallel runs (up to 10) have shown this to be stable and free of
collisions.

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: nlynzaad

.gitignore

@@ -23,6 +23,7 @@ coverage
 # tests
 packages/router-generator/tests/**/*.gen.ts
 packages/router-generator/tests/**/*.gen.js
+e2e/**/port*.txt
 
 # misc
 .DS_Store
@@ -77,4 +78,4 @@ vite.config.ts.timestamp_*
 
 **/llms
 
-**/.tanstack
+**/.tanstack

e2e/e2e-utils/package.json

@@ -14,5 +14,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {},
-  "devDependencies": {}
+  "devDependencies": {
+    "get-port-please": "^3.2.0"
+  }
 }

e2e/e2e-utils/src/derivePort.ts

@@ -1,27 +1,19 @@
-import * as crypto from 'node:crypto'
+import fs from 'node:fs'
+import { getRandomPort } from 'get-port-please'
 
 /**
- * Hash a string and map it to a range [min, max].
- * @param {string} input - The string to hash.
- * @param {number} min - Minimum port value.
- * @param {number} max - Maximum port value.
- * @returns {number} A port within the range [min, max].
+ * Check if a port has been allocated, if it hasn't generate a random port and save it.
+ * @param {string} input - port test allocation
+ * @returns {number} A random port.
  */
-export function derivePort(
-  input: string,
-  min: number = 5600,
-  max: number = 65535,
-): number {
-  // Hash the input using SHA-256
-  const hash = crypto.createHash('sha256').update(input).digest('hex')
+export async function derivePort(input: string): Promise<number> {
+  const portFile = `port-${input}.txt`
 
-  // Convert hash to an integer
-  const hashInt = parseInt(hash.slice(0, 8), 16) // Use the first 8 characters
+  if (!fs.existsSync(portFile)) {
+    fs.writeFileSync(portFile, (await getRandomPort()).toString())
+  }
 
-  // Map hash value to the port range
-  const port = min + (hashInt % (max - min + 1))
-
-  console.info(`Mapped "${input}" to port ${port}`)
-
-  return port
+  const portNumber = parseInt(await fs.promises.readFile(portFile, 'utf-8'))
+  console.info(`Mapped "${input}" to port ${portNumber}`)
+  return portNumber
 }

e2e/react-router/basic-esbuild-file-based/package.json

@@ -7,7 +7,7 @@
     "build": "esbuild src/main.tsx --bundle --outfile=dist/main.js && tsc --noEmit",
     "serve": "esbuild src/main.tsx --bundle --outfile=dist/main.js --servedir=.",
     "start": "dev",
-    "test:e2e": "playwright test --project=chromium"
+    "test:e2e": "rm -rf port*.txt; playwright test --project=chromium"
   },
   "dependencies": {
     "@tanstack/react-router": "workspace:^",

e2e/react-router/basic-esbuild-file-based/playwright.config.ts

@@ -2,7 +2,7 @@ import { defineConfig, devices } from '@playwright/test'
 import { derivePort } from '@tanstack/router-e2e-utils'
 import packageJson from './package.json' with { type: 'json' }
 
-const PORT = derivePort(packageJson.name)
+const PORT = await derivePort(packageJson.name)
 const baseURL = `http://localhost:${PORT}`
 /**
  * See https://playwright.dev/docs/test-configuration.

e2e/react-router/basic-file-based-code-splitting/package.json

@@ -8,9 +8,9 @@
     "build": "vite build && tsc --noEmit",
     "serve": "vite preview",
     "start": "vite",
-    "test:e2e:verbose-routes:true": "VERBOSE_FILE_ROUTES=1 playwright test --project=chromium",
-    "test:e2e:verbose-routes:false": "VERBOSE_FILE_ROUTES=0 playwright test --project=chromium",
-    "test:e2e": "pnpm run test:e2e:verbose-routes:true && pnpm run test:e2e:verbose-routes:false"
+    "test:e2e:verbose-routes:true": "rm -rf port*.txt; VERBOSE_FILE_ROUTES=1 playwright test --project=chromium",
+    "test:e2e:verbose-routes:false": "rm -rf port*.txt; VERBOSE_FILE_ROUTES=0 playwright test --project=chromium",
+    "test:e2e": "rm -rf port*.txt; pnpm run test:e2e:verbose-routes:true && pnpm run test:e2e:verbose-routes:false"
   },
   "dependencies": {
     "@tanstack/react-router": "workspace:^",

e2e/react-router/basic-file-based-code-splitting/playwright.config.ts

@@ -2,7 +2,7 @@ import { defineConfig, devices } from '@playwright/test'
 import { derivePort } from '@tanstack/router-e2e-utils'
 import packageJson from './package.json' with { type: 'json' }
 
-const PORT = derivePort(packageJson.name)
+const PORT = await derivePort(packageJson.name)
 const baseURL = `http://localhost:${PORT}`
 /**
  * See https://playwright.dev/docs/test-configuration.

e2e/react-router/basic-file-based/package.json

@@ -8,7 +8,7 @@
     "build": "vite build && tsc --noEmit",
     "serve": "vite preview",
     "start": "vite",
-    "test:e2e": "playwright test --project=chromium"
+    "test:e2e": "rm -rf port*.txt; playwright test --project=chromium"
   },
   "dependencies": {
     "@tanstack/react-router": "workspace:^",

e2e/react-router/basic-file-based/playwright.config.ts

@@ -2,7 +2,7 @@ import { defineConfig, devices } from '@playwright/test'
 import { derivePort } from '@tanstack/router-e2e-utils'
 import packageJson from './package.json' with { type: 'json' }
 
-const PORT = derivePort(packageJson.name)
+const PORT = await derivePort(packageJson.name)
 const baseURL = `http://localhost:${PORT}`
 /**
  * See https://playwright.dev/docs/test-configuration.

e2e/react-router/basic-file-based/tests/redirect.spec.ts

@@ -8,8 +8,8 @@ import queryString from 'node:querystring'
 // somehow playwright does not correctly import default exports
 const combinate = (combinateImport as any).default as typeof combinateImport
 
-const PORT = derivePort(packageJson.name)
-const EXTERNAL_HOST_PORT = derivePort(`${packageJson.name}-external`)
+const PORT = await derivePort(packageJson.name)
+const EXTERNAL_HOST_PORT = await derivePort(`${packageJson.name}-external`)
 
 test.describe('redirects', () => {
   let server: Server