craftdriver 1.4.0 → 1.5.0

package/dist/lib/browser.js

@@ -5,6 +5,7 @@ import { diagnoseElectronLaunchFailure } from './electronDiagnostics.js';
 import { ElectronRemote } from './electronRemote.js';
 import { findFreePort } from './service.js';
 import { FirefoxService } from './firefox.js';
+import { SafariService } from './safari.js';
 import { resolveBrowserBinaryPath } from './driverManager.js';
 import { buildLaunchCapabilities } from './capabilities.js';
 import { resolveLaunchTarget } from './launchTarget.js';
@@ -351,9 +352,18 @@ export class Browser {
         // it's the optional custom-binary resolution chain — but see
         // resolveBrowserBinaryPath's doc: some of the env vars in that chain aren't
         // craftdriver-opt-in, they're ambient conventions other tools may have set.
+        // Safari has no custom-binary concept: browserPath/args are rejected
+        // upstream in resolveLaunchTarget(), so target.browserPath is
+        // always undefined here. Skip resolveBrowserBinaryPath() for Safari
+        // entirely rather than calling it with 'firefox' as a stand-in — it would
+        // still probe FIREFOX_BIN/SE_FIREFOX_PATH-style env vars that have
+        // nothing to do with Safari, which is misleading even though it happens
+        // to return undefined/harmless today.
         const browserBinary = target.kind === 'electron'
             ? electronBinary
-            : resolveBrowserBinaryPath(isChromeFamily ? 'chrome' : 'firefox', target.browserPath);
+            : name === 'safari'
+                ? undefined
+                : resolveBrowserBinaryPath(isChromeFamily ? 'chrome' : 'firefox', target.browserPath);
         // Main-process access (opt-in): launch the Electron app with a Node inspector
         // on a free local port. chromedriver forwards this arg to the app, enabling
         // its main-process inspector; browser.electron connects below for log capture
@@ -399,6 +409,13 @@ export class Browser {
             driverService = options.chromeService ?? new ChromeService({ browserPath: browserBinary });
             builder.setChromeService(driverService);
         }
+        else if (name === 'safari') {
+            // No browserPath threading (Safari has none — see the browserBinary
+            // resolution above) and no headless/args to pass through; SafariService
+            // resolves its own driver binary (never auto-downloaded).
+            driverService = options.safariService ?? new SafariService();
+            builder.setSafariService(driverService);
+        }
         else {
             driverService = options.firefoxService ?? new FirefoxService();
             builder.setFirefoxService(driverService);
@@ -498,6 +515,26 @@ export class Browser {
     isBiDiEnabled() {
         return this.bidiSession?.isConnected() ?? false;
     }
+    /**
+     * Guard for the BiDi-only surface below. On Safari (which never
+     * negotiates BiDi) this throws `CraftdriverError`/`UNSUPPORTED` with a
+     * stable `{ browserName, feature }` detail so callers can branch on `code`
+     * instead of parsing prose. On every other browser the behavior is
+     * unchanged: the exact plain-`Error` message passed by the call site.
+     *
+     * Deliberately scoped to Safari's guards only — the pre-existing
+     * plain-`Error` guards elsewhere are a separate follow-up, not silently
+     * folded into this helper.
+     */
+    requireBiDi(feature, chromeMessage) {
+        if (this.bidiSession?.isConnected())
+            return;
+        if (this._browserName === 'safari') {
+            throw new CraftdriverError(ErrorCode.UNSUPPORTED, `${feature} is not supported on Safari (no WebDriver BiDi). ` +
+                'Apple does not document a WebDriver BiDi endpoint for Safari.', { detail: { browserName: 'safari', feature } });
+        }
+        throw new Error(chromeMessage);
+    }
     // === BiDi Feature Accessors ===
     /**
      * Network interception API (BiDi)
@@ -505,10 +542,8 @@ export class Browser {
      */
     get network() {
         if (!this._network) {
-            if (!this.bidiSession?.isConnected()) {
-                throw new Error('Network interception requires BiDi. ' +
-                    'BiDi negotiation may have failed at launch — check browser logs for WebSocket errors.');
-            }
+            this.requireBiDi('network', 'Network interception requires BiDi. ' +
+                'BiDi negotiation may have failed at launch — check browser logs for WebSocket errors.');
             this._network = this.bidiSession.network;
         }
         return this._network;
@@ -518,10 +553,8 @@ export class Browser {
      */
     get logs() {
         if (!this._logs) {
-            if (!this.bidiSession?.isConnected()) {
-                throw new Error('Log monitoring requires BiDi. ' +
-                    'BiDi negotiation may have failed at launch — check browser logs for WebSocket errors.');
-            }
+            this.requireBiDi('logs', 'Log monitoring requires BiDi. ' +
+                'BiDi negotiation may have failed at launch — check browser logs for WebSocket errors.');
             this._logs = this.bidiSession.logs;
         }
         return this._logs;
@@ -738,11 +771,9 @@ export class Browser {
      * await browser.grantPermissions(['clipboard-read'], { origin: 'https://example.com' });
      */
     async grantPermissions(permissions, opts) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('grantPermissions() requires BiDi (enableBiDi: true). ' +
-                'Permission overrides use the W3C BiDi `permissions.setPermission` command, ' +
-                'which has no Classic-WebDriver equivalent.');
-        }
+        this.requireBiDi('grantPermissions()', 'grantPermissions() requires BiDi (enableBiDi: true). ' +
+            'Permission overrides use the W3C BiDi `permissions.setPermission` command, ' +
+            'which has no Classic-WebDriver equivalent.');
         if (!Array.isArray(permissions) || permissions.length === 0) {
             throw new Error('grantPermissions: pass a non-empty array of permission names.');
         }
@@ -781,11 +812,9 @@ export class Browser {
      * await browser.setGeolocation(null); // clear
      */
     async setGeolocation(coords) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('setGeolocation() requires BiDi (enableBiDi: true). ' +
-                'Geolocation overrides use the W3C BiDi `emulation.setGeolocationOverride` ' +
-                'command, which has no Classic-WebDriver equivalent.');
-        }
+        this.requireBiDi('setGeolocation()', 'setGeolocation() requires BiDi (enableBiDi: true). ' +
+            'Geolocation overrides use the W3C BiDi `emulation.setGeolocationOverride` ' +
+            'command, which has no Classic-WebDriver equivalent.');
         const conn = this.bidiSession.getConnection();
         // Apply across all top-level contexts in the default user context.
         const tree = await conn.send('browsingContext.getTree', { maxDepth: 0 });
@@ -851,12 +880,10 @@ export class Browser {
     async emulate(options) {
         if (!options || Object.keys(options).length === 0)
             return;
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('emulate() requires BiDi (enableBiDi: true). ' +
-                'Emulation overrides use the W3C BiDi `emulation.*` commands ' +
-                '(and the BiDi+CDP bridge for media features and offline), ' +
-                'which have no Classic-WebDriver equivalent.');
-        }
+        this.requireBiDi('emulate()', 'emulate() requires BiDi (enableBiDi: true). ' +
+            'Emulation overrides use the W3C BiDi `emulation.*` commands ' +
+            '(and the BiDi+CDP bridge for media features and offline), ' +
+            'which have no Classic-WebDriver equivalent.');
         // Validate Chromium-only fields up front so we fail before mutating state.
         const chromiumOnly = ['colorScheme', 'reducedMotion', 'forcedColors', 'offline'];
         const isFirefox = this._browserName === 'firefox';
@@ -1096,7 +1123,7 @@ export class Browser {
     async startTrace(opts) {
         if (!this.bidiSession?.isConnected()) {
             throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'startTrace() requires BiDi (enableBiDi: true). ' +
-                'Tracing relies on BiDi events; Classic WebDriver does not expose them.', { detail: { feature: 'startTrace' } });
+                'Tracing relies on BiDi events; Classic WebDriver does not expose them.', { detail: { browserName: this._browserName, feature: 'startTrace' } });
         }
         if (!this._tracer) {
             this._tracer = new Tracer(this, this.bidiSession.getConnection(), this._browserName);
@@ -1193,10 +1220,8 @@ export class Browser {
      * ```
      */
     async addInitScript(fnOrSrc) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('addInitScript() requires BiDi. ' +
-                'BiDi is enabled by default — check that your browser supports it.');
-        }
+        this.requireBiDi('addInitScript()', 'addInitScript() requires BiDi. ' +
+            'BiDi is enabled by default — check that your browser supports it.');
         const conn = this.bidiSession.getConnection();
         const fnSrc = typeof fnOrSrc === 'function' ? fnOrSrc.toString() : `() => { ${fnOrSrc} }`;
         const result = await conn.send('script.addPreloadScript', {
@@ -1218,9 +1243,7 @@ export class Browser {
      * Register **before** the action that triggers the request.
      */
     waitForRequest(pattern, opts) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('waitForRequest() requires BiDi. BiDi is enabled by default — check your browser supports it.');
-        }
+        this.requireBiDi('waitForRequest()', 'waitForRequest() requires BiDi. BiDi is enabled by default — check your browser supports it.');
         return this.network.waitForRequest(pattern, {
             timeout: opts?.timeout ?? this.defaults.navigationTimeout,
         });
@@ -1239,18 +1262,14 @@ export class Browser {
      * ```
      */
     waitForResponse(pattern, opts) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('waitForResponse() requires BiDi. BiDi is enabled by default \u2014 check your browser supports it.');
-        }
+        this.requireBiDi('waitForResponse()', 'waitForResponse() requires BiDi. BiDi is enabled by default \u2014 check your browser supports it.');
         return this.network.waitForResponse(pattern, {
             timeout: opts?.timeout ?? this.defaults.navigationTimeout,
         });
     }
     on(event, listener) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error(`browser.on('${event}') requires BiDi (enableBiDi: true). ` +
-                'Network event listeners use the W3C BiDi `network` module, which has no Classic-WebDriver equivalent.');
-        }
+        this.requireBiDi(`browser.on('${event}')`, `browser.on('${event}') requires BiDi (enableBiDi: true). ` +
+            'Network event listeners use the W3C BiDi `network` module, which has no Classic-WebDriver equivalent.');
         if (event === 'request') {
             return this.network.on('request', listener);
         }
@@ -1266,6 +1285,17 @@ export class Browser {
      * await dl.saveAs('/tmp/report.csv');
      */
     async waitForDownload(action, opts) {
+        if (this._browserName === 'safari') {
+            // safaridriver exposes no download-directory configuration craftdriver
+            // can manage, so a browser download never lands in _downloadsDir — it
+            // goes to the user's ~/Downloads. Without this guard, waitForDownload()
+            // would watch an empty temp dir and fail with an opaque timeout instead
+            // of a clear "unsupported" error. Craftdriver-managed downloads are out
+            // of scope for Safari.
+            throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'waitForDownload() is not supported on Safari: safaridriver exposes no ' +
+                'download-directory configuration craftdriver can manage, so downloads ' +
+                'cannot be routed to or observed in a controlled directory.', { detail: { browserName: 'safari', feature: 'waitForDownload()' } });
+        }
         const dir = this._downloadsDir;
         if (!dir) {
             throw new Error('waitForDownload() requires a downloads directory. Browser was not launched correctly.');
@@ -1317,7 +1347,23 @@ export class Browser {
                 await handler(dialog);
             });
         }
-        // Classic: no push events — callers must use the imperative API below
+        if (this._browserName === 'safari') {
+            // Safari is Classic-only and has no WebDriver BiDi push events, so there
+            // is no event-driven way to detect a dialog opening. A polling fallback
+            // (repeatedly calling getAlertText()/driver "no such alert" errors to
+            // detect a dialog) was considered, but would need to be *proven*
+            // reliable on real Safari before shipping. Rather than silently no-op (today's
+            // Classic behavior for other browsers) or let waitForDialog() hang
+            // until its own generic timeout — which would look like a missed
+            // dialog rather than "this API isn't supported here" — fail
+            // immediately with a clear, actionable error. Revisit if a polling
+            // form is later measured reliable on real Safari.
+            throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'onDialog() / waitForDialog() are not supported on Safari: Safari has no ' +
+                'WebDriver BiDi, so there is no push-event mechanism for dialogs. ' +
+                'Use the imperative dialog API instead — acceptDialog(), dismissDialog(), ' +
+                'getDialogMessage() — which work in Classic mode.', { detail: { browserName: 'safari', feature: 'onDialog()' } });
+        }
+        // Classic (non-Safari): no push events — callers must use the imperative API below
         // Return a no-op unsubscribe
         return () => {
             /* no-op */
@@ -1378,18 +1424,31 @@ export class Browser {
     waitForDialog(opts) {
         const timeout = opts?.timeout ?? this.defaults.timeout;
         return new Promise((resolve, reject) => {
-            const tid = timeout > 0
-                ? setTimeout(() => {
+            let tid;
+            let off;
+            // onDialog() throws synchronously on Safari (no BiDi push events for
+            // dialogs — see onDialog()'s comment). Register the handler before
+            // scheduling the timeout so that throw rejects this promise
+            // immediately instead of leaving a dangling timer whose callback would
+            // later reference `off` before it was ever assigned.
+            try {
+                off = this.onDialog((dialog) => {
+                    if (tid !== undefined)
+                        clearTimeout(tid);
+                    off();
+                    resolve(dialog);
+                });
+            }
+            catch (err) {
+                reject(err);
+                return;
+            }
+            if (timeout > 0) {
+                tid = setTimeout(() => {
                     off();
                     reject(new Error(`waitForDialog timed out after ${timeout}ms`));
-                }, timeout)
-                : undefined;
-            const off = this.onDialog((dialog) => {
-                if (tid !== undefined)
-                    clearTimeout(tid);
-                off();
-                resolve(dialog);
-            });
+                }, timeout);
+            }
         });
     }
     _buildDialog(params) {
@@ -1512,10 +1571,8 @@ export class Browser {
      * await page.waitForLoadState();
      */
     async openPage(opts) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('openPage() requires BiDi (enableBiDi: true). ' +
-                'WebDriver Classic cannot create top-level browsing contexts.');
-        }
+        this.requireBiDi('openPage()', 'openPage() requires BiDi (enableBiDi: true). ' +
+            'WebDriver Classic cannot create top-level browsing contexts.');
         const conn = this.bidiSession.getConnection();
         const created = await conn.send('browsingContext.create', {
             type: opts?.type ?? 'tab',
@@ -1679,10 +1736,8 @@ export class Browser {
         return ctx;
     }
     async newContext(opts) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('newContext() requires BiDi (enableBiDi: true). ' +
-                'WebDriver Classic has no concept of user contexts.');
-        }
+        this.requireBiDi('newContext()', 'newContext() requires BiDi (enableBiDi: true). ' +
+            'WebDriver Classic has no concept of user contexts.');
         const conn = this.bidiSession.getConnection();
         const created = await conn.send('browser.createUserContext', {});
         const ctx = this._wrapContext(created.userContext, {
@@ -1692,7 +1747,7 @@ export class Browser {
         if (opts?.storageState !== undefined) {
             await ctx.loadStorageState(opts.storageState);
         }
-        // Apply Milestone-C emulation options. Each setter is `userContexts`-scoped,
+        // Apply identity & device emulation options. Each setter is `userContexts`-scoped,
         // so future pages in this context inherit automatically.
         if (opts?.locale !== undefined)
             await ctx.setLocale(opts.locale);
@@ -1708,11 +1763,9 @@ export class Browser {
      * Maps to BiDi `browser.getUserContexts`. **BiDi-only.**
      */
     async contexts() {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('contexts() requires BiDi (enableBiDi: true). ' +
-                'WebDriver Classic has no concept of user contexts. ' +
-                'Use browser.pages() to list tabs instead.');
-        }
+        this.requireBiDi('contexts()', 'contexts() requires BiDi (enableBiDi: true). ' +
+            'WebDriver Classic has no concept of user contexts. ' +
+            'Use browser.pages() to list tabs instead.');
         const conn = this.bidiSession.getConnection();
         const result = await conn.send('browser.getUserContexts', {});
         return (result.userContexts ?? []).map((uc) => this._wrapContext(uc.userContext));
@@ -1723,10 +1776,8 @@ export class Browser {
      * to this context. **BiDi-only.**
      */
     get defaultContext() {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('defaultContext requires BiDi (enableBiDi: true). ' +
-                'WebDriver Classic has no concept of user contexts.');
-        }
+        this.requireBiDi('defaultContext', 'defaultContext requires BiDi (enableBiDi: true). ' +
+            'WebDriver Classic has no concept of user contexts.');
         if (this._defaultContext)
             return this._defaultContext;
         this._defaultContext = this._wrapContext('default');
@@ -1924,12 +1975,31 @@ export class Browser {
     }
     gesture = {
         swipe: async ({ from, to, durationMs = 300, }) => {
+            this.rejectTouchActionsOnSafari('gesture.swipe()');
             await this.driver.performTouchSwipe(from, to, durationMs);
         },
         pinch: async ({ center, scale = 0.5, distance = 100, durationMs = 250, }) => {
+            this.rejectTouchActionsOnSafari('gesture.pinch()');
             await this.driver.performTouchPinch(center, scale, distance, durationMs);
         },
     };
+    /**
+     * `gesture.swipe()`/`gesture.pinch()` send W3C actions with a `pointer`
+     * input source whose `parameters.pointerType` is `'touch'`. Desktop Safari
+     * has no touchscreen and Apple's Safari 12+ WebDriver command table gives
+     * no indication `safaridriver` synthesizes touch-type pointer input —
+     * unlike `pointerType: 'mouse'`, which is exercised by every other pointer
+     * helper and is squarely in scope. Rather than let the action silently
+     * no-op (or behave unpredictably) on real Safari, fail loudly before
+     * sending it.
+     */
+    rejectTouchActionsOnSafari(feature) {
+        if (this._browserName !== 'safari')
+            return;
+        throw new CraftdriverError(ErrorCode.UNSUPPORTED, `${feature} sends a touch-type pointer action, which desktop Safari does not support. ` +
+            'Safari has no touchscreen and no documented touch-pointer WebDriver behavior; ' +
+            'this is desktop browser automation, not iPhone/iPad Safari coverage.', { detail: { browserName: 'safari', feature } });
+    }
     /**
      * Capture a screenshot of the active page (viewport by default), the
      * full scrollable document (`fullPage: true`), or an element matching
@@ -1962,11 +2032,9 @@ export class Browser {
             buf = Buffer.from(b64, 'base64');
         }
         else if (opts?.fullPage) {
-            if (!this.bidiSession?.isConnected()) {
-                throw new Error('screenshot({ fullPage: true }) requires BiDi (enableBiDi: true). ' +
-                    'Full-page screenshots use the W3C BiDi `browsingContext.captureScreenshot` ' +
-                    'command with `origin: "document"`, which has no Classic-WebDriver equivalent.');
-            }
+            this.requireBiDi('screenshot({ fullPage: true })', 'screenshot({ fullPage: true }) requires BiDi (enableBiDi: true). ' +
+                'Full-page screenshots use the W3C BiDi `browsingContext.captureScreenshot` ' +
+                'command with `origin: "document"`, which has no Classic-WebDriver equivalent.');
             const conn = this.bidiSession.getConnection();
             const page = await this.activePage();
             const result = await conn.send('browsingContext.captureScreenshot', {