craftdriver 1.4.0 → 1.6.0

package/dist/lib/browser.js

@@ -5,9 +5,11 @@ 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';
+import { parseRemoteEndpoint, buildRemoteCapabilities, redactUrlForLog } from './remote.js';
 import { By } from './by.js';
 import { until } from './wait.js';
 import { DEFAULT_ELEMENT_TIMEOUT_MS, DEFAULT_NAVIGATION_TIMEOUT_MS, STATE_POLL_INTERVAL_MS, NETWORK_IDLE_SETTLE_MS, PORT_RELEASE_DELAY_MS, BIDI_CONNECT_MAX_ATTEMPTS, BIDI_CONNECT_BACKOFF_STEP_MS, EVAL_REALM_RETRY_ATTEMPTS, EVAL_REALM_RETRY_DELAY_MS, } from './timing.js';
@@ -280,7 +282,12 @@ export class Browser {
     /** The launched Electron app's executable path (for deep-link routing on Windows). */
     _electronAppBinaryPath;
     _electron;
+    /** Requested local name or provider-facing remote name. */
     _browserName = 'chrome';
+    /** Lowercase engine family for engine-specific branches (Edge → `chrome`); see `normalizeEngine`. */
+    _engine = 'chrome';
+    /** Set for sessions created via `remote` — no local driver process/filesystem ever backs these. */
+    _isRemote = false;
     /** Active emulation overrides, re-applied to new top-level contexts. */
     _emulation = {};
     /** Mutable browser-level defaults. Use setDefaultTimeout() / setDefaultNavigationTimeout() to change. */
@@ -315,6 +322,9 @@ export class Browser {
         // Normalize first: callers may be JavaScript or JSON-driven, so reject
         // malformed/mixed targets before touching disk or starting a driver.
         const target = resolveLaunchTarget(options);
+        if (target.kind === 'remote') {
+            return await Browser.launchRemote(target, options);
+        }
         const isElectron = target.kind === 'electron';
         const name = target.browserName;
         const isChromeFamily = name === 'chrome' || name === 'chromium';
@@ -351,9 +361,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 +418,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);
@@ -427,6 +453,9 @@ export class Browser {
         browser._downloadsDir = downloadsDir;
         browser._driverService = driverService;
         browser._browserName = name;
+        // Local names are already the normalized `SupportedBrowserName`, so engine
+        // and provider-facing name coincide here (they diverge only for remote).
+        browser._engine = name;
         browser._electronInspect = electronInspect;
         browser._electronAppBinaryPath = electronBinary;
         // With main-process access enabled, open the inspector bridge now so
@@ -445,14 +474,58 @@ export class Browser {
                 });
             });
         }
-        // Initialize BiDi session if WebSocket URL available
-        const wsUrl = driver.__wsUrl;
-        if (wsUrl && bidiRequested) {
-            await browser.initBiDi(wsUrl);
+        try {
+            // Initialize BiDi session if WebSocket URL available
+            const wsUrl = driver.__wsUrl;
+            if (wsUrl && bidiRequested) {
+                await browser.initBiDi(wsUrl);
+            }
+            // Load session state if provided
+            if (options.storageState) {
+                await browser.loadState(options.storageState);
+            }
+        }
+        catch (err) {
+            // The driver session (and, for Electron, the app) already exists — don't
+            // leak the process if post-launch initialization fails. Tear it down,
+            // then surface the original error.
+            await browser.quit().catch(() => { });
+            throw err;
+        }
+        return browser;
+    }
+    /** Create a remote session without local driver or filesystem setup. */
+    static async launchRemote(target, options) {
+        const { endpoint, sessionTimeoutMs } = parseRemoteEndpoint(target.remote);
+        const caps = buildRemoteCapabilities({
+            browserName: target.browserName,
+            bidiRequested: target.bidiRequested,
+            userCapabilities: target.remote.capabilities,
+        });
+        const builder = new Builder()
+            .forBrowser(target.browserName)
+            .usingServer(endpoint, { sessionTimeoutMs })
+            .withCapabilities(caps);
+        const driver = await builder.build();
+        const browser = new Browser(driver);
+        browser._isRemote = true;
+        browser._browserName = target.browserName;
+        browser._engine = target.engine;
+        try {
+            const wsUrl = driver.__wsUrl;
+            if (wsUrl && target.bidiRequested) {
+                await browser.initBiDi(wsUrl);
+            }
+            if (options.storageState) {
+                await browser.loadState(options.storageState);
+            }
         }
-        // Load session state if provided
-        if (options.storageState) {
-            await browser.loadState(options.storageState);
+        catch (err) {
+            // POST /session already succeeded — a failure initializing the session
+            // must not strand it as a paid, orphaned session on the provider. Send
+            // DELETE /session (via quit()) before surfacing the original error.
+            await browser.quit().catch(() => { });
+            throw err;
         }
         return browser;
     }
@@ -485,8 +558,14 @@ export class Browser {
                     await new Promise((r) => setTimeout(r, BIDI_CONNECT_BACKOFF_STEP_MS * attempt));
                 }
                 else {
-                    // All attempts failed; fall back to Classic-only mode.
-                    console.warn('BiDi connection failed after retries, using Classic WebDriver only:', err);
+                    // All attempts failed; fall back to Classic-only mode. Redact the
+                    // WebSocket URL and any occurrence of it inside the error message —
+                    // some remote providers proxy webSocketUrl through query-string
+                    // tokens or embedded credentials, which must never reach a log.
+                    const redactedWsUrl = redactUrlForLog(wsUrl);
+                    const rawMessage = err instanceof Error ? err.message : String(err);
+                    const redactedMessage = rawMessage.split(wsUrl).join(redactedWsUrl);
+                    console.warn(`BiDi connection to ${redactedWsUrl} failed after retries, using Classic WebDriver only: ${redactedMessage}`);
                     this.bidiSession = undefined;
                 }
             }
@@ -498,6 +577,16 @@ export class Browser {
     isBiDiEnabled() {
         return this.bidiSession?.isConnected() ?? false;
     }
+    /** Require a connected BiDi session, with a stable Safari error code. */
+    requireBiDi(feature, chromeMessage) {
+        if (this.bidiSession?.isConnected())
+            return;
+        if (this._engine === '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 +594,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 +605,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 +823,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 +864,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,15 +932,13 @@ 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';
+        const isFirefox = this._engine === 'firefox';
         if (isFirefox) {
             for (const k of chromiumOnly) {
                 if (k in options) {
@@ -1065,7 +1144,7 @@ export class Browser {
         // URL comes from the session's own webSocketUrl, not a fixed port. So scope the
         // 500ms sleep to Firefox+BiDi; every other quit (all Chrome, Firefox w/o BiDi)
         // skips straight to stopping the driver.
-        if (this._browserName === 'firefox' && bidiWasActive) {
+        if (this._engine === 'firefox' && bidiWasActive) {
             await new Promise((r) => setTimeout(r, PORT_RELEASE_DELAY_MS));
         }
         // Stop the underlying driver service (chromedriver / geckodriver)
@@ -1096,10 +1175,10 @@ 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);
+            this._tracer = new Tracer(this, this.bidiSession.getConnection(), this._engine);
         }
         await this._tracer.start(opts);
     }
@@ -1193,10 +1272,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 +1295,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 +1314,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 +1337,26 @@ export class Browser {
      * await dl.saveAs('/tmp/report.csv');
      */
     async waitForDownload(action, opts) {
+        if (this._engine === '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()' } });
+        }
+        if (this._isRemote) {
+            // Same shape as the Safari guard above: a remote session has no
+            // client-visible downloads directory (downloadsDir is rejected at
+            // remote launch time), so a download never lands anywhere craftdriver
+            // can watch. Fail immediately with a clear error instead of an opaque
+            // timeout on an empty/nonexistent directory.
+            throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'waitForDownload() is not supported on remote sessions: remote sessions have no ' +
+                "client-visible downloads directory; use your provider's download API if one exists.", { detail: { feature: 'waitForDownload()' } });
+        }
         const dir = this._downloadsDir;
         if (!dir) {
             throw new Error('waitForDownload() requires a downloads directory. Browser was not launched correctly.');
@@ -1317,7 +1408,23 @@ export class Browser {
                 await handler(dialog);
             });
         }
-        // Classic: no push events — callers must use the imperative API below
+        if (this._engine === '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 +1485,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 +1632,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 +1797,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 +1808,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 +1824,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 +1837,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 +2036,28 @@ export class Browser {
     }
     gesture = {
         swipe: async ({ from, to, durationMs = 300, }) => {
+            this.rejectTouchActionsOnLocalSafari('gesture.swipe()');
             await this.driver.performTouchSwipe(from, to, durationMs);
         },
         pinch: async ({ center, scale = 0.5, distance = 100, durationMs = 250, }) => {
+            this.rejectTouchActionsOnLocalSafari('gesture.pinch()');
             await this.driver.performTouchPinch(center, scale, distance, durationMs);
         },
     };
+    /**
+     * Local desktop Safari has no documented touch-pointer automation surface, so
+     * fail loudly rather than let the action silently no-op. Local only: a remote
+     * `safari` session may be a real iOS device with a touchscreen (BrowserStack
+     * et al.), where these gestures are legitimate — forward those.
+     */
+    rejectTouchActionsOnLocalSafari(feature) {
+        if (this._isRemote)
+            return;
+        if (this._engine !== 'safari')
+            return;
+        throw new CraftdriverError(ErrorCode.UNSUPPORTED, `${feature} sends a touch-pointer action, which local desktop Safari does not support. ` +
+            'Use a remote real-device session for 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 +2090,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', {