Add macOS E2E tests

Author: vdavid

apps/desktop/src-tauri/src/commands/e2e.rs

@@ -0,0 +1,16 @@
+//! E2E test support commands.
+
+/// Returns the `CMDR_E2E_START_PATH` env var when the `automation` feature is enabled.
+/// The frontend uses this to override startup paths for E2E tests.
+#[tauri::command]
+#[cfg(feature = "automation")]
+pub fn get_e2e_start_path() -> Option<String> {
+    std::env::var("CMDR_E2E_START_PATH").ok()
+}
+
+/// No-op fallback when the `automation` feature is disabled.
+#[tauri::command]
+#[cfg(not(feature = "automation"))]
+pub fn get_e2e_start_path() -> Option<String> {
+    None
+}

apps/desktop/src-tauri/src/commands/mod.rs

@@ -1,5 +1,6 @@
 //! Tauri commands module.
 
+pub mod e2e;
 pub mod file_system;
 pub mod file_viewer;
 pub mod font_metrics;

apps/desktop/src-tauri/src/lib.rs

@@ -695,6 +695,8 @@ pub fn run() {
             commands::indexing::cancel_nav_priority,
             commands::indexing::clear_drive_index,
             commands::indexing::set_indexing_enabled,
+            // E2E test support
+            commands::e2e::get_e2e_start_path,
         ])
         .on_window_event(|window, event| {
             // When the main window is closed, quit the entire app (including settings/debug/viewer windows)

apps/desktop/src/lib/file-explorer/pane/DualPaneExplorer.svelte

@@ -26,6 +26,7 @@
         type UnlistenFn,
         updateFocusedPane,
         findFileIndex,
+        getE2eStartPath,
     } from '$lib/tauri-commands'
     import type {
         VolumeInfo,
@@ -772,6 +773,13 @@
         rightViewMode = status.rightViewMode
         leftPaneWidthPercent = status.leftPaneWidthPercent
 
+        // E2E test override: use CMDR_E2E_START_PATH subdirectories when set
+        const e2eStartPath = await getE2eStartPath()
+        if (e2eStartPath) {
+            leftPath = `${e2eStartPath}/left`
+            rightPath = `${e2eStartPath}/right`
+        }
+
         // Load sort state
         leftSortBy = status.leftSortBy
         rightSortBy = status.rightSortBy
@@ -784,23 +792,23 @@
         // Exception: 'network' is a virtual volume, trust the stored ID for that
         const defaultId = await getDefaultVolumeId()
 
-        if (status.leftVolumeId === 'network') {
+        if (status.leftVolumeId === 'network' && !e2eStartPath) {
             leftVolumeId = 'network'
         } else {
-            const leftContaining = await findContainingVolume(status.leftPath)
+            const leftContaining = await findContainingVolume(leftPath)
             leftVolumeId = leftContaining?.id ?? defaultId
         }
 
-        if (status.rightVolumeId === 'network') {
+        if (status.rightVolumeId === 'network' && !e2eStartPath) {
             rightVolumeId = 'network'
         } else {
-            const rightContaining = await findContainingVolume(status.rightPath)
+            const rightContaining = await findContainingVolume(rightPath)
             rightVolumeId = rightContaining?.id ?? defaultId
         }
 
         // Initialize history with loaded paths and their volumes
-        leftHistory = createHistory(leftVolumeId, status.leftPath)
-        rightHistory = createHistory(rightVolumeId, status.rightPath)
+        leftHistory = createHistory(leftVolumeId, leftPath)
+        rightHistory = createHistory(rightVolumeId, rightPath)
 
         initialized = true
 

apps/desktop/src/lib/tauri-commands/index.ts

@@ -231,6 +231,7 @@ export {
     updateServiceResolveTimeout,
     setIndexingEnabled,
     getDirStatsBatch,
+    getE2eStartPath,
     getAiStatus,
     getAiModelInfo,
     startAiDownload,

apps/desktop/src/lib/tauri-commands/settings.ts

@@ -139,6 +139,22 @@ export async function isAiOptedOut(): Promise<boolean> {
     return invoke<boolean>('is_ai_opted_out')
 }
 
+// ============================================================================
+// E2E test support
+// ============================================================================
+
+/**
+ * Returns the CMDR_E2E_START_PATH env var when the automation feature is enabled.
+ * Returns null when the feature is disabled or the env var is not set.
+ */
+export async function getE2eStartPath(): Promise<string | null> {
+    return invoke<string | null>('get_e2e_start_path')
+}
+
+// ============================================================================
+// AI commands
+// ============================================================================
+
 /** Gets AI-generated folder name suggestions for the current directory. */
 export async function getFolderSuggestions(
     listingId: string,

apps/desktop/test/e2e-linux/CLAUDE.md

@@ -0,0 +1,79 @@
+# Linux E2E tests (Docker + tauri-driver)
+
+WebDriverIO E2E tests for Cmdr on Linux, using tauri-driver with WebKitGTK's WebKitWebDriver.
+
+This is the workhorse test suite. All platform-independent app logic lives here: dialog flows, keyboard nav, selection,
+view modes, file viewer, settings, command palette, and file operations. macOS tests only cover platform integration
+(APFS ops, volume detection).
+
+## Architecture
+
+```
+WebDriverIO ──HTTP:4444──> tauri-driver ──> WebKitWebDriver ──> WebKitGTK (in-app)
+```
+
+Runs inside a Docker container (Ubuntu 24.04) with Xvfb for headless GUI. The host's source code is mounted in, so the
+Tauri app is built inside the container.
+
+## Running
+
+```bash
+cd apps/desktop
+pnpm test:e2e:linux                # Docker (recommended, works from macOS)
+pnpm test:e2e:linux:build          # force rebuild Docker image
+pnpm test:e2e:linux:shell          # interactive shell in container for debugging
+pnpm test:e2e:linux:native         # native Linux only (requires Tauri prereqs)
+./scripts/e2e-linux.sh --clean     # nuke build cache (try this when tests fail oddly)
+```
+
+## Fixture system
+
+Tests use a shared fixture helper (`../e2e-shared/fixtures.ts`) that creates a temp directory tree at
+`/tmp/cmdr-e2e-<timestamp>/` with `left/` (text files, sub-dir, hidden file, bulk .dat files) and `right/` (empty).
+
+The `CMDR_E2E_START_PATH` env var tells the app where to open. Fixtures are fully recreated before each test via
+`recreateFixtures()` in the `beforeTest` hook so tests don't affect each other.
+
+## WebKitGTK WebDriver quirks
+
+These are critical for writing tests. Without these workarounds, tests will silently fail.
+
+### 1. Native clicks fail on non-form elements
+
+WebKitGTK's WebDriver rejects clicks on non-interactive container elements. **Use `jsClick()` (JS `el.click()`)
+instead:**
+
+```typescript
+async function jsClick(element: WebdriverIO.Element): Promise<void> {
+    await browser.execute((el: HTMLElement) => el.click(), element as unknown as HTMLElement)
+}
+```
+
+### 2. `browser.keys(' ')` doesn't deliver Space
+
+The Space character hits a CharKey/VirtualKey ambiguity in WebKitWebDriver. **Use the W3C Actions API instead:**
+
+```typescript
+await browser.action('key').down(' ').pause(50).up(' ').perform()
+await browser.releaseActions()
+```
+
+## Files
+
+| File                       | Purpose                                                         |
+| -------------------------- | --------------------------------------------------------------- |
+| `wdio.conf.ts`             | WebDriverIO config: spawns tauri-driver, manages fixtures       |
+| `app.spec.ts`              | 14 tests: rendering, keyboard nav, mouse interaction, dialogs   |
+| `file-operations.spec.ts`  | 8 tests: copy, move, rename, mkdir, view modes, hidden, palette |
+| `settings.spec.ts`         | 5 tests: settings panel                                         |
+| `viewer.spec.ts`           | 10 tests: file viewer                                           |
+| `docker/Dockerfile`        | Ubuntu 24.04 image with Tauri prereqs, Xvfb, Node, Rust        |
+| `docker/entrypoint.sh`     | Xvfb/dbus setup for headless GUI                                |
+| `tsconfig.json`            | TypeScript config for WDIO types                                |
+
+## Related
+
+- Shared fixture helper: `test/e2e-shared/fixtures.ts`
+- Full guide: `docs/tooling/e2e-testing-guide.md`
+- macOS E2E tests: `test/e2e-macos/` (platform integration only — APFS ops, volume detection)
+- Linux stubs: `src-tauri/src/stubs/` (volumes, network, permissions use stubs on Linux)