browser-commander 0.18.0 → 0.20.0

package/tests/helpers/trace-fixtures.js

@@ -8,6 +8,7 @@
  */
 
 import { EventEmitter } from 'node:events';
+import { afterEach } from 'node:test';
 import { useTempDirectory } from './temp-directory.js';
 
 /**
@@ -19,6 +20,23 @@ export function useTempTraceDirectory() {
   return useTempDirectory('bc-traces-');
 }
 
+/**
+ * Close every bundle a test opened, including deliberately truncated ones.
+ *
+ * @returns {(bundle: Object) => Object} Tracker for an opened bundle
+ */
+export function useTraceBundleCleanup() {
+  const bundles = new Set();
+  afterEach(async () => {
+    await Promise.all([...bundles].map((bundle) => bundle.abort()));
+    bundles.clear();
+  });
+  return (bundle) => {
+    bundles.add(bundle);
+    return bundle;
+  };
+}
+
 /**
  * A snapshot shaped like the one the in-page capture returns.
  *
@@ -50,7 +68,10 @@ export function makeSnapshot(overrides = {}) {
 /**
  * Create a fake page the recorder can drive.
  *
- * @param {Object} [options] - `{snapshot, mutations, screenshot}`
+ * @param {Object} [options] - `{snapshot, mutations, screenshot, frames}`
+ * @param {Object[]} [options.frames] - Extra frames, each `{mutations}`; the
+ *   page itself is always the main frame, and a page given no frames has no
+ *   `frames()` at all, the way a page object from neither engine would
  * @returns {Object} The fake page
  */
 export function createFakePage(options = {}) {
@@ -62,10 +83,11 @@ export function createFakePage(options = {}) {
     screenshot: options.screenshot ?? Buffer.from('fake-png'),
     screenshots: 0,
     evaluated: [],
+    initScripts: [],
     failures: new Map(),
   };
 
-  return {
+  const page = {
     state,
     /**
      * Make one in-page call fail, the way a closed page does.
@@ -112,7 +134,17 @@ export function createFakePage(options = {}) {
         const batches = state.mutations.splice(0, state.mutations.length);
         const dropped = state.droppedMutations;
         state.droppedMutations = 0;
-        return { batches, dropped, installed: true };
+        return {
+          batches: batches.map((batch) => ({
+            frameId: 'main',
+            mainFrame: true,
+            ...batch,
+          })),
+          dropped,
+          installed: true,
+          frameId: 'main',
+          mainFrame: true,
+        };
       }
       return true;
     },
@@ -120,11 +152,73 @@ export function createFakePage(options = {}) {
       state.screenshots += 1;
       return state.screenshot;
     },
+    /**
+     * Register a script for every future document, the Playwright spelling.
+     *
+     * @param {Function} fn - The function to run
+     * @param {*} argument - Its argument
+     * @returns {Promise<void>} Resolves once registered
+     */
+    addInitScript: async (fn, argument) => {
+      state.initScripts.push({
+        name: typeof fn === 'function' ? fn.name : String(fn),
+        argument,
+      });
+    },
     on: (event, listener) => emitter.on(event, listener),
     off: (event, listener) => emitter.off(event, listener),
     emit: (event, payload) => emitter.emit(event, payload),
     listenerCount: (event) => emitter.listenerCount(event),
   };
+
+  if (options.frames) {
+    const children = options.frames.map((frame, index) =>
+      createFakeFrame(state, frame, `child-${index + 1}`)
+    );
+    page.frames = () => [
+      createFakeFrame(state, null, 'main', page),
+      ...children,
+    ];
+  }
+
+  return page;
+}
+
+/**
+ * One frame of a fake page.
+ *
+ * The main frame answers out of the page's own state, so a page with frames
+ * behaves exactly like one without for everything except the extra documents.
+ *
+ * @param {Object} state - The page's state
+ * @param {Object|null} frame - `{mutations, dropped}` for a child frame
+ * @param {string} frameId - What this frame calls itself
+ * @param {Object} [page] - The page, when this is the main frame
+ * @returns {Object} A frame with `evaluate`
+ */
+function createFakeFrame(state, frame, frameId, page) {
+  if (page) {
+    return { evaluate: page.evaluate };
+  }
+  const queued = frame?.mutations ? [...frame.mutations] : [];
+  return {
+    evaluate: async (fn, argument) => {
+      const name = typeof fn === 'function' ? fn.name : String(fn);
+      state.evaluated.push({ name, argument, frameId });
+      if (name === 'drainMutationsInPage') {
+        return {
+          batches: queued
+            .splice(0, queued.length)
+            .map((batch) => ({ frameId, mainFrame: false, ...batch })),
+          dropped: frame?.dropped ?? 0,
+          installed: true,
+          frameId,
+          mainFrame: false,
+        };
+      }
+      return true;
+    },
+  };
 }
 
 /**

package/tests/helpers/trace-server.js

@@ -25,12 +25,19 @@ export const TRACE_PAGE = `<!doctype html>
     <select id="plan"><option value="free">Free</option><option value="pro">Pro</option></select>
     <label><input id="terms" type="checkbox"> I agree</label>
   </form>
-  <ul id="items"></ul>
+  <ul id="items"><li id="item-a">a</li><li id="item-b">b</li></ul>
+  <div id="subtree"><p id="old-child">old</p></div>
   <p id="status" data-state="idle">idle</p>
+  <textarea id="notes"></textarea>
+  <div id="tall" style="height:3000px"></div>
   <iframe id="inner" name="inner" src="/frame" style="width:80px;height:40px"></iframe>
   <a id="next" href="/next">Go to the next page</a>
   <a id="download" href="/file/report.txt" download>Download the report</a>
   <button id="add" type="button">Add an item</button>
+  <button id="insert-first" type="button">Insert before the first item</button>
+  <button id="move-last" type="button">Move the last item to the front</button>
+  <button id="remove-one" type="button">Remove an item</button>
+  <button id="replace-subtree" type="button">Replace a subtree</button>
   <button id="touch" type="button">Change the status</button>
   <button id="log" type="button">Log something</button>
   <button id="boom" type="button">Throw</button>
@@ -44,6 +51,30 @@ export const TRACE_PAGE = `<!doctype html>
       item.textContent = 'item ' + added;
       document.getElementById('items').appendChild(item);
     });
+    // Issue #93's third regression case: a replay that only appends gets
+    // every one of these wrong.
+    const items = () => document.getElementById('items');
+    document.getElementById('insert-first').addEventListener('click', () => {
+      const item = document.createElement('li');
+      item.id = 'inserted';
+      item.textContent = 'inserted first';
+      items().insertBefore(item, items().firstChild);
+    });
+    document.getElementById('move-last').addEventListener('click', () => {
+      items().insertBefore(items().lastElementChild, items().firstChild);
+    });
+    document.getElementById('remove-one').addEventListener('click', () => {
+      const gone = document.getElementById('item-a');
+      if (gone) gone.remove();
+    });
+    document.getElementById('replace-subtree').addEventListener('click', () => {
+      const subtree = document.getElementById('subtree');
+      subtree.replaceChildren();
+      const fresh = document.createElement('p');
+      fresh.id = 'new-child';
+      fresh.textContent = 'new';
+      subtree.appendChild(fresh);
+    });
     document.getElementById('touch').addEventListener('click', () => {
       const status = document.getElementById('status');
       status.setAttribute('data-state', 'touched');
@@ -68,6 +99,27 @@ export const TRACE_PAGE = `<!doctype html>
   </script>
 </body></html>`;
 
+/**
+ * A page that changes its own DOM while it is still loading.
+ *
+ * Issue #93's first regression case: the interval between a navigation and the
+ * next checkpoint used to be unrecorded, because the in-page observer died
+ * with the previous document. Everything this page builds happens before any
+ * automation could install an observer after the fact.
+ */
+export const INIT_PAGE = `<!doctype html>
+<html><head><title>Initializing page</title></head>
+<body style="margin:0">
+  <div id="root"></div>
+  <script>
+    const made = document.createElement('p');
+    made.id = 'made-while-loading';
+    made.textContent = 'built during initialization';
+    document.getElementById('root').appendChild(made);
+    document.getElementById('root').setAttribute('data-initialized', 'yes');
+  </script>
+</body></html>`;
+
 /** The page a full navigation lands on. */
 export const NEXT_PAGE = `<!doctype html>
 <html><head><title>Next page</title></head>
@@ -96,6 +148,10 @@ export async function startTraceServer() {
       sendHtml(res, TRACE_PAGE);
       return;
     }
+    if (path === '/init') {
+      sendHtml(res, INIT_PAGE);
+      return;
+    }
     if (path === '/next') {
       sendHtml(res, NEXT_PAGE);
       return;

package/tests/unit/downloads/manager.test.js

@@ -271,22 +271,95 @@ describe('download manager (issue #88)', () => {
         },
       });
 
+    /**
+     * Describe the CDP command that sends downloads to this test's staging path.
+     *
+     * @param {string} [browserContextId] - Context to configure
+     * @returns {Object} Expected CDP command
+     */
+    const downloadBehaviorCommand = (browserContextId) => ({
+      method: 'Browser.setDownloadBehavior',
+      params: {
+        behavior: 'allowAndName',
+        downloadPath: path.join(root, STAGING_DIRECTORY),
+        eventsEnabled: true,
+        ...(browserContextId ? { browserContextId } : {}),
+      },
+    });
+
     it('should ask Chromium to report downloads it did not automate', async () => {
       const session = createFakeCdpSession();
       manager = await cdpManagerOver(session);
 
-      assert.deepStrictEqual(session.sent, [
-        {
-          method: 'Browser.setDownloadBehavior',
-          params: {
-            behavior: 'allowAndName',
-            downloadPath: path.join(root, STAGING_DIRECTORY),
-            eventsEnabled: true,
-          },
-        },
+      assert.deepStrictEqual(session.sent, [downloadBehaviorCommand()]);
+    });
+
+    it('should scope download behavior to the page browser context', async () => {
+      // Issue #97: browser.newPage() and browser.newContext() create a
+      // non-default Chromium context. Browser download events are global, but
+      // the path configured without this id belongs to the default context.
+      const browserSession = createFakeCdpSession();
+      browserSession.send = async (method, params) => {
+        browserSession.sent.push({ method, params });
+        if (method === 'Target.getBrowserContexts') {
+          return { browserContextIds: ['context-from-target'] };
+        }
+        return undefined;
+      };
+      const pageSession = createFakeCdpSession();
+      pageSession.send = async (method, params) => {
+        pageSession.sent.push({ method, params });
+        return {
+          targetInfo: { browserContextId: 'context-from-target' },
+        };
+      };
+      let pageSessionDetached = false;
+      pageSession.detach = async () => {
+        pageSessionDetached = true;
+      };
+      const browser = {
+        newBrowserCDPSession: async () => browserSession,
+      };
+      const browserContext = {
+        browser: () => browser,
+        newCDPSession: async () => pageSession,
+      };
+      const page = { context: () => browserContext };
+
+      manager = await createDownloadManager({
+        engine: 'playwright',
+        browser: browserContext,
+        page,
+        directory: root,
+      });
+
+      assert.deepStrictEqual(pageSession.sent, [
+        { method: 'Target.getTargetInfo', params: undefined },
+      ]);
+      assert.strictEqual(pageSessionDetached, true);
+      assert.deepStrictEqual(browserSession.sent, [
+        { method: 'Target.getBrowserContexts', params: undefined },
+        downloadBehaviorCommand('context-from-target'),
       ]);
     });
 
+    it('should keep a persistent context on default download behavior', async () => {
+      const session = createFakeCdpSession();
+      const persistentContext = {
+        browser: () => null,
+        newCDPSession: async () => session,
+      };
+
+      manager = await createDownloadManager({
+        engine: 'playwright',
+        browser: persistentContext,
+        page: { context: () => persistentContext },
+        directory: root,
+      });
+
+      assert.deepStrictEqual(session.sent, [downloadBehaviorCommand()]);
+    });
+
     it('should place a manually started download like an automated one', async () => {
       const session = createFakeCdpSession();
       manager = await cdpManagerOver(session);
@@ -338,6 +411,137 @@ describe('download manager (issue #88)', () => {
       assert.match(cancelled[0].failure, /canceled/);
     });
 
+    it('should wait for staged bytes that land after the completion event', async () => {
+      // Issue #92: Chromium writes `<guid>.crdownload` and renames it, so the
+      // completion event can arrive before `<guid>` is openable. Publishing on
+      // the event alone turned a download that succeeded into
+      // `ENOENT ... .browser-commander-staging/<guid>`.
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+      const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+      const failed = collect(DOWNLOAD_EVENT.FAILED);
+
+      const guid = 'guid-0010';
+      const stagedPath = path.join(root, STAGING_DIRECTORY, guid);
+      session.emit('Browser.downloadWillBegin', {
+        guid,
+        url: 'https://example.com/late.pdf',
+        suggestedFilename: 'late.pdf',
+      });
+      // The event first, the bytes afterwards - the ordering from the report.
+      session.emit('Browser.downloadProgress', { guid, state: 'completed' });
+      await yieldToEngine();
+      assert.deepStrictEqual(completed, [], 'published before the bytes exist');
+      await fs.writeFile(stagedPath, 'late body');
+
+      await manager.idle();
+
+      assert.deepStrictEqual(failed, []);
+      assert.strictEqual(completed.length, 1);
+      assert.strictEqual(
+        await fs.readFile(completed[0].path, 'utf8'),
+        'late body'
+      );
+      assert.deepStrictEqual(
+        await fs.readdir(path.join(root, STAGING_DIRECTORY)),
+        []
+      );
+    });
+
+    it('should not claim bytes while the partial file is still being written', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+      const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+
+      const guid = 'guid-0011';
+      const stagedPath = path.join(root, STAGING_DIRECTORY, guid);
+      session.emit('Browser.downloadWillBegin', {
+        guid,
+        url: 'https://example.com/partial.pdf',
+        suggestedFilename: 'partial.pdf',
+      });
+      // A half-written file under the final name, with Chromium's own
+      // in-progress marker still beside it.
+      await fs.writeFile(stagedPath, 'half');
+      await fs.writeFile(`${stagedPath}.crdownload`, 'rest');
+      session.emit('Browser.downloadProgress', { guid, state: 'completed' });
+      await yieldToEngine();
+      await yieldToEngine();
+      assert.deepStrictEqual(completed, [], 'claimed a half-written file');
+
+      await fs.rm(`${stagedPath}.crdownload`);
+      await fs.writeFile(stagedPath, 'half and rest');
+      await manager.idle();
+
+      assert.strictEqual(completed.length, 1);
+      assert.strictEqual(
+        await fs.readFile(completed[0].path, 'utf8'),
+        'half and rest'
+      );
+    });
+
+    it('should report a completion whose bytes never arrive as a failure', async () => {
+      const session = createFakeCdpSession();
+      manager = await createDownloadManager({
+        engine: 'puppeteer',
+        directory: root,
+        browser: {
+          target: () => ({ createCDPSession: async () => session }),
+        },
+        stagingTimeout: 60,
+        stagingPollInterval: 5,
+      });
+      const failed = collect(DOWNLOAD_EVENT.FAILED);
+      const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+
+      session.emit('Browser.downloadWillBegin', {
+        guid: 'guid-0012',
+        url: 'https://example.com/ghost.pdf',
+        suggestedFilename: 'ghost.pdf',
+      });
+      session.emit('Browser.downloadProgress', {
+        guid: 'guid-0012',
+        state: 'completed',
+      });
+      await manager.idle();
+
+      assert.deepStrictEqual(completed, []);
+      assert.strictEqual(failed.length, 1);
+      assert.match(failed[0].failure, /was not readable within 60ms/);
+      assert.match(failed[0].failure, /guid-0012/);
+    });
+
+    it('should keep a capture waiting until the staged bytes are readable', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+
+      const guid = 'guid-0013';
+      const stagedPath = path.join(root, STAGING_DIRECTORY, guid);
+      const artifact = await manager.capture({
+        timeout: 5000,
+        action: async () => {
+          session.emit('Browser.downloadWillBegin', {
+            guid,
+            url: 'https://example.com/captured.pdf',
+            suggestedFilename: 'captured.pdf',
+          });
+          session.emit('Browser.downloadProgress', {
+            guid,
+            state: 'completed',
+          });
+          setTimeout(() => {
+            fs.writeFile(stagedPath, 'captured body').catch(() => {});
+          }, 40);
+        },
+      });
+
+      assert.strictEqual(artifact.state, DOWNLOAD_EVENT.COMPLETED);
+      assert.strictEqual(
+        await fs.readFile(artifact.path, 'utf8'),
+        'captured body'
+      );
+    });
+
     it('should ignore progress for a download it never saw start', async () => {
       const session = createFakeCdpSession();
       manager = await cdpManagerOver(session);

package/tests/unit/downloads/staging.test.js

@@ -0,0 +1,139 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  DEFAULT_STAGING_POLL_INTERVAL,
+  DEFAULT_STAGING_STABILITY,
+  DEFAULT_STAGING_TIMEOUT,
+  describeStagingTimeout,
+  STAGING_IN_PROGRESS_SUFFIXES,
+  waitForStagedFile,
+} from '../../../src/downloads/staging.js';
+import { useTempDownloadDirectory } from '../../helpers/download-fixtures.js';
+
+describe('waiting for staged bytes (issue #92)', () => {
+  const directory = useTempDownloadDirectory();
+
+  it('should report a file that is already complete', async () => {
+    const staged = path.join(directory.path, 'guid-ready');
+    await fs.writeFile(staged, 'complete body');
+
+    const settled = await waitForStagedFile({ path: staged, timeout: 1000 });
+
+    assert.strictEqual(settled.ready, true);
+    assert.strictEqual(settled.bytes, 'complete body'.length);
+    assert.strictEqual(settled.reason, null);
+  });
+
+  it('should wait for a file that appears after the completion event', async () => {
+    // This is issue #92 exactly: the browser says "completed" and the rename
+    // Chromium does behind it has not become visible yet.
+    const staged = path.join(directory.path, 'guid-late');
+    const appear = setTimeout(() => {
+      fs.writeFile(staged, 'late body').catch(() => {});
+    }, 60);
+
+    const settled = await waitForStagedFile({
+      path: staged,
+      timeout: 5000,
+      interval: 5,
+    });
+    clearTimeout(appear);
+
+    assert.strictEqual(settled.ready, true, settled.reason ?? '');
+    assert.strictEqual(settled.bytes, 'late body'.length);
+  });
+
+  it('should keep waiting while the file is still growing', async () => {
+    const staged = path.join(directory.path, 'guid-growing');
+    await fs.writeFile(staged, 'a');
+    const grow = setInterval(() => {
+      fs.appendFile(staged, 'a').catch(() => {});
+    }, 5);
+    setTimeout(() => clearInterval(grow), 80);
+
+    const settled = await waitForStagedFile({
+      path: staged,
+      timeout: 5000,
+      interval: 5,
+    });
+    clearInterval(grow);
+
+    assert.strictEqual(settled.ready, true, settled.reason ?? '');
+    // The quiet period ends the wait, so the file had stopped growing before
+    // it was declared ready.
+    assert.strictEqual(settled.bytes, (await fs.stat(staged)).size);
+  });
+
+  it('should survive a pause between writes that is longer than one poll', async () => {
+    const staged = path.join(directory.path, 'guid-paused');
+    await fs.writeFile(staged, 'first');
+    const resume = setTimeout(() => {
+      fs.appendFile(staged, '-second').catch(() => {});
+    }, 25);
+
+    const settled = await waitForStagedFile({
+      path: staged,
+      timeout: 1000,
+      interval: 5,
+      stability: 60,
+    });
+    clearTimeout(resume);
+
+    assert.strictEqual(settled.ready, true, settled.reason ?? '');
+    assert.strictEqual(settled.bytes, 'first-second'.length);
+    assert.ok(settled.waitedMs >= 60);
+  });
+
+  it('should not claim a file whose partial sibling is still being written', async () => {
+    const staged = path.join(directory.path, 'guid-partial');
+    await fs.writeFile(staged, 'looks done');
+    await fs.writeFile(`${staged}.crdownload`, 'still writing');
+
+    const settled = await waitForStagedFile({
+      path: staged,
+      timeout: 60,
+      interval: 5,
+    });
+
+    assert.strictEqual(settled.ready, false);
+    assert.match(settled.reason, /\.crdownload file is still being written/);
+  });
+
+  it('should fail explicitly when the bytes never arrive', async () => {
+    const staged = path.join(directory.path, 'guid-missing');
+
+    const settled = await waitForStagedFile({
+      path: staged,
+      timeout: 60,
+      interval: 5,
+    });
+
+    assert.strictEqual(settled.ready, false);
+    assert.strictEqual(settled.bytes, null);
+    assert.match(settled.reason, /has not appeared/);
+  });
+
+  it('should name the file, the budget and what it last saw', () => {
+    const message = describeStagingTimeout({
+      path: '/tmp/root/.browser-commander-staging/guid',
+      timeout: 250,
+      reason: 'the file has not appeared yet',
+    });
+
+    assert.match(message, /reported the download as completed/);
+    assert.match(message, /guid/);
+    assert.match(message, /250ms/);
+    assert.match(message, /has not appeared yet/);
+  });
+
+  it('should ship defaults a download can actually finish within', () => {
+    assert.ok(DEFAULT_STAGING_TIMEOUT >= 1000);
+    assert.ok(DEFAULT_STAGING_POLL_INTERVAL > 0);
+    assert.ok(DEFAULT_STAGING_STABILITY > DEFAULT_STAGING_POLL_INTERVAL);
+    assert.ok(DEFAULT_STAGING_POLL_INTERVAL < DEFAULT_STAGING_TIMEOUT);
+    assert.ok(STAGING_IN_PROGRESS_SUFFIXES.includes('.crdownload'));
+  });
+});

package/tests/unit/scripts/ci-workflow-policy.test.js

@@ -155,6 +155,14 @@ jobs:
     assert.equal(countFailures(content), 2);
   });
 
+  it('rejects download-artifact v7 after its runtime emitted DEP0005', () => {
+    const content = workflow({
+      steps: '      - uses: actions/download-artifact@v7',
+    });
+
+    assert.equal(countFailures(content), 1);
+  });
+
   it('accepts a base_ref bound to any environment variable name', () => {
     const content = workflow({
       on: 'pull_request',

package/tests/unit/scripts/npm-release-helpers.test.js

@@ -131,6 +131,7 @@ describe('test runner helper', () => {
       buildNodeTestArgs(options, ['tests/unit/a.test.js'], '24.18.0'),
       [
         '--test',
+        '--throw-deprecation',
         '--test-isolation=none',
         '--experimental-test-coverage',
         '--test-reporter',
@@ -144,8 +145,8 @@ describe('test runner helper', () => {
     const options = parseTestRunnerArgs(['tests/unit']);
 
     assert.deepEqual(
-      buildNodeTestArgs(options, ['tests/unit/a.test.js'], '20.20.2'),
-      ['--test', 'tests/unit/a.test.js']
+      buildNodeTestArgs(options, ['tests/unit/a.test.js'], '22.22.3'),
+      ['--test', '--throw-deprecation', 'tests/unit/a.test.js']
     );
   });
 });

package/tests/unit/scripts/pre-commit-config.test.js

@@ -48,7 +48,8 @@ const MIRRORED_COMMANDS = [
   {
     id: 'python-mypy-scripts',
     workflow: 'python.yml',
-    command: 'mypy --python-version 3.13 scripts tests/unit/scripts',
+    command:
+      'mypy --no-warn-unused-configs --python-version 3.13 scripts tests/unit/scripts',
   },
   {
     id: 'rust-fmt',