Fix Playwright port conflict in CI by disabling webServer auto-start

CHANGELOG.md

@@ -1,3 +1,30 @@
+## [2025-11-05] FIX: Playwright E2E Port Conflict in CI
+
+Summary
+Resolved GitHub Actions workflow failure caused by port 3000 conflict. CI workflow manually starts `netlify dev --port 8888`, but Playwright config attempted to auto-start its own server on port 3000, causing the port conflict error.
+
+Implementation
+- playwright.config.ts: Made `webServer` conditional on CI environment
+  - In CI: `webServer: undefined` (CI workflow already starts netlify dev on port 8888)
+  - In local dev: `webServer` starts Next.js with `reuseExistingServer: true` to avoid port conflicts
+  - Updated comments to clarify port reuse behavior
+- e2e/README.md: Updated CI Integration and Configuration sections
+  - Documented that CI workflow starts netlify dev separately
+  - Clarified Base URL defaults and server auto-start behavior
+  - Enhanced troubleshooting section for port conflicts
+
+Validation
+- Playwright config validation: ✅ PASS (`npx playwright test --list`)
+- TypeScript syntax check: ✅ PASS (no config-related errors)
+- CI/local mode differentiation: ✅ VERIFIED (webServer undefined in CI, configured in local)
+
+Technical Details
+- CI workflow sets `CI=true` and `BASE_URL=http://localhost:8888`
+- Playwright uses BASE_URL from environment, falling back to http://localhost:3000
+- No webServer conflicts: CI uses pre-started netlify dev; local dev uses Next.js with server reuse
+
+---
+
 ## [2025-11-04] CRITICAL FIX: Full-Stack Epistemic Alignment (Geometry ≠ Experience)
 
 Summary

e2e/README.md

@@ -88,14 +88,15 @@ Tests run automatically in GitHub Actions when `CI=true` is set. The config incl
 - GitHub reporter for annotations
 - Screenshots on failure
 - Trace on first retry
+- CI workflow starts netlify dev on port 8888 (Playwright won't auto-start a server in CI)
 
 ## Configuration
 
 See `playwright.config.ts` for full configuration including:
 
-- Base URL (defaults to http://localhost:8888)
+- Base URL (defaults to http://localhost:3000, or uses BASE_URL env var)
 - Browser projects (Chromium, Firefox, WebKit)
-- Web server auto-start
+- Web server auto-start (disabled in CI, enabled locally with server reuse)
 - Timeout settings
 - Reporter configuration
 
@@ -159,12 +160,18 @@ test('my test', async ({ page }) => {
 
 ### Port already in use
 
-Kill the existing process:
+If you see "port already in use" errors locally:
 
 ```bash
+# Kill existing Next.js dev server
+pkill -f "next dev"
+
+# Kill existing Netlify dev server
 pkill -f netlify
 ```
 
+Note: The Playwright config now uses `reuseExistingServer: true` for local development to prevent port conflicts. In CI, the webServer is disabled since the workflow starts netlify dev separately.
+
 ### Tests fail locally but pass in CI
 
 Check environment variables and ensure `.env` is configured correctly.

playwright.config.ts

@@ -34,12 +34,11 @@ export default defineConfig({
       use: { ...devices['Desktop Safari'] },
     },
   ],
-  webServer: {
+  webServer: process.env.CI ? undefined : {
     command: 'npm run dev',
     url: 'http://localhost:3000',
-    // Reuse existing server to avoid port 3000 conflicts in local dev
-    // In CI, start fresh to ensure clean test environment
-    reuseExistingServer: !process.env.CI,
+    // Reuse existing server to avoid port conflicts in local dev
+    reuseExistingServer: true,
     timeout: 120000,
     // Stdout: 'ignore' prevents npm output from cluttering test results
     stdout: 'ignore',