@srsholmes/tauri-playwright 0.1.0

package/README.md

@@ -0,0 +1,483 @@
+# tauri-playwright
+
+Playwright E2E testing for Tauri desktop apps. Controls the real native webview (WKWebView, WebView2, WebKitGTK) with a Playwright-compatible API — auto-waiting, locator assertions, semantic selectors, network mocking, native screenshots, and video recording.
+
+## The Problem
+
+Tauri apps use system webviews instead of Chromium. Playwright requires Chrome DevTools Protocol (CDP), but only WebView2 (Windows) supports it. **Standard Playwright integration is impossible on macOS and Linux.**
+
+## The Solution
+
+Three testing modes from the same test files:
+
+| Mode | Platform | How it works |
+|---|---|---|
+| `browser` | All | Headless Chromium with mocked Tauri IPC. Fast, CI-friendly. |
+| `tauri` | All | Socket bridge to the real Tauri webview. True E2E. |
+| `cdp` | Windows | Direct CDP to WebView2. Full native Playwright. |
+
+```
+┌──────────────────┐  socket/JSON  ┌──────────────────────────────────┐
+│  Playwright       │◄────────────►│  tauri-plugin-playwright          │
+│  test runner      │              │  (Rust, embedded in your app)     │
+│                   │              │                                   │
+│  @srsholmes/      │              │  Socket server → JS injection     │
+│  tauri-playwright │              │  HTTP polling  ← JS results       │
+└──────────────────┘              └──────────────────────────────────┘
+```
+
+## Quick Start
+
+### 1. Add the Rust plugin to your Tauri app
+
+```toml
+# src-tauri/Cargo.toml
+[features]
+e2e-testing = ["tauri-plugin-playwright"]
+
+[dependencies]
+tauri-plugin-playwright = { version = "0.1", optional = true }
+```
+
+```rust
+// src-tauri/src/lib.rs
+pub fn run() {
+    let mut builder = tauri::Builder::default()
+        .invoke_handler(tauri::generate_handler![/* your commands */]);
+
+    #[cfg(feature = "e2e-testing")]
+    {
+        builder = builder.plugin(tauri_plugin_playwright::init());
+    }
+
+    builder.run(tauri::generate_context!()).expect("error running app");
+}
+```
+
+### 2. Install the npm package
+
+```bash
+pnpm add -D @srsholmes/tauri-playwright @playwright/test
+npx playwright install chromium
+```
+
+### 3. Create test fixtures
+
+```ts
+// e2e/fixtures.ts
+import { createTauriTest } from '@srsholmes/tauri-playwright';
+
+export const { test, expect } = createTauriTest({
+  devUrl: 'http://localhost:1420',
+  ipcMocks: {
+    greet: (args) => `Hello, ${(args as { name?: string })?.name}!`,
+  },
+  mcpSocket: '/tmp/tauri-playwright.sock',
+});
+```
+
+### 4. Write tests
+
+```ts
+// e2e/tests/app.spec.ts
+import { test, expect } from '../fixtures';
+
+test('counter increments', async ({ tauriPage }) => {
+  await tauriPage.click('[data-testid="btn-increment"]');
+  await expect(tauriPage.locator('[data-testid="counter-value"]')).toContainText('1');
+});
+
+test('greets via Tauri IPC', async ({ tauriPage }) => {
+  await tauriPage.fill('[data-testid="greet-input"]', 'World');
+  await tauriPage.click('[data-testid="btn-greet"]');
+  await expect(tauriPage.getByTestId('greet-result')).toContainText('Hello, World!');
+});
+```
+
+### 5. Configure Playwright
+
+```ts
+// e2e/playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  projects: [
+    {
+      name: 'browser-only',
+      use: { ...devices['Desktop Chrome'], mode: 'browser' },
+    },
+    {
+      name: 'tauri',
+      use: { mode: 'tauri' },
+    },
+  ],
+  webServer: {
+    command: 'pnpm dev',
+    port: 1420,
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+### 6. Run tests
+
+```bash
+# Browser mode (headless, no Tauri needed)
+npx playwright test --project=browser-only
+
+# Tauri mode (start the app first)
+cargo tauri dev --features e2e-testing  # Terminal 1
+npx playwright test --project=tauri      # Terminal 2
+```
+
+## API Reference
+
+### Page Methods
+
+All actions auto-wait for the element to be visible and enabled (default 5s timeout, configurable).
+
+#### Interactions
+
+```ts
+await tauriPage.click(selector, { timeout? })
+await tauriPage.dblclick(selector)
+await tauriPage.hover(selector)
+await tauriPage.fill(selector, text)
+await tauriPage.type(selector, text)            // character by character
+await tauriPage.press(selector, 'Enter')
+await tauriPage.check(selector)
+await tauriPage.uncheck(selector)
+await tauriPage.selectOption(selector, value)
+await tauriPage.focus(selector)
+await tauriPage.blur(selector)
+await tauriPage.dragAndDrop(source, target)
+await tauriPage.dispatchEvent(selector, 'custom-event')
+```
+
+#### Queries (auto-wait for element)
+
+```ts
+const text = await tauriPage.textContent(selector)
+const html = await tauriPage.innerHTML(selector)
+const visible = await tauriPage.innerText(selector)
+const value = await tauriPage.inputValue(selector)
+const attr = await tauriPage.getAttribute(selector, name)
+const box = await tauriPage.boundingBox(selector)
+const css = await tauriPage.getComputedStyle(selector, 'color')
+const all = await tauriPage.allTextContents(selector)
+```
+
+#### State Checks (instant, no waiting)
+
+```ts
+await tauriPage.isVisible(selector)     // false if not found
+await tauriPage.isHidden(selector)
+await tauriPage.isChecked(selector)
+await tauriPage.isDisabled(selector)
+await tauriPage.isEnabled(selector)
+await tauriPage.isEditable(selector)
+await tauriPage.isFocused(selector)
+await tauriPage.count(selector)         // 0 if none found
+```
+
+#### Navigation
+
+```ts
+await tauriPage.goto(url)
+await tauriPage.reload()
+await tauriPage.goBack()
+await tauriPage.goForward()
+await tauriPage.waitForURL('/dashboard')
+const title = await tauriPage.title()
+const url = await tauriPage.url()
+const html = await tauriPage.content()
+```
+
+#### Waiting
+
+```ts
+await tauriPage.waitForSelector(selector, timeout?)
+await tauriPage.waitForFunction('document.readyState === "complete"', timeout?)
+await tauriPage.waitForURL('/dashboard', { timeout: 10000 })
+```
+
+#### Evaluate
+
+```ts
+const result = await tauriPage.evaluate<number>('window.innerWidth')
+```
+
+### Semantic Selectors
+
+```ts
+tauriPage.getByTestId('submit')
+tauriPage.getByText('Hello World')
+tauriPage.getByRole('button', { name: 'Submit' })
+tauriPage.getByLabel('Email')
+tauriPage.getByPlaceholder('Enter name')
+tauriPage.getByAltText('Logo')
+tauriPage.getByTitle('Close')
+```
+
+### Locator API
+
+```ts
+const locator = tauriPage.locator('[data-testid="list"]')
+
+// Actions
+await locator.click()
+await locator.fill('text')
+await locator.press('Enter')
+await locator.clear()
+await locator.pressSequentially('hello', { delay: 50 })
+await locator.dispatchEvent('input')
+
+// Queries
+await locator.textContent()
+await locator.innerText()
+await locator.inputValue()
+await locator.getAttribute('href')
+await locator.evaluate('(el) => el.dataset.custom')
+
+// State
+await locator.isVisible()
+await locator.isChecked()
+await locator.isFocused()
+
+// Refinement
+locator.nth(2)
+locator.first()
+locator.last()
+locator.filter({ hasText: 'Active' })
+await locator.all()            // returns array of locators
+
+// Nesting
+locator.locator('.child')
+locator.getByTestId('item')
+locator.getByText('Click me')
+
+// Scrolling
+await locator.scrollIntoViewIfNeeded()
+```
+
+### Assertions
+
+Custom `expect` matchers with auto-retry (default 5s timeout):
+
+```ts
+// Visibility
+await expect(locator).toBeVisible()
+await expect(locator).toBeHidden()
+await expect(locator).not.toBeVisible()
+
+// Content
+await expect(locator).toContainText('Hello')
+await expect(locator).toContainText(/hello/i)    // regex
+await expect(locator).toHaveText('Hello World')  // exact match
+
+// Form state
+await expect(locator).toHaveValue('test')
+await expect(locator).toBeChecked()
+await expect(locator).toBeEnabled()
+await expect(locator).toBeDisabled()
+await expect(locator).toBeEditable()
+await expect(locator).toBeFocused()
+await expect(locator).toBeEmpty()
+
+// Attributes
+await expect(locator).toHaveAttribute('type', 'text')
+await expect(locator).toHaveClass('active')
+await expect(locator).toHaveCSS('color', 'rgb(255, 0, 0)')
+await expect(locator).toHaveId('main')
+
+// Collections
+await expect(locator).toHaveCount(5)
+await expect(locator).toBeAttached()
+
+// Page-level
+await expect(tauriPage).toHaveURL('/dashboard')
+await expect(tauriPage).toHaveTitle('My App')
+```
+
+### Keyboard & Mouse
+
+```ts
+// Keyboard
+await tauriPage.keyboard.press('Enter')
+await tauriPage.keyboard.press('Control+A')
+await tauriPage.keyboard.type('hello world', { delay: 50 })
+await tauriPage.keyboard.down('Shift')
+await tauriPage.keyboard.up('Shift')
+
+// Mouse
+await tauriPage.mouse.click(100, 200)
+await tauriPage.mouse.click(100, 200, { button: 'right' })
+await tauriPage.mouse.dblclick(100, 200)
+await tauriPage.mouse.move(300, 400)
+await tauriPage.mouse.wheel(0, 100)
+```
+
+### Network Mocking
+
+```ts
+// Mock an API endpoint
+await tauriPage.route('/api/users', {
+  status: 200,
+  body: JSON.stringify({ users: ['Alice', 'Bob'] }),
+  contentType: 'application/json',
+});
+
+// Click a button that fetches from the mocked endpoint
+await tauriPage.click('[data-testid="fetch-btn"]');
+await expect(tauriPage.getByTestId('user-0')).toContainText('Alice');
+
+// Verify network requests were captured
+const requests = await tauriPage.getNetworkRequests();
+expect(requests.find(r => r.url.includes('/api/users'))).toBeTruthy();
+
+// Clean up
+await tauriPage.unroute('/api/users');
+await tauriPage.clearRoutes();
+```
+
+### Dialog Handling
+
+```ts
+await tauriPage.installDialogHandler({
+  defaultConfirm: true,
+  defaultPromptText: 'Claude',
+});
+
+await tauriPage.click('[data-testid="btn-confirm"]');
+
+const dialogs = await tauriPage.getDialogs();
+expect(dialogs[0].type).toBe('confirm');
+expect(dialogs[0].message).toBe('Are you sure?');
+```
+
+### File Upload
+
+```ts
+await tauriPage.setInputFiles('[data-testid="file-input"]', [
+  { name: 'test.txt', mimeType: 'text/plain', buffer: Buffer.from('hello') },
+]);
+```
+
+### Screenshots & Video
+
+```ts
+// Native screenshot (CoreGraphics on macOS — captures real window with title bar)
+const png = await tauriPage.screenshot();
+await tauriPage.screenshot({ path: '/tmp/screenshot.png' });
+
+// Video recording (native frame capture → ffmpeg → MP4)
+await tauriPage.startRecording({ path: '/tmp/recording', fps: 15 });
+// ... run test actions ...
+const result = await tauriPage.stopRecording();
+console.log(result.video); // '/tmp/recording/video.mp4'
+```
+
+The fixture automatically records video and captures screenshots on failure, attaching them to the Playwright HTML report.
+
+### IPC Mocking (Browser Mode)
+
+Mock any Tauri `invoke()` command, including plugin commands:
+
+```ts
+createTauriTest({
+  devUrl: 'http://localhost:1420',
+  ipcMocks: {
+    greet: (args) => `Hello, ${args?.name}!`,
+    get_config: () => ({ theme: 'dark', lang: 'en' }),
+    'plugin:fs|read': () => 'file contents',
+    'plugin:dialog|open': () => '/path/to/file',
+  },
+});
+```
+
+Assert which IPC commands were called:
+
+```ts
+import { getCapturedInvokes, clearCapturedInvokes } from '@srsholmes/tauri-playwright';
+
+const calls = await getCapturedInvokes(tauriPage);
+expect(calls).toContainEqual(
+  expect.objectContaining({ cmd: 'greet', args: { name: 'World' } })
+);
+```
+
+## Plugin Configuration
+
+```rust
+use tauri_plugin_playwright::PluginConfig;
+
+// Default: Unix socket at /tmp/tauri-playwright.sock
+builder = builder.plugin(tauri_plugin_playwright::init());
+
+// Custom socket path + TCP fallback
+builder = builder.plugin(tauri_plugin_playwright::init_with_config(
+    PluginConfig::new()
+        .socket_path("/tmp/my-app-pw.sock")
+        .tcp_port(6274)
+));
+```
+
+## CDP Mode (Windows)
+
+On Windows, WebView2 supports Chrome DevTools Protocol for full native Playwright:
+
+```bash
+# Launch with CDP enabled
+WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS="--remote-debugging-port=9222" cargo tauri dev
+```
+
+```ts
+// Playwright config
+{
+  name: 'cdp',
+  use: { mode: 'cdp' },
+}
+
+// Fixture config
+createTauriTest({
+  cdpEndpoint: 'http://localhost:9222',
+  // ...
+});
+```
+
+## Example App
+
+See [`examples/hello-world/`](examples/hello-world/) for a complete working example with:
+
+- React frontend with counter, greet (Tauri IPC), todo list, modal, file upload, dialogs, drag & drop, API fetch
+- Rust backend with greet command + playwright plugin
+- **67 E2E tests** across 10 spec files covering every API method
+- **127 unit tests** for the TypeScript library
+- Playwright config with browser-only and Tauri projects
+
+## Requirements
+
+- **Tauri 2.0** with `"withGlobalTauri": true` in `tauri.conf.json`
+- **Node.js 18+**
+- **Rust toolchain** (for Tauri mode)
+- **ffmpeg** (optional, for video stitching)
+- **Screen recording permission** on macOS (for native screenshots)
+
+## CI/CD
+
+GitHub Actions workflow included (`.github/workflows/e2e.yml`):
+
+```yaml
+# Browser-only tests run on ubuntu (fast, headless)
+npx playwright test --project=browser-only
+
+# Tauri tests run on macOS (real app, native screenshots)
+npx playwright test --project=tauri
+```
+
+Test results, HTML reports, and videos are uploaded as artifacts.
+
+## License
+
+MIT