browser-commander 0.23.0 → 0.25.0

package/tests/e2e/engine-matrix.e2e.test.js

@@ -0,0 +1,107 @@
+/** Native common launch and commander contracts for every JS engine (#124). */
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { describe, it } from 'node:test';
+import { launchBrowser } from '../../src/browser/launcher.js';
+import { makeBrowserCommander } from '../../src/factory.js';
+import {
+  CHROME_LAUNCH_OPTIONS,
+  PARITY_CHROME,
+} from '../helpers/e2e-browser.js';
+
+// feature-parity: engines.webdriver@native-typed engines.cli-matrix@native-typed
+describe('Common native engine API', { skip: !process.env.RUN_E2E }, () => {
+  it(
+    'selenium restores portable cookies and BiDi origin state',
+    { timeout: 60000 },
+    async () => {
+      const server = createServer((_request, response) => {
+        response.end('<title>Portable state</title>');
+      });
+      await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+      const origin = `http://127.0.0.1:${server.address().port}`;
+      let session;
+      try {
+        session = await launchBrowser({
+          engine: 'selenium',
+          launch: 'engine',
+          bidi: true,
+          headless: true,
+          executablePath: PARITY_CHROME,
+          ...CHROME_LAUNCH_OPTIONS,
+          storageState: {
+            cookies: [{ name: 'session', value: 'restored', url: origin }],
+            origins: [
+              { origin, localStorage: [{ name: 'theme', value: 'dark' }] },
+            ],
+          },
+        });
+        await session.page.goto(origin);
+        assert.equal(
+          await session.page.evaluate(() =>
+            globalThis.localStorage.getItem('theme')
+          ),
+          'dark'
+        );
+        assert.match(
+          await session.page.evaluate(() => document.cookie),
+          /session=restored/u
+        );
+      } finally {
+        await session?.close();
+        await new Promise((resolve) => server.close(resolve));
+      }
+    }
+  );
+  for (const engine of ['playwright', 'puppeteer', 'selenium']) {
+    for (const launch of ['real', 'engine']) {
+      it(
+        `${engine}/${launch}: input, click, native handles, PDF, cleanup`,
+        { timeout: 120000 },
+        async () => {
+          const session = await launchBrowser({
+            engine,
+            launch,
+            headless: true,
+            executablePath: PARITY_CHROME,
+            ...CHROME_LAUNCH_OPTIONS,
+          });
+          const commander = makeBrowserCommander({
+            page: session.page,
+            enableNetworkTracking: false,
+            enableNavigationManager: false,
+          });
+          const profile = session.userDataDir;
+          try {
+            assert.equal(commander.engine, engine);
+            await commander.goto({
+              url: `data:text/html,${encodeURIComponent('<input id="name"><button id="go" onclick="document.title=document.querySelector(\'#name\').value">Go</button>')}`,
+            });
+            await commander.fill({ selector: '#name', text: 'Ada' });
+            assert.equal(
+              await commander.inputValue({ selector: '#name' }),
+              'Ada'
+            );
+            await commander.click({ selector: '#go' });
+            assert.equal(await session.page.title(), 'Ada');
+            assert.ok(
+              Buffer.from(await session.page.pdf({ format: 'A4' }))
+                .subarray(0, 5)
+                .equals(Buffer.from('%PDF-'))
+            );
+            if (engine === 'selenium') {
+              assert.equal(await session.driver.getTitle(), 'Ada');
+            }
+          } finally {
+            await commander.destroy();
+            await session.close();
+          }
+          if (session.temporaryProfile) {
+            assert.equal(existsSync(profile), false);
+          }
+        }
+      );
+    }
+  }
+});

package/tests/e2e/playwright.e2e.test.js

@@ -9,6 +9,7 @@
 
 import { describe, it, before, after } from 'node:test';
 import assert from 'node:assert';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
 
 // Dynamic import for playwright since it may not be installed
 let playwright;
@@ -25,23 +26,16 @@ describe(
     const BASE_URL = process.env.TEST_URL || 'http://localhost:3000';
 
     before(async () => {
-      try {
-        playwright = await import('playwright');
-        const module = await import('../../src/index.js');
-        createCommander = module.createCommander;
-
-        browser = await playwright.chromium.launch({
-          headless: process.env.HEADLESS !== 'false',
-        });
-        const context = await browser.newContext();
-        page = await context.newPage();
-        commander = createCommander({ page, verbose: true });
-      } catch (error) {
-        console.log(
-          'Skipping E2E tests - playwright not available or test app not running'
-        );
-        console.log('Error:', error.message);
-      }
+      playwright = await import('playwright');
+      const module = await import('../../src/index.js');
+      createCommander = module.createCommander;
+      browser = await playwright.chromium.launch({
+        headless: process.env.HEADLESS !== 'false',
+        ...CHROME_LAUNCH_OPTIONS,
+      });
+      const context = await browser.newContext();
+      page = await context.newPage();
+      commander = createCommander({ page, verbose: true });
     });
 
     after(async () => {

package/tests/e2e/puppeteer.e2e.test.js

@@ -9,6 +9,7 @@
 
 import { describe, it, before, after } from 'node:test';
 import assert from 'node:assert';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
 
 // Dynamic import for puppeteer since it may not be installed
 let puppeteer;
@@ -22,22 +23,15 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
   const BASE_URL = process.env.TEST_URL || 'http://localhost:3000';
 
   before(async () => {
-    try {
-      puppeteer = await import('puppeteer');
-      const module = await import('../../src/index.js');
-      createCommander = module.createCommander;
-
-      browser = await puppeteer.default.launch({
-        headless: process.env.HEADLESS !== 'false' ? 'new' : false,
-      });
-      page = await browser.newPage();
-      commander = createCommander({ page, verbose: true });
-    } catch (error) {
-      console.log(
-        'Skipping E2E tests - puppeteer not available or test app not running'
-      );
-      console.log('Error:', error.message);
-    }
+    puppeteer = await import('puppeteer');
+    const module = await import('../../src/index.js');
+    createCommander = module.createCommander;
+    browser = await puppeteer.default.launch({
+      headless: process.env.HEADLESS !== 'false',
+      ...CHROME_LAUNCH_OPTIONS,
+    });
+    page = await browser.newPage();
+    commander = createCommander({ page, verbose: true });
   });
 
   after(async () => {
@@ -352,7 +346,9 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
       }
 
       // Scroll to specific item
-      await commander.scroll({ selector: '[data-testid="scroll-item-15"]' });
+      await commander.scrollIntoView({
+        locatorOrElement: await page.$('[data-testid="scroll-item-15"]'),
+      });
       await commander.wait({ ms: 500 });
 
       // Target should be visible

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
+      );
+    }
+  });
+});

package/tests/unit/browser/cookie-sources.test.js

@@ -1,17 +1,78 @@
 // feature-parity: sources.cookie-listing@native-typed
 import assert from 'node:assert';
 import { describe, it } from 'node:test';
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import BetterSqlite3 from 'better-sqlite3';
 
 import {
   listCookieSources,
   resolveImportSource,
 } from '../../../src/browser/browser-cookies.js';
+import { migrateProfile } from '../../../src/browser/migration/index.js';
 import { writeFirefoxProfile } from '../../helpers/migration-fixtures.js';
 import { useTempDirectories } from '../../helpers/temp-directory.js';
 
 const makeDirectory = useTempDirectories();
 
 describe('listCookieSources', () => {
+  it('matches only whole hosts and subdomains in both SQLite families', async () => {
+    const hosts = [
+      '.github.com',
+      'api.GITHUB.COM.',
+      'notgithub.com',
+      '.github.com.attacker.test',
+      '.gitXhub.com',
+    ];
+    for (const browser of ['firefox', 'chrome']) {
+      const homeDir = await makeDirectory('bc-source-domains-');
+      let file;
+      if (browser === 'firefox') {
+        const profile = await writeFirefoxProfile(
+          homeDir,
+          hosts.map((host, index) => ({
+            host,
+            name: `${index}`,
+            value: 'secret',
+          }))
+        );
+        file = path.join(profile, 'cookies.sqlite');
+      } else {
+        const profile = path.join(homeDir, '.config/google-chrome/Default');
+        await mkdir(profile, { recursive: true });
+        file = path.join(profile, 'Cookies');
+        const database = new BetterSqlite3(file);
+        try {
+          database.exec('CREATE TABLE cookies (host_key TEXT, value TEXT)');
+          for (const host of hosts) {
+            database
+              .prepare('INSERT INTO cookies VALUES (?, ?)')
+              .run(host, 'secret');
+          }
+        } finally {
+          database.close();
+        }
+      }
+      const before = await readFile(file);
+      const sources = await listCookieSources({
+        domains: ['GITHUB.COM.', 'git_hub.com', '%github.com'],
+        platform: 'linux',
+        homeDir,
+        environment: {},
+      });
+      assert.equal(sources.length, 1);
+      assert.equal(sources[0].browser, browser);
+      assert.equal(sources[0].cookies, hosts.length);
+      assert.deepEqual(sources[0].byDomain, {
+        'GITHUB.COM.': 2,
+        'git_hub.com': 0,
+        '%github.com': 0,
+      });
+      assert.ok(!JSON.stringify(sources).includes('secret'));
+      assert.deepEqual(await readFile(file), before);
+    }
+  });
+
   it('reports cookie counts per profile without reading values', async () => {
     const temporaryDirectory = await makeDirectory('bc-src-');
     const profilePath = await writeFirefoxProfile(temporaryDirectory, [
@@ -92,23 +153,37 @@ describe('resolveImportSource', () => {
     });
   });
 
-  it('falls back to the installed browser that holds the domains', async () => {
-    const homeDir = await makeDirectory('bc-import-fallback-');
-    await writeFirefoxProfile(homeDir, otherCookie);
-    await writeFirefoxProfile(homeDir, githubCookie, {
-      root: '.librewolf',
-      name: 'default',
-    });
-
-    const source = await resolve(homeDir);
-    assert.equal(source.browser, 'librewolf');
-    assert.equal(source.profile, 'default');
-    assert.equal(source.warning.reason, 'default-browser-fallback');
-    assert.equal(source.warning.item, 'librewolf');
-    assert.match(
-      source.warning.detail,
-      /default browser \(firefox\) holds no cookies for github\.com; imported from librewolf/
-    );
+  it('falls back when the default holds unrelated or lookalike domains', async () => {
+    for (const host of ['.other.test', '.notgithub.com']) {
+      const homeDir = await makeDirectory('bc-import-fallback-');
+      await writeFirefoxProfile(homeDir, [{ ...otherCookie[0], host }]);
+      await writeFirefoxProfile(homeDir, githubCookie, {
+        root: '.librewolf',
+        name: 'default',
+      });
+      const source = await resolve(homeDir);
+      assert.equal(source.browser, 'librewolf');
+      assert.equal(source.profile, 'default');
+      assert.equal(source.warning.reason, 'default-browser-fallback');
+      assert.equal(source.warning.item, 'librewolf');
+      assert.match(
+        source.warning.detail,
+        /default browser \(firefox\) holds no cookies for github\.com; imported from librewolf/
+      );
+      const report = await migrateProfile({
+        from: { browser: 'auto' },
+        to: path.join(homeDir, 'target'),
+        include: ['cookies'],
+        domains: ['github.com'],
+        platform: 'linux',
+        homeDir,
+        environment: {},
+        runCommand: firefoxIsDefault,
+      });
+      assert.equal(report.source.browser, 'librewolf');
+      assert.equal(report.migrated.cookies, 1);
+      assert.equal(report.cookies[0].domain, '.github.com');
+    }
   });
 
   it('falls back when the system default cannot be determined', async () => {

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

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { BROWSER_SOURCES } from '../../../src/browser/browser-sources.js';
+import { readSafeStoragePassword } from '../../../src/browser/browser-cookie-credentials.js';
+
+describe('catalogue credential identities and Keychain diagnostics', () => {
+  it('requests every declared browser service rather than a four-browser table', async () => {
+    for (const browser of BROWSER_SOURCES.filter(
+      (entry) => entry.safeStorage
+    )) {
+      for (const name of [browser.id, ...(browser.aliases ?? [])]) {
+        const calls = [];
+        const password = await readSafeStoragePassword({
+          browser: name,
+          platform: 'darwin',
+          environment: {},
+          runCredentialCommand: async (command, args) => {
+            calls.push([command, args]);
+            return 'synthetic-password';
+          },
+        });
+        assert.equal(password, 'synthetic-password');
+        assert.deepEqual(calls, [
+          [
+            'security',
+            ['find-generic-password', '-w', '-s', browser.safeStorage.service],
+          ],
+        ]);
+      }
+    }
+  });
+
+  for (const outcome of ['denied', 'empty']) {
+    it(`identifies the item and retry path when Keychain returns ${outcome}`, async () => {
+      await assert.rejects(
+        readSafeStoragePassword({
+          browser: 'chrome',
+          platform: 'darwin',
+          runCredentialCommand: async () => {
+            if (outcome === 'denied') {
+              throw new Error('security exited with code 36');
+            }
+            return '';
+          },
+        }),
+        /Chrome Safe Storage.*Keychain.*allow.*retry.*refresh=true/s
+      );
+    });
+  }
+});

package/tests/unit/browser/firefox-cookie-expiry.test.js

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { it } from 'node:test';
+
+import { openSqliteDatabase } from '../../../src/browser/browser-cookie-database.js';
+import { readBrowserCookiesWithDependencies } from '../../../src/browser/browser-cookies.js';
+import { migrateProfile } from '../../../src/browser/migration/index.js';
+
+const fixture = await readFile(
+  new URL(
+    '../../../../tests/fixtures/firefox-cookie-expiry.sql',
+    import.meta.url
+  ),
+  'utf8'
+);
+
+for (const version of [0, 15, 16, 17]) {
+  for (const migration of [false, true]) {
+    it(`normalizes Firefox schema ${version} expiry through ${migration ? 'migration' : 'installed reading'}`, async () => {
+      const homeDir = await mkdtemp(path.join(os.tmpdir(), 'bc-ff-expiry-'));
+      try {
+        const root = path.join(homeDir, '.mozilla', 'firefox');
+        const source = path.join(root, 'expiry.default-release');
+        await mkdir(source, { recursive: true });
+        await writeFile(
+          path.join(root, 'profiles.ini'),
+          '[Profile0]\nName=default-release\nIsRelative=1\nPath=expiry.default-release\nDefault=1\n'
+        );
+        const file = path.join(source, 'cookies.sqlite');
+        const database = await openSqliteDatabase(file);
+        try {
+          database.exec(fixture);
+          database.exec(`PRAGMA user_version = ${version}`);
+          if (version >= 16) {
+            database.exec(
+              'UPDATE moz_cookies SET expiry = expiry * 1000 + 999 WHERE expiry > 0'
+            );
+          }
+        } finally {
+          database.close();
+        }
+        const before = await readFile(file);
+        const options = { platform: 'linux', homeDir, environment: {} };
+        const cookies = migration
+          ? (
+              await migrateProfile({
+                from: { browser: 'firefox', userDataDir: source },
+                to: path.join(homeDir, 'target'),
+                include: ['cookies'],
+                domains: ['expiry.example'],
+                ...options,
+              })
+            ).cookies
+          : await readBrowserCookiesWithDependencies(
+              {
+                browser: 'firefox',
+                domainFilter: 'expiry.example',
+                cache: false,
+              },
+              options
+            );
+        assert.equal(cookies.length, 3);
+        const expiry = Object.fromEntries(
+          cookies.map((cookie) => [cookie.name, cookie.expires])
+        );
+        assert.deepEqual(expiry, {
+          persistent: 2_000_000_001,
+          'session-negative': -1,
+          'session-zero': -1,
+        });
+        assert.deepEqual(await readFile(file), before);
+      } finally {
+        await rm(homeDir, { recursive: true, force: true });
+      }
+    });
+  }
+}