From 684cc30b19a8d8217e0f4fc3749ff59fafa31ba1 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 1 May 2026 10:46:40 +0000 Subject: [PATCH 1/4] Add Cursor Cloud specific instructions to AGENTS.md Document how to run the Electron app in the Cloud Agent VM environment, including the required flags to work around network service subprocess crashes in containerized environments. Add quick reference for key development commands and gotchas. Co-authored-by: yasser khan --- AGENTS.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index d9131e9fa62..5339b5e0eea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -266,3 +266,35 @@ Open Settings (`Ctrl/Cmd+,`) → switch logging to **Debug** → reproduce → * 3. **Restart** app (and computer if needed). 4. **Reset data** — **View → Clear All Data**, or delete the config directory. 5. **Collect debug logs and heap snapshots**. + +## Cursor Cloud specific instructions + +### Running the Electron app in Cloud Agent VMs + +The Cloud Agent VM has a TigerVNC X server on `:1` (owned by user `ubuntu`). To launch the app: + +1. Allow local X connections: `su - ubuntu -c "DISPLAY=:1 xhost +local:"` +2. Run with in-process network service (required to avoid network service subprocess crashes in this container environment): + ``` + export DISPLAY=:1 + /workspace/node_modules/electron/dist/electron dist/ --disable-dev-mode --no-sandbox --disable-gpu --disable-software-rasterizer --in-process-gpu --enable-features=NetworkServiceInProcess2 + ``` +3. GTK and dbus warnings are expected and harmless in this environment. + +### Key development commands + +All standard commands are documented in the table at the top of this file. Quick reference: + +- **Lint**: `npm run lint:js-quiet` +- **Type check**: `npm run check-types` +- **Unit tests**: `npm run test:unit` (Jest, 1140+ tests, ~3s) +- **Build (dev)**: `npm run build` (webpack, ~4s) +- **Run app**: `npm start` (builds + launches; on Linux runs `linux-dev-setup` first) +- **Dev mode (watch)**: `npm run watch` (auto-rebuild + Electron restart on file changes) +- **All checks**: `npm run check` (lint + type-check + build-config + unit tests in parallel) + +### Gotchas + +- `npm run linux-dev-setup` requires `sudo` to set SUID on `chrome-sandbox`. It runs automatically before `npm start` and `npm run watch`. +- The `postinstall` script runs `patch-package && electron-builder install-app-deps`. If native module compilation fails, ensure build tools (gcc, make, python3) are available. +- Electron 41 uses Chromium's utility process model; in constrained environments (Docker/Firecracker), child processes may segfault. The `--enable-features=NetworkServiceInProcess2` flag moves the network service in-process to work around this. From 9e76d9823a784257ca41736e978366811d9103b8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 1 May 2026 11:00:19 +0000 Subject: [PATCH 2/4] Add E2E Playwright test instructions to Cloud Agent docs Document setup steps, running commands, environment variables, and known container-environment limitations for the Playwright E2E test suite in Cloud Agent VMs. Co-authored-by: yasser khan --- AGENTS.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5339b5e0eea..43493f832a1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -293,8 +293,37 @@ All standard commands are documented in the table at the top of this file. Quick - **Dev mode (watch)**: `npm run watch` (auto-rebuild + Electron restart on file changes) - **All checks**: `npm run check` (lint + type-check + build-config + unit tests in parallel) +### E2E tests (Playwright) + +The E2E suite lives in `e2e/` with its own `package.json`. It uses Playwright's Electron support (not browser testing — no Playwright browsers needed). See `e2e/AGENTS.md` for full guidance. + +**Setup (one-time after npm install):** +```bash +cd e2e && npm install && cd .. +npm run build-test # builds webpack with NODE_ENV=test → outputs to e2e/dist/ +``` + +**Running tests:** +```bash +cd e2e +DISPLAY=:1 npx playwright test --reporter=list --workers=1 # all tests +DISPLAY=:1 npx playwright test specs/startup/welcome_screen_modal.test.ts --reporter=list --workers=1 # single file +npx playwright test --list # list all tests +``` + +**Environment variables for server-backed tests:** +- `MM_TEST_SERVER_URL` — e.g. `http://localhost:8065` +- `MM_TEST_USER_NAME` — e.g. `sysadmin` +- `MM_TEST_PASSWORD` — e.g. `Sys@dmin-sample1` + +**Known limitations in Cloud Agent VMs:** +- Tests that load external URLs (example.com, github.com) may time out on `waitForAppReady` because the Chromium network service subprocess crashes in the container environment. The fixture already passes `--no-sandbox --disable-gpu --disable-gpu-sandbox --no-zygote` etc., but some tests still need live network connectivity. +- Keyboard-shortcut-based tests may fail in headless/container environments (the `e2e/AGENTS.md` recommends IPC invocations over keyboard shortcuts for this reason). +- Tests tagged `@darwin` or `@win32` are platform-specific and won't run on Linux. + ### Gotchas - `npm run linux-dev-setup` requires `sudo` to set SUID on `chrome-sandbox`. It runs automatically before `npm start` and `npm run watch`. - The `postinstall` script runs `patch-package && electron-builder install-app-deps`. If native module compilation fails, ensure build tools (gcc, make, python3) are available. - Electron 41 uses Chromium's utility process model; in constrained environments (Docker/Firecracker), child processes may segfault. The `--enable-features=NetworkServiceInProcess2` flag moves the network service in-process to work around this. +- `DISPLAY=:1` must be set for any command that launches Electron (including E2E tests). The X server is managed by TigerVNC under the `ubuntu` user; run `su - ubuntu -c "DISPLAY=:1 xhost +local:"` once per session to allow root processes to connect. From 7ead269647eb5e545e00f452bf8745722c098117 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 1 May 2026 11:42:31 +0000 Subject: [PATCH 3/4] Fix E2E tests for headless/container CI environments - Remove --no-zygote flag: was preventing renderer child processes from spawning, causing all window URLs to be empty. The zygote process is essential for Chromium's process model. - Add --in-process-gpu and --enable-features=NetworkServiceInProcess2: prevents network service subprocess crashes in Firecracker/Docker. - Fix waitForAppReady to force-show the main window in headless/VNC environments where BrowserWindow.show() doesn't fire automatically. Before: only tests using emptyConfig (welcome screen) passed. After: 28+ tests pass including config, settings, menu bar, downloads. Co-authored-by: yasser khan --- e2e/fixtures/index.ts | 3 ++- e2e/helpers/appReadiness.ts | 16 +++++++++++++++- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/e2e/fixtures/index.ts b/e2e/fixtures/index.ts index b669817147d..a88ed8922da 100644 --- a/e2e/fixtures/index.ts +++ b/e2e/fixtures/index.ts @@ -83,8 +83,9 @@ export const test = base.extend({ '--disable-gpu', '--disable-gpu-sandbox', '--disable-dev-shm-usage', - '--no-zygote', '--disable-software-rasterizer', + '--in-process-gpu', + '--enable-features=NetworkServiceInProcess2', // Stability '--disable-breakpad', diff --git a/e2e/helpers/appReadiness.ts b/e2e/helpers/appReadiness.ts index eaa4b14aea2..ff856fb8e1d 100644 --- a/e2e/helpers/appReadiness.ts +++ b/e2e/helpers/appReadiness.ts @@ -19,7 +19,21 @@ export async function waitForAppReady(app: ElectronApplication): Promise { await expect.poll( async () => { try { - return await app.evaluate(() => (global as any).__e2eAppReady === true); + const ready = await app.evaluate(() => { + // In headless/VNC CI environments, the main window may not auto-show. + // Force-show it so the 'show' event fires and __e2eAppReady gets set. + if (!(global as any).__e2eAppReady) { + const refs = (global as any).__e2eTestRefs; + if (refs) { + const mainWin = refs.MainWindow.get(); + if (mainWin && !mainWin.isVisible()) { + mainWin.show(); + } + } + } + return (global as any).__e2eAppReady === true; + }); + return ready; } catch (error) { const message = error instanceof Error ? error.message : String(error); if ( From 1b69f92e431b1f6ce78e6a4c3029aead77491c9b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 1 May 2026 11:42:50 +0000 Subject: [PATCH 4/4] Update AGENTS.md: E2E tests now mostly pass in Cloud Agent VMs Co-authored-by: yasser khan --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 43493f832a1..1b919509467 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -317,9 +317,10 @@ npx playwright test --list # - `MM_TEST_PASSWORD` — e.g. `Sys@dmin-sample1` **Known limitations in Cloud Agent VMs:** -- Tests that load external URLs (example.com, github.com) may time out on `waitForAppReady` because the Chromium network service subprocess crashes in the container environment. The fixture already passes `--no-sandbox --disable-gpu --disable-gpu-sandbox --no-zygote` etc., but some tests still need live network connectivity. +- A few download-item tests that depend on specific download completion states may be flaky. - Keyboard-shortcut-based tests may fail in headless/container environments (the `e2e/AGENTS.md` recommends IPC invocations over keyboard shortcuts for this reason). - Tests tagged `@darwin` or `@win32` are platform-specific and won't run on Linux. +- Tests requiring a live Mattermost server need `MM_TEST_SERVER_URL`, `MM_TEST_USER_NAME`, `MM_TEST_PASSWORD` env vars. ### Gotchas