test: add Playwright e2e suite and wire it into CI

Run the existing Playwright `_electron` suite in a new e2e.yml (Node 24 — the
version Electron bundles — under xvfb, with the Electron binary cached and
materialized for the cached-binary case). Add a launch/cleanup harness:
`launchApp` isolates each test with Electron's native `--user-data-dir` (the app
honors it via app.getPath('userData')) and can seed `app-data.json`; `pageByTitle`
selects a window by title since the app opens several views, most title-less, so
`firstWindow()` is ambiguous. Smoke tests: launch, the Welcome view renders a
Welcome-specific element, the multi-view composition is present (guards the
Phase 3 BrowserView->WebContentsView migration), and the app shuts down without
hanging (close in finally; job timeout bounds it).

Note: AI-assisted (Claude Code). Manually verified: 4 smoke tests pass locally
(yarn build && yarn test:e2e); tsc, eslint, prettier clean.

Author: notluquis

.github/workflows/e2e.yml

@@ -0,0 +1,69 @@
+name: E2E
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e:
+    name: 'Playwright (Linux)'
+    runs-on: ubuntu-latest
+    # Bound the job so a stuck Electron launch/close fails fast instead of
+    # tying up a runner; this suite specifically guards shutdown hangs.
+    timeout-minutes: 15
+    env:
+      # Only Electron is launched here, never Playwright's bundled browsers, so
+      # skip their download during yarn install (faster, fewer network flakes).
+      PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '1'
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          # Match the Node that the target Electron bundles (Electron 42 -> Node
+          # 24); do not run ahead of it. Node 26 broke Electron's install tooling.
+          node-version: '24.x'
+          cache: 'yarn'
+      # Cache the @electron/get binary download so launch does not depend on a
+      # fresh GitHub-releases fetch every run.
+      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: ~/.cache/electron
+          key: ${{ runner.os }}-electron-${{ hashFiles('yarn.lock') }}
+          restore-keys: ${{ runner.os }}-electron-
+      - run: yarn install --frozen-lockfile
+      # Electron's postinstall only extracts the binary into
+      # node_modules/electron/dist on a fresh download. On a ~/.cache/electron
+      # cache hit it skips that, leaving dist empty and launch failing with
+      # "Electron failed to install correctly", so materialize it explicitly.
+      - run: node node_modules/electron/install.js
+      - run: yarn build
+      # Electron needs system libraries; xvfb provides a display on the headless
+      # runner. The app launches up to four windows, so a real display beats
+      # --headless here.
+      - run: npx playwright install-deps
+      # A minimal Python env with jupyterlab so the env-backed tests run (a venv
+      # + pip is lighter than a full conda env for a smoke). The seeded
+      # app-data.json points the app at this interpreter.
+      - name: Provision a Python env for the env-backed e2e
+        run: |
+          python3 -m venv "$RUNNER_TEMP/jlab-venv"
+          "$RUNNER_TEMP/jlab-venv/bin/pip" install --quiet --upgrade pip jupyterlab
+          echo "JLAB_TEST_PYTHON_PATH=$RUNNER_TEMP/jlab-venv/bin/python" >> "$GITHUB_ENV"
+      - run: xvfb-run -a yarn test:e2e
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report
+          path: |
+            playwright-report/
+            test-results/
+          retention-days: 14

.gitignore

@@ -8,6 +8,8 @@ node_modules
 .cache
 .eslintcache
 coverage
+test-results
+playwright-report
 .vscode/*
 !.vscode/launch.json
 *.py[co]

playwright.config.ts

@@ -4,7 +4,8 @@ export default defineConfig({
   testDir: './test/e2e',
   timeout: 60000,
   retries: process.env.CI ? 2 : 0,
-  reporter: process.env.CI ? 'github' : 'list',
+  workers: process.env.CI ? 1 : undefined,
+  reporter: process.env.CI ? [['github'], ['html', { open: 'never' }]] : 'list',
   use: {
     trace: 'on-first-retry',
     video: 'on-first-retry'

test/e2e/helpers.ts

@@ -0,0 +1,66 @@
+import { _electron as electron, ElectronApplication } from '@playwright/test';
+import { stubAllDialogs } from 'electron-playwright-helpers';
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+// A fresh userData dir per launch keeps tests independent. Electron's native
+// --user-data-dir flag is honored because the app reads app.getPath('userData')
+// (see getUserDataDir in utils) and only overrides it on Snap. Returns the app
+// plus the temp userData dir so the caller can clean it up in a finally block.
+// If launch fails, the temp dir is removed here so repeated runs don't
+// accumulate dirs.
+//
+// Pass `pythonPath` to seed `app-data.json` before launch (the app reads
+// `appData.pythonPath`), which makes the app treat that env as configured and
+// enables the local-server welcome actions.
+export async function launchApp(opts?: {
+  pythonPath?: string;
+}): Promise<{ app: ElectronApplication; userDataDir: string }> {
+  const userDataDir = mkdtempSync(join(tmpdir(), 'jlab-e2e-'));
+  if (opts?.pythonPath) {
+    writeFileSync(
+      join(userDataDir, 'app-data.json'),
+      JSON.stringify({ pythonPath: opts.pythonPath })
+    );
+  }
+  try {
+    const app = await electron.launch({
+      args: ['.', `--user-data-dir=${userDataDir}`]
+    });
+    await stubAllDialogs(app);
+    return { app, userDataDir };
+  } catch (error) {
+    cleanup(userDataDir);
+    throw error;
+  }
+}
+
+export function cleanup(userDataDir: string): void {
+  rmSync(userDataDir, { recursive: true, force: true });
+}
+
+// The app opens several windows (titlebar, welcome, session, manager) and most
+// have an empty title, so firstWindow() is ambiguous. Poll windows() and match
+// on the page title instead. Post Electron 30 a WebContentsView also surfaces
+// as its own page here, so title matching stays the reliable selector.
+export async function pageByTitle(
+  app: ElectronApplication,
+  pattern: RegExp,
+  timeout = 15000
+) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    for (const page of app.windows()) {
+      try {
+        if (pattern.test(await page.title())) {
+          return page;
+        }
+      } catch {
+        // page may be mid-navigation; retry on the next pass
+      }
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`no window title matched ${pattern}`);
+}

test/e2e/smoke.test.ts

@@ -1,75 +1,60 @@
-import { _electron as electron, expect, test } from '@playwright/test';
-import { stubAllDialogs } from 'electron-playwright-helpers';
-import { mkdtempSync, rmSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
-
-let tempUserData: string;
-
-test.beforeEach(() => {
-  tempUserData = mkdtempSync(join(tmpdir(), 'jlab-e2e-'));
+import { expect, test } from '@playwright/test';
+import { cleanup, launchApp, pageByTitle } from './helpers';
+
+test('app launches and opens at least one window', async () => {
+  const { app, userDataDir } = await launchApp();
+  try {
+    await app.firstWindow();
+    expect(app.windows().length).toBeGreaterThan(0);
+  } finally {
+    await app.close();
+    cleanup(userDataDir);
+  }
 });
 
-test.afterEach(async () => {
-  rmSync(tempUserData, { recursive: true, force: true });
+test('on first run the Welcome window renders', async () => {
+  const { app, userDataDir } = await launchApp();
+  try {
+    // Selecting by title rather than firstWindow(): the app opens several
+    // windows and only this one is the welcome view.
+    const welcome = await pageByTitle(app, /welcome/i);
+    await welcome.waitForLoadState('domcontentloaded');
+    // Assert a Welcome-specific element, not just body, so a blank or error
+    // page would fail rather than pass.
+    await expect(welcome.locator('#new-notebook-link')).toBeVisible();
+  } finally {
+    await app.close();
+    cleanup(userDataDir);
+  }
 });
 
-test('app launches and shows a window', async () => {
-  const app = await electron.launch({
-    args: ['.'],
-    env: {
-      ...process.env,
-      JLAB_DESKTOP_HOME: tempUserData,
-      ELECTRON_IS_TEST: '1'
-    }
-  });
-
-  await stubAllDialogs(app);
-  const window = await app.firstWindow();
-  await window.waitForLoadState('domcontentloaded');
-
-  expect(app.windows().length).toBeGreaterThan(0);
-  await app.close();
+test('the session window composes multiple views (titlebar + welcome + content)', async () => {
+  const { app, userDataDir } = await launchApp();
+  try {
+    // Once the welcome view has settled, the BrowserView/WebContentsView
+    // composition should expose several views (titlebar, welcome, content area)
+    // as separate pages. A dropped view after the Phase 3 WebContentsView
+    // migration would lower this count.
+    await pageByTitle(app, /welcome/i);
+    await expect
+      .poll(() => app.windows().length, { timeout: 10000 })
+      .toBeGreaterThanOrEqual(3);
+  } finally {
+    await app.close();
+    cleanup(userDataDir);
+  }
 });
 
-test('app exits with code 0', async () => {
-  const app = await electron.launch({
-    args: ['.'],
-    env: {
-      ...process.env,
-      JLAB_DESKTOP_HOME: tempUserData,
-      ELECTRON_IS_TEST: '1'
-    }
-  });
-
-  await stubAllDialogs(app);
-  await app.firstWindow();
-
-  const exitCode = await app.close();
-  expect(exitCode).toBe(0);
-});
-
-test('first-run shows env selection when no env configured', async () => {
-  const app = await electron.launch({
-    args: ['.'],
-    env: {
-      ...process.env,
-      JLAB_DESKTOP_HOME: tempUserData,
-      ELECTRON_IS_TEST: '1',
-      // empty userData = no prior config = first run
-      APPDATA: tempUserData
-    }
-  });
-
-  await stubAllDialogs(app);
-  const window = await app.firstWindow();
-
-  // welcome view or env select should appear within 15s
-  await expect(
-    window.locator(
-      '#welcome-view, #env-select-dialog, [data-testid="env-select"]'
-    )
-  ).toBeVisible({ timeout: 15000 });
-
-  await app.close();
+test('app shuts down cleanly without hanging', async () => {
+  const { app, userDataDir } = await launchApp();
+  try {
+    await app.firstWindow();
+  } finally {
+    // Close in finally so the Electron process is always terminated, even if
+    // an earlier step throws. A hang here surfaces via the job timeout.
+    await app.close();
+    cleanup(userDataDir);
+  }
+  // close() has resolved, so the process exited and the windows are gone.
+  expect(app.windows().length).toBe(0);
 });