browser-commander 0.24.0 → 0.26.0

package/src/browser/webdriver.js

@@ -40,6 +40,13 @@ import {
 } from './profile-directory.js';
 import { buildRealBrowserArgs } from './real-browser.js';
 import { resolveRestrictions } from './restrictions.js';
+import { findBrowserSource } from './browser-sources.js';
+import {
+  isSafariChannel,
+  SafariUnsupportedError,
+  safariLaunchError,
+  validateSafariOptions,
+} from './safari-support.js';
 
 const require = createRequire(import.meta.url);
 const accessAsync = promisify(access);
@@ -76,6 +83,8 @@ export const CHROMEDRIVER_DEFAULT_SWITCHES = Object.freeze([
 const DRIVERS = Object.freeze({
   chrome: { name: 'chromedriver', builder: 'chrome' },
   firefox: { name: 'geckodriver', builder: 'firefox' },
+  safari: { name: 'safaridriver', builder: 'safari' },
+  'safari-technology-preview': { name: 'safaridriver', builder: 'safari' },
 });
 
 /**
@@ -102,7 +111,7 @@ export function loadSelenium(subpath) {
 function assertBrowser(browser) {
   if (!DRIVERS[browser]) {
     throw new Error(
-      `Unsupported WebDriver browser: ${browser}. Expected 'chrome' or 'firefox'`
+      `Unsupported WebDriver browser: ${browser}. Expected 'chrome', 'firefox' or 'safari'`
     );
   }
   return DRIVERS[browser];
@@ -182,6 +191,20 @@ export async function resolveWebDriverExecutable({
   managerPath,
 } = {}) {
   const { name } = assertBrowser(browser);
+  if (isSafariChannel(browser)) {
+    if (platform !== 'darwin') {
+      throw new SafariUnsupportedError('Safari launch outside macOS');
+    }
+    const file = driverPath ?? findBrowserSource(browser).executables.darwin[0];
+    if (!(await isExecutable(file, checkAccess))) {
+      throw new Error(`Safari WebDriver executable is not accessible: ${file}`);
+    }
+    return {
+      driverPath: file,
+      browserPath: null,
+      source: 'bundled-safaridriver',
+    };
+  }
   if (driverPath) {
     if (!(await isExecutable(driverPath, checkAccess))) {
       throw new Error(`WebDriver executable is not accessible: ${driverPath}`);
@@ -237,6 +260,9 @@ export async function resolveWebDriverExecutable({
  * @returns {string[]}
  */
 export function buildDriverServerArgs(browser, port) {
+  if (isSafariChannel(browser)) {
+    return ['--port', String(port)];
+  }
   if (assertBrowser(browser).name === 'geckodriver') {
     return ['--port', String(port), '--host', LOOPBACK_HOST];
   }
@@ -306,6 +332,16 @@ export function buildBrowserOptions({
 }) {
   let options;
   let browserArgs;
+  if (isSafariChannel(browser)) {
+    options = new selenium.webdriver.Capabilities();
+    options.set(
+      'browserName',
+      browser === 'safari-technology-preview'
+        ? 'Safari Technology Preview'
+        : 'safari'
+    );
+    return { options, args: [] };
+  }
   if (browser === 'chrome') {
     options = new selenium.chrome.Options();
     if (debuggerAddress) {
@@ -387,7 +423,9 @@ function buildSession({ selenium, serverUrl, browser, options }) {
   const builder = new selenium.webdriver.Builder()
     .usingServer(serverUrl)
     .forBrowser(DRIVERS[browser].builder);
-  if (browser === 'chrome') {
+  if (isSafariChannel(browser)) {
+    builder.withCapabilities(options);
+  } else if (browser === 'chrome') {
     builder.setChromeOptions(options);
   } else {
     builder.setFirefoxOptions(options);
@@ -462,6 +500,10 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
     debuggerAddress,
   } = options;
   assertBrowser(browser);
+  const safari = isSafariChannel(browser);
+  if (safari) {
+    validateSafariOptions(options);
+  }
   if (debuggerAddress && browser !== 'chrome') {
     throw new Error('debuggerAddress is only supported by Chrome WebDriver');
   }
@@ -476,23 +518,17 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
   const startProcess = dependencies.startProcess ?? defaultStartProcess;
 
   const resolved = await resolveWebDriverExecutable({
+    ...dependencies,
     browser,
     driverPath: requestedDriverPath,
     executablePath,
-    runCommand: dependencies.runCommand ?? defaultRunCommand,
-    ...(dependencies.checkAccess
-      ? { checkAccess: dependencies.checkAccess }
-      : {}),
-    ...(dependencies.environment
-      ? { environment: dependencies.environment }
-      : {}),
-    ...(dependencies.platform ? { platform: dependencies.platform } : {}),
   });
 
-  const temporaryProfile = !debuggerAddress && !requestedUserDataDir;
-  const userDataDir = debuggerAddress
-    ? undefined
-    : await resolveProfile(browser, requestedUserDataDir);
+  const temporaryProfile = !safari && !debuggerAddress && !requestedUserDataDir;
+  const userDataDir =
+    safari || debuggerAddress
+      ? undefined
+      : await resolveProfile(browser, requestedUserDataDir);
   const childEnv = driverEnvironment(restrictions, env);
 
   let driverProcess;
@@ -506,9 +542,11 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
       { env: childEnv, forwardOutput: verbose }
     );
     let output = '';
-    driverProcess.stderr?.on('data', (chunk) => {
-      output = `${output}${chunk}`.slice(-4000);
-    });
+    for (const stream of [driverProcess.stdout, driverProcess.stderr]) {
+      stream?.on('data', (chunk) => {
+        output = `${output}${chunk}`.slice(-4000);
+      });
+    }
     await waitForDriverReady(serverUrl, {
       fetchImplementation: dependencies.fetch ?? fetch,
       timeout: startupTimeout,
@@ -536,7 +574,14 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
       browser,
       options: built.options,
     });
-    const page = await createWebDriverPage(driver, dependencies.pageOptions);
+    // Fresh Safari sessions can report an empty URL until first navigation.
+    if (safari) {
+      await driver.get('about:blank');
+    }
+    const page = await createWebDriverPage(driver, {
+      ...dependencies.pageOptions,
+      ...(safari ? { browserName: 'safari' } : {}),
+    });
 
     const close = memoize(() =>
       teardown({ page, driver, driverProcess, temporaryProfile, userDataDir })
@@ -558,7 +603,7 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
     };
   } catch (error) {
     await teardown({ driver, driverProcess, temporaryProfile, userDataDir });
-    throw error;
+    throw safari ? safariLaunchError(error, browser) : error;
   }
 }
 

package/src/cli/args.js

@@ -92,6 +92,8 @@ export const COMMANDS = Object.freeze({
       profile: STRING,
       'user-data-dir': STRING,
       'target-browser': STRING,
+      'password-csv': STRING,
+      'include-payment-cards': FLAG,
       to: STRING,
       include: STRING,
       domain: STRINGS,

package/src/cli/commands.js

@@ -216,6 +216,8 @@ async function profileMigrate(parsed, io) {
       profile: options.profile,
       userDataDir: options.userDataDir,
       targetBrowser: options.targetBrowser,
+      passwordCsv: options.passwordCsv,
+      includePaymentCards: options.includePaymentCards,
       to: options.to,
       include: options.include
         ?.split(',')

package/src/cli/high-level-methods.js

@@ -220,6 +220,8 @@ function migrateProfile(state, params) {
     include: params.include,
     domains: params.domains,
     targetBrowser: params.targetBrowser,
+    passwordCsv: params.passwordCsv,
+    includePaymentCards: params.includePaymentCards,
   });
 }
 

package/src/cli/sessions.js

@@ -12,6 +12,9 @@ export const BROWSER_CHANNELS = Object.freeze({
   msedge: 'msedge',
   brave: 'brave',
   chromium: 'chromium',
+  safari: 'safari',
+  'safari-technology-preview': 'safari-technology-preview',
+  'safari-tp': 'safari-technology-preview',
 });
 
 const ENGINES = Object.freeze(['playwright', 'puppeteer', 'selenium']);
@@ -40,6 +43,7 @@ const LAUNCH_PASSTHROUGH = Object.freeze([
   'firstRun',
   'driverPath',
   'bidi',
+  'seedCookies',
 ]);
 
 /** Validate an engine name, defaulting to Playwright. */
@@ -118,6 +122,7 @@ export function buildLaunchOptions(params = {}) {
  * persistent context whose `browser()` is null. Puppeteer returns a Browser.
  */
 export function sessionFromLaunch(engine, launched) {
+  engine = launched.engine ?? engine;
   const playwright = engine === 'playwright';
   const handle = launched.browser;
   return {

package/src/core/webdriver-page.js

@@ -32,6 +32,7 @@ import {
   toWebDriverKey,
 } from './webdriver-conversions.js';
 import { createWebDriverEventBridge } from './webdriver-events.js';
+import { SafariUnsupportedError } from '../browser/safari-support.js';
 
 const require = createRequire(import.meta.url);
 
@@ -99,6 +100,7 @@ export class WebDriverPage extends EventEmitter {
     }
     this.driver = driver;
     this.engine = 'selenium';
+    this.browserName = options.browserName;
     this.isWebDriverPage = true;
     this._url = 'about:blank';
     this._closed = false;
@@ -358,6 +360,57 @@ export class WebDriverPage extends EventEmitter {
     return result;
   }
 
+  /** Execute an asynchronous function using W3C execute/async. */
+  async evaluateAsync(pageFunction, ...args) {
+    const script = buildEvaluateScript(pageFunction);
+    const result = await this.driver.executeAsyncScript(
+      `const done = arguments[arguments.length - 1]; const args = Array.from(arguments).slice(0, -1); Promise.resolve((function(){${script}}).apply(null, args)).then(value => done({value}), error => done({error: String(error)}));`,
+      ...args
+    );
+    if (result.error) {
+      throw new Error(result.error);
+    }
+    const [value, href] = result.value;
+    this._url = href;
+    return value;
+  }
+
+  /** Fail before subscribing or creating files for unsupported Safari features. */
+  requireFeature(feature) {
+    if (this.browserName?.toLowerCase().startsWith('safari')) {
+      throw new SafariUnsupportedError(feature);
+    }
+  }
+
+  setRequestInterception() {
+    return Promise.resolve().then(() => {
+      this.requireFeature('network interception');
+      throw new Error('Network interception requires a supporting engine');
+    });
+  }
+
+  route() {
+    return this.setRequestInterception();
+  }
+
+  /** W3C window handles include both tabs and windows. */
+  async windows() {
+    return await this.driver.getAllWindowHandles();
+  }
+
+  async newWindow(type = 'tab') {
+    await this.driver.switchTo().newWindow(type);
+    this._contextId = await this.driver.getWindowHandle();
+    await this.syncUrl();
+    return this._contextId;
+  }
+
+  async switchToWindow(handle) {
+    await this.driver.switchTo().window(handle);
+    this._contextId = handle;
+    await this.syncUrl();
+  }
+
   /**
    * Puppeteer's evaluateOnNewDocument, as a BiDi preload script.
    *
@@ -626,6 +679,7 @@ export class WebDriverPage extends EventEmitter {
    * @returns {Promise<Buffer>}
    */
   async pdf(options = {}) {
+    this.requireFeature('PDF');
     const buffer = Buffer.from(
       await this.driver.printPage(toPrintOptions(options)),
       'base64'
@@ -709,6 +763,14 @@ export class WebDriverPage extends EventEmitter {
  * @returns {Promise<WebDriverPage>}
  */
 export async function createWebDriverPage(driver, options = {}) {
+  if (!options.browserName) {
+    const capabilities = await driver.getCapabilities();
+    options = {
+      ...options,
+      browserName:
+        capabilities?.get?.('browserName') ?? capabilities?.browserName,
+    };
+  }
   const page = new WebDriverPage(driver, options);
   await page.contextId();
   await page.syncUrl();

package/src/exports.js

@@ -322,3 +322,9 @@ export {
   redactUrl,
   redactValue,
 } from './traces/redaction.js';
+
+export {
+  SafariSetupError,
+  SafariUnsupportedError,
+  openSafariSettings,
+} from './browser/safari-support.js';

package/src/traces/recorder.js

@@ -93,6 +93,7 @@ function validateLinksOptions(links) {
  * @returns {Promise<Object>} The running trace
  */
 export async function startTrace(options = {}) {
+  requireTraceSupport(options);
   const {
     commander,
     page = commander?.page,
@@ -468,3 +469,7 @@ export async function startTrace(options = {}) {
     },
   };
 }
+
+function requireTraceSupport(options) {
+  (options.page ?? options.commander?.page)?.requireFeature?.('tracing');
+}

package/tests/e2e/safari.e2e.test.js

@@ -0,0 +1,104 @@
+// feature-parity: safari.control@native-typed
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import {
+  launchRealBrowser,
+  SafariUnsupportedError,
+  makeBrowserCommander,
+} from '../../src/index.js';
+import { createDispatcher } from '../../src/cli/dispatcher.js';
+
+it(
+  'Safari drives a local page in an isolated automation session',
+  {
+    skip:
+      process.platform !== 'darwin' || process.env.RUN_SAFARI_E2E !== 'true',
+    timeout: 60_000,
+  },
+  async () => {
+    const server = createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'text/html' });
+      response.end(
+        '<title>Safari smoke</title><input id="name"><button id="go" onclick="document.querySelector(\'#out\').textContent=document.querySelector(\'#name\').value">Go</button><p id="out"></p>'
+      );
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const url = `http://127.0.0.1:${server.address().port}/`;
+    let session;
+    let commander;
+    const cli = createDispatcher();
+    const phase = (message) =>
+      console.info(`[Safari smoke] ${new Date().toISOString()} ${message}`);
+    try {
+      phase('launch seeded session');
+      session = await launchRealBrowser({
+        channel: 'safari',
+        startupTimeout: 20_000,
+        seedCookies: [{ name: 'seed', value: 'yes', url, httpOnly: true }],
+      });
+      const { page, driver } = session;
+      phase('exercise page commands');
+      commander = makeBrowserCommander({ page });
+      await page.goto(url);
+      assert.equal(commander.engine, 'selenium');
+      await commander.fill({ selector: '#name', text: 'Safari' });
+      await commander.click({ selector: '#go' });
+      assert.equal(
+        await page.evaluate(() => document.querySelector('#out').textContent),
+        'Safari'
+      );
+      assert.equal(await page.evaluateAsync(async (value) => value + 1, 4), 5);
+      assert.ok((await page.screenshot()).length > 100);
+      assert.equal((await driver.manage().getCookie('seed')).value, 'yes');
+      phase('exercise windows and tabs');
+      const initial = await driver.getWindowHandle();
+      for (const type of ['tab', 'window']) {
+        const handle = await page.newWindow(type);
+        assert.ok((await page.windows()).includes(handle));
+        await page.goto(url);
+        await driver.close();
+        await page.switchToWindow(initial);
+      }
+      await assert.rejects(() => page.pdf(), SafariUnsupportedError);
+      await assert.rejects(
+        () => page.setRequestInterception(true),
+        SafariUnsupportedError
+      );
+      phase('close seeded session');
+      await session.close();
+      phase('launch fresh session');
+      session = await launchRealBrowser({ channel: 'safari' });
+      await session.page.goto(url);
+      assert.equal(
+        (await session.driver.manage().getCookies()).some(
+          (cookie) => cookie.name === 'seed'
+        ),
+        false
+      );
+      phase('close fresh session');
+      await session.close();
+      phase('launch CLI session');
+      await cli.dispatch('session.launch', {
+        browser: 'safari',
+        engine: 'selenium',
+      });
+      phase('exercise CLI commands');
+      await cli.dispatch('page.goto', { url });
+      assert.equal(
+        (await cli.dispatch('page.eval', { expression: 'document.title' }))
+          .value,
+        'Safari smoke'
+      );
+    } finally {
+      phase('close CLI session');
+      await cli.close();
+      phase('destroy commander');
+      await commander?.destroy();
+      phase('close remaining session and server');
+      await session?.close();
+      await new Promise((resolve) => server.close(resolve));
+      phase('cleanup complete');
+    }
+  }
+);

package/tests/unit/browser/attach/snapshot.test.js

@@ -34,6 +34,36 @@ function snapshotChrome(root, to) {
   return snapshotUserDataDir({ browser: 'chrome', userDataDir: root, to });
 }
 
+it(
+  'reports a locked database with snapshot guidance and leaves no target database',
+  { timeout: 5000 },
+  async () => {
+    const root = await makeTempDir();
+    const target = await makeTempDir();
+    const profile = path.join(root, 'Default');
+    await mkdir(profile);
+    const filename = await writeChromiumHistory(profile, 1);
+    const writer = new BetterSqlite3(filename);
+    writer.exec('BEGIN EXCLUSIVE');
+    try {
+      const report = await snapshotChrome(root, target);
+      assert.equal(report.copied.databases, 0);
+      assert.ok(
+        report.skipped.some(
+          ({ item, reason, detail }) =>
+            item === 'Default/History' &&
+            reason === 'unreadable' &&
+            detail.includes('Consistent SQLite snapshot unavailable')
+        )
+      );
+      await assert.rejects(stat(path.join(target, 'Default/History')));
+    } finally {
+      writer.exec('ROLLBACK');
+      writer.close();
+    }
+  }
+);
+
 /** Write `content` to `root/relativePath`, creating the parent folders. */
 async function put(root, relativePath, content = relativePath) {
   const filePath = path.join(root, ...relativePath.split('/'));

package/tests/unit/browser/browser-cookies.test.js

@@ -12,6 +12,7 @@ import {
   mkdtemp,
   readFile,
   readdir,
+  rename,
   rm,
   stat,
   writeFile,
@@ -149,6 +150,40 @@ describe('installed browser cookie import', () => {
     }
   });
 
+  it('discovers and decrypts Yandex Cookies through its catalogue alias', async () => {
+    temporaryDirectory = await mkdtemp(
+      path.join(os.tmpdir(), 'bc-yandex-cookies-')
+    );
+    const host = '.yandex.ru';
+    const { root } = await createChromiumProfile({
+      homeDir: temporaryDirectory,
+      rows: [
+        {
+          host,
+          name: 'SID',
+          encryptedValue: encryptCbcCookie({
+            host,
+            value: 'yandex-session',
+            password: 'peanuts',
+            prefix: 'v10',
+          }),
+        },
+      ],
+    });
+    const yandexRoot = path.join(temporaryDirectory, '.config/yandex-browser');
+    await rename(root, yandexRoot);
+    const file = path.join(yandexRoot, 'Default/Network/Cookies');
+    const before = await readFile(file);
+    const cookies = await readBrowserCookiesWithDependencies(
+      { browser: 'yandex-browser', domainFilter: 'yandex.ru', cache: false },
+      { platform: 'linux', homeDir: temporaryDirectory, environment: {} }
+    );
+    assert.equal(cookies.length, 1);
+    assert.equal(cookies[0].domain, host);
+    assert.equal(cookies[0].value, 'yandex-session');
+    assert.deepEqual(await readFile(file), before);
+  });
+
   it('exports both public helpers', () => {
     assert.equal(publicListBrowserProfiles, listBrowserProfiles);
     assert.equal(publicReadBrowserCookies, readBrowserCookies);

package/tests/unit/browser/catalogue-launch.test.js

@@ -0,0 +1,93 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { mkdir, symlink } from 'node:fs/promises';
+import path from 'node:path';
+import { useTempDirectories } from '../../helpers/temp-directory.js';
+import {
+  BROWSER_SOURCES,
+  resolveBrowserRoots,
+} from '../../../src/browser/browser-sources.js';
+import {
+  assertDedicatedUserDataDir,
+  CHANNEL_EXECUTABLE_NAMES,
+} from '../../../src/browser/system-browser.js';
+
+const temporary = useTempDirectories('bc-catalogue-protection-');
+
+describe('catalogue launch and protection (#121)', () => {
+  it('protects a new profile beneath a symlink to a default root', async () => {
+    const homeDir = await temporary();
+    const options = { homeDir, environment: {} };
+    const root = resolveBrowserRoots('chrome', options)[0];
+    await mkdir(root, { recursive: true });
+    const alias = path.join(homeDir, 'profile-alias');
+    await symlink(
+      root,
+      alias,
+      process.platform === 'win32' ? 'junction' : 'dir'
+    );
+    assert.throws(
+      () =>
+        assertDedicatedUserDataDir(path.join(alias, 'new-profile'), options),
+      /dedicated.*default profile/
+    );
+  });
+
+  it('offers launch names for every supported Chromium source and alias', () => {
+    for (const browser of BROWSER_SOURCES.filter(
+      (entry) => entry.family === 'chromium'
+    )) {
+      assert.ok(CHANNEL_EXECUTABLE_NAMES[browser.id]?.length, browser.id);
+      for (const alias of browser.aliases ?? []) {
+        assert.deepEqual(
+          CHANNEL_EXECUTABLE_NAMES[alias],
+          CHANNEL_EXECUTABLE_NAMES[browser.id]
+        );
+      }
+    }
+  });
+
+  it('protects every catalogue root and descendant profile on every OS', () => {
+    for (const platform of ['linux', 'darwin', 'win32']) {
+      const options = {
+        platform,
+        homeDir: platform === 'win32' ? 'C:\\Users\\test' : '/users/test',
+        environment: {},
+      };
+      for (const browser of BROWSER_SOURCES) {
+        for (const root of resolveBrowserRoots(browser.id, options)) {
+          assert.throws(
+            () => assertDedicatedUserDataDir(root, options),
+            /dedicated.*default profile/,
+            `${browser.id}: ${root}`
+          );
+          assert.throws(
+            () =>
+              assertDedicatedUserDataDir(
+                `${root}${platform === 'win32' ? '\\' : '/'}Profile 1`,
+                options
+              ),
+            /dedicated.*default profile/
+          );
+        }
+      }
+    }
+  });
+
+  it('adds the requested desktop catalogue entries', () => {
+    for (const id of [
+      'whale',
+      '360se',
+      '360chrome',
+      'qq',
+      'sogou',
+      'duckduckgo',
+      'tor',
+    ]) {
+      assert.ok(
+        BROWSER_SOURCES.some((entry) => entry.id === id),
+        id
+      );
+    }
+  });
+});