fix: resolve blank page on Vercel + add comprehensive Playwright e2e tests

Copilot · hotlong · Copilot · commit 85c0d2c71a7a · 2026-02-10T17:40:03.000Z
- Fix crypto module externalization causing blank page in production build
  (replaced `external: ['crypto']` with inline Vite plugin that stubs
  `createHash`/`createVerify` before Vite's browser-external resolve)
- Update playwright.config.ts to test production build via `vite preview`
- Enhance e2e/smoke.spec.ts with blank-page detection tests
- Add e2e/console-rendering.spec.ts for rendering &amp; navigation validation
- Add e2e job to CI workflow (.github/workflows/ci.yml)
- Apply same crypto fix to examples/msw-todo/vite.config.ts

Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -114,6 +114,49 @@ jobs:
           fi
           echo "All packages built successfully"
 
+  e2e:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20.x'
+          cache: 'pnpm'
+
+      - name: Turbo Cache
+        uses: actions/cache@v5
+        with:
+          path: node_modules/.cache/turbo
+          key: turbo-${{ runner.os }}-${{ github.sha }}
+          restore-keys: |
+            turbo-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Run E2E tests
+        run: pnpm test:e2e --project=chromium
+
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 14
+
   docs:
     name: Build Docs
     runs-on: ubuntu-latest
diff --git a/apps/console/vite.config.ts b/apps/console/vite.config.ts
@@ -11,7 +11,29 @@ export default defineConfig({
     'process.version': '"0.0.0"',
   },
 
-  plugins: [react()],
+  // @objectstack/core@2.0.4 statically imports Node.js crypto (for plugin hashing).
+  // The code already has a browser fallback, so we provide an empty stub instead of
+  // marking it as external (which emits a bare `import 'crypto'` that browsers reject).
+  // enforce: 'pre' ensures this runs before Vite's built-in browser-external resolve.
+  plugins: [
+    {
+      name: 'stub-crypto',
+      enforce: 'pre',
+      resolveId(id: string) {
+        if (id === 'crypto') return '\0crypto-stub';
+      },
+      load(id: string) {
+        if (id === '\0crypto-stub') {
+          return [
+            'export function createHash() { return { update() { return this; }, digest() { return ""; } }; }',
+            'export function createVerify() { return { update() { return this; }, end() {}, verify() { return false; } }; }',
+            'export default {};',
+          ].join('\n');
+        }
+      },
+    },
+    react(),
+  ],
   resolve: {
     extensions: ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json'],
     alias: {
@@ -73,14 +95,6 @@ export default defineConfig({
       transformMixedEsModules: true
     },
     rollupOptions: {
-      // @objectstack/core@2.0.4 statically imports Node.js crypto (for plugin hashing).
-      // The code already has a browser fallback, so we treat it as external in the browser build.
-      external: ['crypto'],
-      output: {
-        globals: {
-          crypto: '{}',
-        },
-      },
       onwarn(warning, warn) {
         if (
           warning.code === 'UNRESOLVED_IMPORT' &&
diff --git a/e2e/console-rendering.spec.ts b/e2e/console-rendering.spec.ts
@@ -0,0 +1,83 @@
+import { test, expect } from '@playwright/test';
+
+/**
+ * Console rendering & navigation E2E tests.
+ *
+ * These tests validate that the production build renders correctly and
+ * that client-side routing works — the two main failure modes that cause
+ * the "blank page on Vercel" issue.
+ */
+
+/** Wait for React to mount (at least one child inside #root). */
+async function waitForReactMount(page: import('@playwright/test').Page) {
+  await page.waitForFunction(
+    () => (document.getElementById('root')?.children.length ?? 0) > 0,
+    { timeout: 30_000 },
+  );
+}
+
+test.describe('Console Rendering', () => {
+  test('should not have critical console errors during bootstrap', async ({ page }) => {
+    const criticalErrors: string[] = [];
+
+    // Capture console.error calls that indicate fatal issues
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        const text = msg.text();
+        // Ignore benign errors (e.g. favicon 404, service-worker registration)
+        if (
+          text.includes('favicon') ||
+          text.includes('service-worker') ||
+          text.includes('mockServiceWorker')
+        ) {
+          return;
+        }
+        criticalErrors.push(text);
+      }
+    });
+
+    await page.goto('/');
+    await waitForReactMount(page);
+
+    expect(
+      criticalErrors,
+      `Critical console errors detected:\n${criticalErrors.join('\n')}`,
+    ).toEqual([]);
+  });
+
+  test('should resolve client-side routes without blank content', async ({ page }) => {
+    await page.goto('/');
+    await waitForReactMount(page);
+
+    // After routing, the page should have meaningful DOM content
+    const rootHTML = await page.locator('#root').innerHTML();
+    expect(rootHTML.length, 'React root innerHTML is empty').toBeGreaterThan(50);
+  });
+
+  test('should serve index.html for SPA fallback routes', async ({ page }) => {
+    // Vercel blank-page issues often stem from missing SPA rewrites.
+    // Navigate to a deep route — the server must return index.html (not 404).
+    const response = await page.goto('/apps/default/some-object');
+    expect(response?.status(), 'Deep route returned non-200 status').toBeLessThan(400);
+
+    await waitForReactMount(page);
+
+    // React should still mount
+    const root = page.locator('#root');
+    const childCount = await root.evaluate((el) => el.children.length);
+    expect(childCount, 'React did not mount on deep route').toBeGreaterThan(0);
+  });
+
+  test('should include the MSW service worker in the build output', async ({ page }) => {
+    // The mock server requires mockServiceWorker.js to be served from /public.
+    // If it's missing, the app may hang during bootstrap.
+    const response = await page.request.get('/mockServiceWorker.js');
+
+    // In production builds without MSW, 404 is acceptable.
+    // But if the build includes it, it must be valid JS.
+    if (response.ok()) {
+      const contentType = response.headers()['content-type'] || '';
+      expect(contentType).toContain('javascript');
+    }
+  });
+});
diff --git a/e2e/smoke.spec.ts b/e2e/smoke.spec.ts
@@ -1,29 +1,91 @@
 import { test, expect } from '@playwright/test';
 
 /**
- * Smoke test to verify the console app loads correctly.
- * This is a foundational E2E test that validates the basic app shell.
+ * Smoke tests for the console production build.
+ *
+ * These tests run against `vite preview` (the same artefact deployed to Vercel)
+ * and are designed to catch **blank-page** regressions caused by:
+ *   - Broken imports or missing modules in the production bundle
+ *   - Missing polyfills (e.g. `process`, `crypto`)
+ *   - Uncaught JavaScript exceptions during bootstrap
+ *   - Failed network requests for critical assets (JS/CSS bundles)
+ *   - React failing to mount into #root
  */
-test.describe('Console App', () => {
-  test('should load the home page', async ({ page }) => {
+
+/** Wait for React to mount (at least one child inside #root). */
+async function waitForReactMount(page: import('@playwright/test').Page) {
+  await page.waitForFunction(
+    () => (document.getElementById('root')?.children.length ?? 0) > 0,
+    { timeout: 30_000 },
+  );
+}
+
+test.describe('Console App – Smoke', () => {
+  test('should load the page without JavaScript errors', async ({ page }) => {
+    const errors: string[] = [];
+    page.on('pageerror', (err) => errors.push(err.message));
+
     await page.goto('/');
-    // Wait for the app to render
-    await page.waitForLoadState('networkidle');
-    // The page should have rendered something (not blank)
-    const body = page.locator('body');
-    await expect(body).not.toBeEmpty();
+    await waitForReactMount(page);
+
+    // The page must not have thrown any uncaught exceptions
+    expect(errors, 'Uncaught JS errors during page load').toEqual([]);
   });
 
-  test('should display the navigation sidebar', async ({ page }) => {
+  test('should render React content inside #root', async ({ page }) => {
+    await page.goto('/');
+    await waitForReactMount(page);
+
+    // #root must exist and have child elements (React mounted successfully)
+    const root = page.locator('#root');
+    await expect(root).toBeAttached();
+    const childCount = await root.evaluate((el) => el.children.length);
+    expect(childCount, '#root has no children – blank page detected').toBeGreaterThan(0);
+  });
+
+  test('should not show a blank page (meaningful text rendered)', async ({ page }) => {
+    await page.goto('/');
+    await waitForReactMount(page);
+
+    // The visible page text must not be empty
+    const bodyText = await page.locator('body').innerText();
+    expect(bodyText.trim().length, 'Page body has no visible text').toBeGreaterThan(0);
+  });
+
+  test('should load all JavaScript bundles without 404s', async ({ page }) => {
+    const failedAssets: string[] = [];
+
+    page.on('response', (response) => {
+      const url = response.url();
+      if (
+        (url.endsWith('.js') || url.endsWith('.css')) &&
+        response.status() >= 400
+      ) {
+        failedAssets.push(`${response.status()} ${url}`);
+      }
+    });
+
     await page.goto('/');
     await page.waitForLoadState('networkidle');
-    // The app shell should contain a navigation area
-    const nav = page.locator('nav').first();
-    await expect(nav).toBeVisible();
+
+    expect(failedAssets, 'Critical assets returned HTTP errors').toEqual([]);
   });
 
   test('should have correct page title', async ({ page }) => {
     await page.goto('/');
-    await expect(page).toHaveTitle(/.+/);
+    await expect(page).toHaveTitle(/ObjectStack|ObjectUI|Console/i);
+  });
+
+  test('should show the app shell or loading screen', async ({ page }) => {
+    await page.goto('/');
+
+    // Either the app shell (nav / sidebar) or the loading screen should appear
+    // within a reasonable time. Both are acceptable initial states.
+    const appShell = page.locator('nav').first();
+    const loadingScreen = page.getByText(/Initializing|Loading|Connecting/i).first();
+
+    await expect(
+      appShell.or(loadingScreen),
+    ).toBeVisible({ timeout: 30_000 });
   });
 });
diff --git a/examples/msw-todo/vite.config.ts b/examples/msw-todo/vite.config.ts
@@ -3,7 +3,29 @@ import react from '@vitejs/plugin-react';
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [react()],
+  // @objectstack/core@2.0.4 statically imports Node.js crypto (for plugin hashing).
+  // The code already has a browser fallback, so we provide an empty stub instead of
+  // marking it as external (which emits a bare `import 'crypto'` that browsers reject).
+  // enforce: 'pre' ensures this runs before Vite's built-in browser-external resolve.
+  plugins: [
+    {
+      name: 'stub-crypto',
+      enforce: 'pre',
+      resolveId(id: string) {
+        if (id === 'crypto') return '\0crypto-stub';
+      },
+      load(id: string) {
+        if (id === '\0crypto-stub') {
+          return [
+            'export function createHash() { return { update() { return this; }, digest() { return ""; } }; }',
+            'export function createVerify() { return { update() { return this; }, end() {}, verify() { return false; } }; }',
+            'export default {};',
+          ].join('\n');
+        }
+      },
+    },
+    react(),
+  ],
   server: {
     port: 3000,
   },
@@ -36,14 +58,6 @@ export default defineConfig({
         }
         warn(warning);
       },
-      // @objectstack/core@2.0.4 statically imports Node.js crypto (for plugin hashing).
-      // The code already has a browser fallback, so we treat it as external in the browser build.
-      external: ['crypto'],
-      output: {
-        globals: {
-          crypto: '{}',
-        },
-      },
     }
   }
 });
diff --git a/playwright.config.ts b/playwright.config.ts
@@ -2,6 +2,11 @@ import { defineConfig, devices } from '@playwright/test';
 
 /**
  * Playwright E2E test configuration for Object UI
+ *
+ * Tests run against the **production build** of the console app so that
+ * deployment-time issues (blank pages, broken imports, missing polyfills)
+ * are caught before they reach Vercel / other hosting platforms.
+ *
  * @see https://playwright.dev/docs/test-configuration
  */
 export default defineConfig({
@@ -18,8 +23,8 @@ export default defineConfig({
   reporter: process.env.CI ? 'github' : 'html',
   /* Shared settings for all projects */
   use: {
-    /* Base URL to use in actions like `await page.goto('/')` */
-    baseURL: 'http://localhost:5173',
+    /* Base URL – vite preview defaults to port 4173 */
+    baseURL: 'http://localhost:4173',
     /* Collect trace when retrying the failed test */
     trace: 'on-first-retry',
     /* Screenshot on failure */
@@ -51,11 +56,15 @@ export default defineConfig({
     },
   ],
 
-  /* Run your local dev server before starting the tests */
+  /**
+   * Build the console app and serve the production bundle via `vite preview`.
+   * This mirrors the Vercel deployment pipeline and catches blank-page issues
+   * caused by build-time errors (broken imports, missing polyfills, etc.).
+   */
   webServer: {
-    command: 'pnpm run dev:console',
-    url: 'http://localhost:5173',
+    command: 'pnpm --filter @object-ui/console build && pnpm --filter @object-ui/console preview --port 4173',
+    url: 'http://localhost:4173',
     reuseExistingServer: !process.env.CI,
-    timeout: 120 * 1000,
+    timeout: 180 * 1000,
   },
 });
