craftdriver 1.4.0 → 1.6.0

package/docs/safari.md

@@ -0,0 +1,118 @@
+# Safari
+
+CraftDriver drives **real desktop Safari on macOS** through W3C WebDriver
+Classic.
+
+## One-time setup
+
+Safari's driver (`safaridriver`) ships with macOS — **nothing to install or
+download**. You only have to turn on automation **once per machine**:
+
+```bash
+safaridriver --enable
+```
+
+This is the single prerequisite.
+
+CraftDriver never runs `--enable` for you. If automation isn't enabled, a
+launch fails immediately with that exact remedy rather than hanging.
+
+## Quick start
+
+```typescript
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({ browserName: 'safari' });
+await browser.navigateTo('http://127.0.0.1:8080/login.html');
+await browser.getByLabel('Username').fill('alice');
+await browser.getByLabel('Password').fill('secret');
+await browser.getByRole('button', { name: 'Sign in' }).click();
+await browser.expect('#welcome').toHaveText('Welcome back, alice!');
+await browser.quit();
+```
+
+Same API as every other browser — locators, actions, assertions, and
+auto-waiting all work unchanged.
+
+## What works
+
+Navigation, locators, and element queries · click / fill / clear / keyboard /
+desktop mouse · `evaluate()` (sync & async JS) · frames and iframes · window &
+popup enumeration · **imperative dialogs** (`getAlertText` / `acceptAlert` /
+`dismissAlert` / `sendAlertText`) · viewport and element screenshots · cookies
+and storage (via the standard Classic cookie endpoints) · accessibility checks.
+
+## What isn't supported
+
+Safari exposes no WebDriver BiDi endpoint, so everything event- or
+BiDi-driven is unavailable — and each of these throws a clear
+[`UNSUPPORTED`](./error-codes.md) error immediately, never a silent hang:
+
+- network mocking / interception and request/response waits
+- console & JavaScript-error capture, tracing
+- BiDi user contexts and emulation (permissions, geolocation,
+  locale/timezone, offline, color-scheme)
+- init/preload scripts and the virtual clock
+- event-driven dialogs (`onDialog` / `waitForDialog`) — use the imperative
+  methods above
+- full-page screenshots and `openPage()`
+- CraftDriver-managed downloads (`waitForDownload`)
+
+Desktop Safari is also **not** iPhone/iPad Safari — there is no mobile or
+touch emulation.
+
+## Limitations to plan around
+
+- **macOS-only.** There is no Safari for Linux or Windows, and none is coming.
+  Trying to launch Safari off macOS throws `UNSUPPORTED`.
+- **Headed only.** No headless mode — every launch opens a visible automation
+  window (with a purple banner). Don't interact with it while a test runs.
+  Setting `HEADLESS=true` with Safari is rejected up front.
+- **Serial only.** Only one Safari WebDriver session can be active on a Mac at
+  a time. A second concurrent launch is refused with an actionable error
+  (never a hang) — run Safari tests serially.
+
+## Safari Technology Preview
+
+STP ships its own `safaridriver`; point `SafariService` at it. This is also
+the one way to get a **second concurrent session** on one Mac — stable Safari
+and STP each run one session at the same time.
+
+```typescript
+import { Browser, SafariService } from 'craftdriver';
+
+const browser = await Browser.launch({
+  browserName: 'safari',
+  safariService: new SafariService({
+    binaryPath: '/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver',
+  }),
+});
+```
+
+Enable automation once for STP too: `/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver --enable`.
+
+## Running Safari tests
+
+Run Safari **serially** — one session at a time. With Vitest that's
+`--maxWorkers=1`:
+
+```bash
+vitest run --maxWorkers=1
+```
+
+Keep it headed (don't set `HEADLESS`), on macOS with Remote Automation enabled.
+In CI, use a macOS runner; parallelism across Safari needs **separate macOS
+hosts**.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `You must enable 'Allow remote automation'…` | Run `safaridriver --enable` once (see [setup](#one-time-setup)). |
+| Second launch fails while one session is open | Expected — Safari is serial. Serialize your tests, or use STP for a second session. |
+| `Could not find 'safaridriver'` | You're not on macOS, or Safari is missing. For a non-standard install, set `CRAFTDRIVER_SAFARIDRIVER_PATH` or `SafariService({ binaryPath })`. |
+
+## See also
+
+- [Driver Configuration → Safari](./driver-configuration.md#safari-macos-driver-ships-with-the-browser) — the no-download driver-resolution chain.
+- [WebDriver Standards](./standards.md#safari-is-classic-only) — why Safari is Classic-only.

package/docs/standards.md

@@ -16,6 +16,24 @@ That protocol choice is the center of the project. CraftDriver tries to provide
 
 CraftDriver picks the practical protocol path behind a single public API. You call `browser.click()`, `browser.navigateTo()`, `browser.network.mock()`, or `browser.startTrace()`; the library handles the transport details.
 
+### Remote sessions use the same two protocols
+
+`Browser.launch({ remote })` connects to a W3C-compatible remote endpoint
+(a self-hosted Selenium Grid, BrowserStack, or another cloud provider). The
+same protocols are used, but the endpoint decides which browser features and
+BiDi proxying are available. Remote uploads and downloads also have a
+different lifecycle. See [Remote WebDriver](./remote-webdriver.md).
+
+### Safari is Classic-only
+
+Apple does not currently document a supported WebDriver BiDi endpoint for
+Safari or Safari Technology Preview. A local Safari launch therefore rejects
+`enableBiDi: true` and BiDi-only methods fail with `UNSUPPORTED`. Remote
+Safari defaults to Classic too; an explicit remote opt-in is forwarded because
+the remote endpoint owns negotiation, and it is usable only if that endpoint
+returns a working `webSocketUrl`. See the [Safari guide](./safari.md) for the
+local Classic feature set.
+
 ## Why It Matters
 
 Standards-based automation gives projects a few useful properties:

package/docs/why-craftdriver.md

@@ -5,7 +5,7 @@ CraftDriver is for writing boringly reliable automation against real browsers, w
 ## What It Cares About
 
 - 🍺 **Focused Node.js API** - browser automation without a giant framework around it.
-- 🧭 **Real browsers** - drives installed Chrome, Chromium, and Firefox instead of patched browser engine builds.
+- 🧭 **Real browsers** - drives installed Chrome, Chromium, and Firefox instead of patched browser engine builds, plus real [Safari on macOS](./safari.md).
 - 🌐 **Standards that age well** - W3C WebDriver standards stay stable while browser-private protocols change.
 - 🚦 **Readable, auto-waited flows** - role, label, text, test id, CSS, XPath, click, fill, and expect.
 - 📡 **Network control** - mock, block, intercept, and wait for browser requests and responses.
@@ -13,6 +13,8 @@ CraftDriver is for writing boringly reliable automation against real browsers, w
 - ⏱️ **Virtual clock** - freeze or fast-forward `Date`, timers, and time-sensitive UI.
 - ♿ **Accessibility audits** - run axe-core checks on pages, elements, and locators.
 - 🧾 **Trace evidence** - capture actions, console output, errors, network events, and screenshots.
+- ⚛️ **Electron apps** - drive packaged Electron desktop app renderers, matched to the app's bundled Chromium.
+- ☁️ **Remote WebDriver** - use the Browser API with a self-hosted Selenium Grid or a cloud provider like [BrowserStack](https://www.browserstack.com/).
 - 🤖 **Agent-friendly** - CLI, MCP, and assistant rules when coding agents need the browser.
 
 ## Good Fits

package/docs/zero-config-drivers.md

@@ -62,3 +62,15 @@ Manual configuration is useful when:
   [Driver Configuration → Browser Binary Configuration](./driver-configuration.md#browser-binary-configuration)
 
 See [Driver Configuration](./driver-configuration.md) for the full reference.
+
+## Safari: nothing to resolve, nothing to download
+
+The auto-download model above doesn't apply to `browserName: 'safari'`.
+`safaridriver` ships as part of macOS/Safari itself — there's no version to
+match, no binary to fetch, and no cache to warm. CraftDriver only ever
+**locates** the driver Apple already installed. The single prerequisite is
+turning automation on once per Mac with `safaridriver --enable`.
+
+See the [**Safari guide**](./safari.md) for setup and capabilities, and
+[Driver Configuration → Safari](./driver-configuration.md#safari-macos-driver-ships-with-the-browser)
+for the driver-resolution chain.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craftdriver",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Modern WebDriver automation library for NodeJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,8 +17,11 @@
     "test:firefox": "BROWSER_NAME=firefox HEADLESS=true vitest run --maxWorkers=2",
     "test:chrome": "BROWSER_NAME=chrome vitest run",
     "test:chromium": "BROWSER_NAME=chromium vitest run",
+    "test:safari": "BROWSER_NAME=safari vitest run tests/safari.test.ts --maxWorkers=1",
     "test:recipes": "HEADLESS=true vitest run --config vitest.recipes.config.ts",
     "test:electron": "vitest run --config vitest.electron.config.ts",
+    "test:browserstack": "vitest run --config vitest.browserstack.config.ts",
+    "test:grid": "vitest run --config vitest.grid.config.ts",
     "bench": "HEADLESS=true vitest run --config vitest.perf.config.ts",
     "clean": "rimraf dist",
     "serve": "http-server ./examples -a 127.0.0.1 -p 8080 -c-1 --cors",
@@ -40,6 +43,7 @@
     "firefox",
     "chrome",
     "chromium",
+    "safari",
     "electron",
     "electron-testing",
     "desktop-app-testing",

package/skills/craftdriver/SKILL.md

@@ -36,7 +36,10 @@ break the moment markup shifts.
 4. BiDi features (`network`, `logs`, tracing, init scripts, true load
    events) work out of the box — `enableBiDi` defaults to `true`. They only
    break if you explicitly pass `enableBiDi: false`; the error code on the
-   wrong transport is `UNSUPPORTED`.
+   wrong transport is `UNSUPPORTED`. Exception: `browserName: 'safari'`
+   defaults `enableBiDi` to `false` and rejects `true` — Safari is
+   Classic-only (macOS, headed, one session at a time). See
+   [docs/safari.md](../../docs/safari.md).
 5. Tests fetch from the example server. Start it in a separate
    terminal: `npm run examples:start` before `npm test`.
 

package/skills/craftdriver/cheatsheet.md

@@ -10,11 +10,14 @@ list.
 import { Browser } from 'craftdriver';
 
 const browser = await Browser.launch({
-  browserName: 'chrome',   // 'chrome' | 'chromium' | 'firefox'
+  browserName: 'chrome',   // 'chrome' | 'chromium' | 'firefox' | 'safari'
   headless: true,
   // enableBiDi defaults to true — network / logs / tracing / init scripts
   // all need it, so only set enableBiDi: false if you must disable it.
 });
+// 'safari' is macOS-only, headed only (no `headless`),
+// one session at a time, WebDriver Classic only (enableBiDi is rejected).
+// See docs/safari.md.
 try {
   await browser.navigateTo('https://example.com');
   // ...