browser-commander 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.20.0
+
+### Minor Changes
+
+- Persist managed downloads from Playwright pages in non-default Chromium browser
+  contexts. Browser Commander now resolves the page target's `browserContextId`
+  and applies its staging directory to that context while retaining browser-wide
+  download lifecycle events.
+
+  Wait for a real quiet period before accepting staged download bytes, close unfinished trace bundles explicitly in tests, and move the supported Node.js floor to 22 with the maintained `better-sqlite3` fallback.
+
 ## 0.19.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",
@@ -52,7 +52,7 @@
   },
   "homepage": "https://github.com/link-foundation/browser-commander#readme",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "peerDependencies": {
     "playwright": ">=1.40.0",
@@ -67,7 +67,7 @@
     }
   },
   "dependencies": {
-    "better-sqlite3": "^12.11.1",
+    "better-sqlite3": "^13.0.3",
     "links-notation": "^0.20.0",
     "log-lazy": "^1.0.4",
     "test-anywhere": "^0.9.1"
@@ -83,5 +83,9 @@
     "playwright": "^1.62.1",
     "prettier": "^3.9.6",
     "puppeteer": "^25.10.0"
+  },
+  "allowScripts": {
+    "better-sqlite3@13.0.3": true,
+    "puppeteer": false
   }
 }

package/scripts/run-tests.mjs

@@ -147,13 +147,15 @@ export function buildNodeTestArgs(
   testFiles,
   nodeVersion = process.versions.node
 ) {
-  const args = ['--test'];
+  // A resource leak that is a warning today becomes a runtime failure in a
+  // later Node release. Make deprecations fail at the point that creates them.
+  const args = ['--test', '--throw-deprecation'];
 
   // Node's default process isolation serializes each test file's results over
   // a child-process channel. Node 24 on macOS can intermittently corrupt that
   // stream (ERR_TEST_FAILURE: "Unable to deserialize cloned data"). Running
   // supported runtimes in-process removes that transport while keeping the
-  // Node 20-compatible fallback for consumers on the minimum engine version.
+  // Node 22-compatible fallback for consumers on the minimum engine version.
   if (supportsTestIsolation(nodeVersion)) {
     args.push('--test-isolation=none');
   }

package/src/downloads/manager.js

@@ -22,6 +22,7 @@ import {
 import {
   attachCdpSource,
   attachPlaywrightSource,
+  browserContextIdForPage,
   classifyFailure,
   DOWNLOAD_FAILURE,
   openBrowserCdpSession,
@@ -308,17 +309,25 @@ export async function createDownloadManager(options = {}) {
   try {
     cdpSession = await openBrowserCdpSession({ engine, browser, page });
     if (cdpSession) {
+      const browserContextId = await browserContextIdForPage({
+        engine,
+        browser,
+        page,
+        browserSession: cdpSession,
+      });
       attached.push(
         await attachCdpSource({
           session: cdpSession,
           root,
           sink,
+          browserContextId,
           stagingTimeout,
           stagingPollInterval,
         })
       );
     }
   } catch (error) {
+    await cdpSession?.detach?.().catch?.(() => {});
     cdpSession = undefined;
     log?.warn?.(`manual downloads are not observable: ${error.message}`);
   }

package/src/downloads/sources.js

@@ -92,6 +92,7 @@ export function attachPlaywrightSource({ context, sink }) {
  * @param {Object} options.session - CDP session with Browser domain access
  * @param {string} options.root - Managed download directory
  * @param {Object} options.sink - `{started, finished, failed, track}` callbacks
+ * @param {string} [options.browserContextId] - Chromium context to configure
  * @param {number} [options.stagingTimeout] - Budget for the bytes to land on disk
  * @param {number} [options.stagingPollInterval] - Milliseconds between readings
  * @returns {Promise<Object>} Handle with `detach()` and `stagingDirectory`
@@ -100,6 +101,7 @@ export async function attachCdpSource({
   session,
   root,
   sink,
+  browserContextId,
   stagingTimeout,
   stagingPollInterval,
 }) {
@@ -116,6 +118,7 @@ export async function attachCdpSource({
     behavior: 'allowAndName',
     downloadPath: stagingDirectory,
     eventsEnabled: true,
+    ...(browserContextId ? { browserContextId } : {}),
   });
 
   const byGuid = new Map();
@@ -200,6 +203,74 @@ export async function attachCdpSource({
   };
 }
 
+/**
+ * Read the Chromium browser-context id that owns a page.
+ *
+ * `Browser.setDownloadBehavior` is sent over a browser-wide session so its
+ * events cover the whole browser, but omitting `browserContextId` configures
+ * only Chromium's default context. Playwright's `browser.newPage()` convenience
+ * API creates a non-default context, whose id is exposed by its target.
+ *
+ * @param {Object} options - Browser handles
+ * @param {string} options.engine - Engine name
+ * @param {Object} [options.browser] - Browser or persistent context
+ * @param {Object} [options.page] - Page whose context downloads belong to
+ * @param {Object} [options.browserSession] - Browser-wide CDP session
+ * @returns {Promise<string|undefined>} Chromium context id, when non-default
+ */
+export async function browserContextIdForPage({
+  engine,
+  browser,
+  page,
+  browserSession,
+}) {
+  if (engine !== 'playwright' || !page) {
+    return undefined;
+  }
+
+  const context = page.context?.() ?? browser;
+  // Playwright exposes a persistent context as the browser's default context:
+  // unlike browser.newContext(), its `browser()` is null. Keeping the id
+  // absent preserves default-context behavior, including downloads from tabs
+  // opened outside the automation.
+  if (typeof context?.browser === 'function' && !context.browser()) {
+    return undefined;
+  }
+  const pageSession = await context?.newCDPSession?.(page);
+  if (!pageSession) {
+    return undefined;
+  }
+
+  let browserContextId;
+  try {
+    const { targetInfo } = await pageSession.send('Target.getTargetInfo');
+    browserContextId = targetInfo?.browserContextId || undefined;
+  } finally {
+    // This session exists only for target metadata. A failure to detach it
+    // must not discard the id that lets the long-lived source work correctly.
+    await pageSession.detach?.().catch?.(() => {});
+  }
+  if (!browserContextId || !browserSession) {
+    return browserContextId;
+  }
+
+  try {
+    // TargetInfo also reports an opaque id for a persistent/default context in
+    // current Chromium. Only ids returned here are true non-default contexts
+    // accepted by Browser.setDownloadBehavior's browserContextId parameter.
+    const { browserContextIds = [] } = await browserSession.send(
+      'Target.getBrowserContexts'
+    );
+    return browserContextIds.includes(browserContextId)
+      ? browserContextId
+      : undefined;
+  } catch {
+    // Older/page-scoped CDP bridges may not expose getBrowserContexts. The
+    // persistent-context guard above handles their known default-context case.
+    return browserContextId;
+  }
+}
+
 /**
  * Open a CDP session that can drive the Browser domain.
  *

package/src/downloads/staging.js

@@ -26,6 +26,9 @@ export const DEFAULT_STAGING_TIMEOUT = 10000;
 /** How often the staged file is looked at while waiting. */
 export const DEFAULT_STAGING_POLL_INTERVAL = 25;
 
+/** How long an unchanged size must remain observable before it is complete. */
+export const DEFAULT_STAGING_STABILITY = 100;
+
 /** Suffixes Chromium uses for a file it is still writing. */
 export const STAGING_IN_PROGRESS_SUFFIXES = Object.freeze([
   '.crdownload',
@@ -77,14 +80,15 @@ async function observeStagedFile(filePath, suffixes) {
 /**
  * Wait until a staged download is readable and has stopped growing.
  *
- * Stability is decided by two consecutive readings of the same size, the same
- * evidence the Selenium directory watcher uses: a file that merely exists is
- * not evidence that its last byte was written.
+ * Stability is decided by an unchanged-size quiet period. Two equal readings
+ * only prove that no write landed between those particular polls; a stalled
+ * writer can pause for longer than one interval and resume afterwards.
  *
  * @param {Object} options - Wait options
  * @param {string} options.path - Path the engine staged the download under
  * @param {number} [options.timeout] - Total budget in milliseconds
  * @param {number} [options.interval] - Milliseconds between readings
+ * @param {number} [options.stability] - Required unchanged-size quiet period
  * @param {string[]} [options.inProgressSuffixes] - Suffixes of a partial file
  * @returns {Promise<{ready: boolean, bytes: number|null, reason: string|null, waitedMs: number}>} Outcome
  */
@@ -93,11 +97,13 @@ export async function waitForStagedFile(options = {}) {
     path: filePath,
     timeout = DEFAULT_STAGING_TIMEOUT,
     interval = DEFAULT_STAGING_POLL_INTERVAL,
+    stability = DEFAULT_STAGING_STABILITY,
     inProgressSuffixes = STAGING_IN_PROGRESS_SUFFIXES,
   } = options;
 
   const deadline = createDeadline({ timeout });
   let previousSize;
+  let stableSince;
   // Always set by the reading below before the deadline can be checked.
   let reason;
 
@@ -107,15 +113,21 @@ export async function waitForStagedFile(options = {}) {
       reason = seen.reason;
       // A file that vanished has to prove itself stable again from scratch.
       previousSize = undefined;
+      stableSince = undefined;
     } else if (seen.size === previousSize) {
-      return {
-        ready: true,
-        bytes: seen.size,
-        reason: null,
-        waitedMs: deadline.elapsedMs(),
-      };
+      const stableMs = deadline.elapsedMs() - stableSince;
+      if (stableMs >= stability) {
+        return {
+          ready: true,
+          bytes: seen.size,
+          reason: null,
+          waitedMs: deadline.elapsedMs(),
+        };
+      }
+      reason = `the file had been unchanged for only ${stableMs}ms`;
     } else {
       previousSize = seen.size;
+      stableSince = deadline.elapsedMs();
       reason = `the file was still growing at ${seen.size} bytes`;
     }
 

package/src/traces/bundle.js

@@ -58,6 +58,7 @@ export async function openTraceBundle(options = {}) {
 
   const eventsPath = path.join(root, TRACE_FILES.EVENTS);
   const eventsHandle = await fs.open(eventsPath, 'a', TRACE_FILE_MODE);
+  let closeEventsPromise;
 
   let written = 0;
   let sequence = 0;
@@ -69,6 +70,12 @@ export async function openTraceBundle(options = {}) {
   const counts = { checkpoints: 0, events: 0, mutationBatches: 0 };
   const problems = [];
 
+  /** Close the timeline exactly once, after every queued append. */
+  function closeEvents() {
+    closeEventsPromise ??= appendQueue.then(() => eventsHandle.close());
+    return closeEventsPromise;
+  }
+
   const fits = (bytes) =>
     bytes <= maxResourceBytes && written + bytes <= maxBundleBytes;
 
@@ -308,6 +315,8 @@ export async function openTraceBundle(options = {}) {
     writeMutations,
     writeArtifact,
     drop,
+    /** Close an unfinished bundle without manufacturing a manifest. */
+    abort: closeEvents,
     /**
      * Write the manifest and close the timeline.
      *
@@ -325,8 +334,7 @@ export async function openTraceBundle(options = {}) {
             : manifest.outcome,
       };
       // Anything a listener reported on its way out is still queued.
-      await appendQueue;
-      await eventsHandle.close();
+      await closeEvents();
       await fs.writeFile(
         path.join(root, TRACE_FILES.MANIFEST),
         `${JSON.stringify(finished, null, 2)}\n`,

package/src/traces/recorder.js

@@ -74,6 +74,18 @@ function normalizeEvents(events) {
   return [...new Set(events)];
 }
 
+/**
+ * Reject a malformed side export before the bundle opens any file handles.
+ *
+ * @param {Object|null} links - Optional Links Notation export options
+ * @returns {void}
+ */
+function validateLinksOptions(links) {
+  if (links && (typeof links.output !== 'string' || links.output === '')) {
+    throw new Error('trace links require an output path');
+  }
+}
+
 /**
  * Start recording a session.
  *
@@ -111,6 +123,10 @@ export async function startTrace(options = {}) {
   }
   const eventSources = normalizeEvents(events);
   const privacyOptions = normalizePrivacyOptions(privacy);
+  // Validate the optional side export before opening the authoritative bundle.
+  // Otherwise a rejected start (for example `links: {}`) strands the bundle's
+  // events handle because no running trace is returned for the caller to stop.
+  validateLinksOptions(links);
   const engine = commander?.engine ?? null;
   const identity = createTraceIdentity({ page });
 
@@ -139,9 +155,6 @@ export async function startTrace(options = {}) {
   const startedAt = new Date(now()).toISOString();
 
   if (links) {
-    if (typeof links.output !== 'string' || links.output === '') {
-      throw new Error('trace links require an output path');
-    }
     linksSink = await openTraceLinks({
       output: links.output,
       include: links.include,

package/tests/e2e/downloads.e2e.test.js

@@ -17,8 +17,12 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-import { openBrowserCdpSession } from '../../src/downloads/sources.js';
-import { launchE2EBrowser } from '../helpers/e2e-browser.js';
+import {
+  browserContextIdForPage,
+  openBrowserCdpSession,
+} from '../../src/downloads/sources.js';
+import { makeBrowserCommander } from '../../src/factory.js';
+import { launchE2EBrowser, SANDBOX_ARGS } from '../helpers/e2e-browser.js';
 import {
   BLOB_PDF_BODY,
   PDF_BODY,
@@ -202,9 +206,16 @@ function describeDownloads(engine) {
       // than through the engine's download API. Issue #88 asks for "one
       // lifecycle for automated *and* manual downloads".
       const session = await openBrowserCdpSession({ engine, browser, page });
+      const browserContextId = await browserContextIdForPage({
+        engine,
+        browser,
+        page,
+        browserSession: session,
+      });
       const captured = downloads.capture({ timeout: 20000 });
       await session.send('Target.createTarget', {
         url: `${server.baseUrl}/file/manual.pdf`,
+        ...(browserContextId ? { browserContextId } : {}),
       });
 
       const artifact = await captured;
@@ -231,5 +242,71 @@ describe(
     for (const engine of ENGINES) {
       describeDownloads(engine);
     }
+
+    it('should persist a Blob from browser.newPage() (issue #97)', async () => {
+      const { chromium } = await import('playwright');
+      const directory = await fs.mkdtemp(
+        path.join(os.tmpdir(), 'bc-e2e-context-downloads-')
+      );
+      const browser = await chromium.launch({
+        headless: true,
+        args: SANDBOX_ARGS,
+      });
+      const page = await browser.newPage();
+      const commander = makeBrowserCommander({
+        page,
+        enableNetworkTracking: false,
+        enableNavigationManager: false,
+        enableDialogManager: false,
+      });
+
+      try {
+        const downloads = await commander.configureDownloads({
+          directory,
+          persist: true,
+        });
+        const completed = [];
+        downloads.on('completed', (artifact) => completed.push(artifact));
+        await page.setContent(`
+          <button id="download">Download</button>
+          <script>
+            document.querySelector('#download').addEventListener('click', () => {
+              const blob = new Blob([${JSON.stringify(BLOB_PDF_BODY)}], {
+                type: 'application/pdf',
+              });
+              const anchor = document.createElement('a');
+              anchor.href = URL.createObjectURL(blob);
+              anchor.download = 'declaration.pdf';
+              anchor.click();
+            });
+          </script>
+        `);
+
+        const artifact = await downloads.capture({
+          action: page.click.bind(page, '#download'),
+        });
+
+        assert.strictEqual(artifact.state, 'completed');
+        assert.strictEqual(path.basename(artifact.path), 'declaration.pdf');
+        assert.strictEqual(
+          await fs.readFile(artifact.path, 'utf8'),
+          BLOB_PDF_BODY
+        );
+        assert.strictEqual(completed.length, 1);
+        const staged = await fs.readdir(
+          path.join(directory, '.browser-commander-staging')
+        );
+        assert.deepStrictEqual(staged, []);
+        assert.ok(
+          !(await fs.readdir(directory)).some((entry) =>
+            entry.endsWith('.partial')
+          )
+        );
+      } finally {
+        await commander.destroy();
+        await browser.close();
+        await fs.rm(directory, { recursive: true, force: true });
+      }
+    });
   }
 );

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.
  *

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

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

@@ -5,6 +5,7 @@ import path from 'node:path';
 
 import {
   DEFAULT_STAGING_POLL_INTERVAL,
+  DEFAULT_STAGING_STABILITY,
   DEFAULT_STAGING_TIMEOUT,
   describeStagingTimeout,
   STAGING_IN_PROGRESS_SUFFIXES,
@@ -61,11 +62,31 @@ describe('waiting for staged bytes (issue #92)', () => {
     clearInterval(grow);
 
     assert.strictEqual(settled.ready, true, settled.reason ?? '');
-    // Two equal readings are what ends the wait, so the file had stopped
-    // growing before it was declared ready.
+    // 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');
@@ -111,6 +132,7 @@ describe('waiting for staged bytes (issue #92)', () => {
   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',

package/tests/unit/traces/bundle.test.js

@@ -16,10 +16,14 @@ import {
   TRACE_MODE,
   TRACE_OUTCOME,
 } from '../../../src/traces/schema.js';
-import { useTempTraceDirectory } from '../../helpers/trace-fixtures.js';
+import {
+  useTempTraceDirectory,
+  useTraceBundleCleanup,
+} from '../../helpers/trace-fixtures.js';
 
 describe('trace bundle writer (issue #87)', () => {
   const directory = useTempTraceDirectory();
+  const cleanup = useTraceBundleCleanup();
 
   /**
    * Open a bundle inside the suite's temporary directory.
@@ -27,8 +31,13 @@ describe('trace bundle writer (issue #87)', () => {
    * @param {Object} [options] - Options for `openTraceBundle`
    * @returns {Promise<Object>} The bundle writer
    */
-  const open = (options = {}) =>
-    openTraceBundle({ output: path.join(directory.path, 'run'), ...options });
+  const open = async (options = {}) =>
+    cleanup(
+      await openTraceBundle({
+        output: path.join(directory.path, 'run'),
+        ...options,
+      })
+    );
 
   /**
    * List a bundle's members, relative to its root.
@@ -66,6 +75,18 @@ describe('trace bundle writer (issue #87)', () => {
     await assert.rejects(openTraceBundle({}), /trace output must be a path/);
   });
 
+  it('should abort an unfinished bundle without writing a manifest', async () => {
+    const bundle = await open();
+    await bundle.appendEvent({ kind: TRACE_EVENT.CHECKPOINT });
+
+    await bundle.abort();
+    await bundle.abort();
+
+    await assert.rejects(
+      fs.access(path.join(bundle.root, TRACE_FILES.MANIFEST))
+    );
+  });
+
   it('should write the layout the format documents', async () => {
     const bundle = await open();
 

package/tests/unit/traces/links.test.js

@@ -27,6 +27,7 @@ import {
   createFakePage,
   makeSnapshot,
   useTempTraceDirectory,
+  useTraceBundleCleanup,
 } from '../../helpers/trace-fixtures.js';
 
 /**
@@ -66,6 +67,7 @@ function parseExport(text) {
 
 describe('trace links export (issue #94)', () => {
   const directory = useTempTraceDirectory();
+  const trackOpenBundle = useTraceBundleCleanup();
 
   /**
    * Write a bundle holding one of everything the export has to say.
@@ -76,6 +78,7 @@ describe('trace links export (issue #94)', () => {
   const writeBundle = async ({ close = true } = {}) => {
     const root = path.join(directory.path, 'run.bc-trace');
     const bundle = await openTraceBundle({ output: root });
+    trackOpenBundle(bundle);
     const owner = {
       traceId: 'trace-1',
       browserContextId: 'context-1',
@@ -457,6 +460,10 @@ describe('trace links export (issue #94)', () => {
     );
     // No closing link, which is how a reader tells this run never finished.
     assert.ok(!links.some((link) => link.id === 'result'));
+
+    // The assertions above model the process being killed. The test process
+    // itself survives, so release its open descriptor explicitly.
+    await trace.stop();
   });
 
   it('should take the export away with a discarded bundle', async () => {

package/tests/unit/traces/reader.test.js

@@ -16,10 +16,14 @@ import {
   TRACE_MODE,
   TRACE_OUTCOME,
 } from '../../../src/traces/schema.js';
-import { useTempTraceDirectory } from '../../helpers/trace-fixtures.js';
+import {
+  useTempTraceDirectory,
+  useTraceBundleCleanup,
+} from '../../helpers/trace-fixtures.js';
 
 describe('trace reader (issue #87)', () => {
   const directory = useTempTraceDirectory();
+  const cleanup = useTraceBundleCleanup();
 
   /**
    * Write a small bundle the tests can read back.
@@ -29,9 +33,11 @@ describe('trace reader (issue #87)', () => {
    * @returns {Promise<Object>} The bundle writer
    */
   const writeBundle = async ({ close = true } = {}) => {
-    const bundle = await openTraceBundle({
-      output: path.join(directory.path, 'run'),
-    });
+    const bundle = cleanup(
+      await openTraceBundle({
+        output: path.join(directory.path, 'run'),
+      })
+    );
     await bundle.appendEvent({
       kind: TRACE_EVENT.TRACE_START,
       mode: TRACE_MODE.CHECKPOINTS,

package/tests/unit/traces/recorder.test.js

@@ -172,6 +172,7 @@ describe('trace recorder (issue #87)', () => {
       await trace.checkpoint('start');
 
       assert.strictEqual(page.state.screenshots, 0);
+      await trace.stop();
     });
 
     it('should take a screenshot only on failure when asked', async () => {
@@ -182,6 +183,7 @@ describe('trace recorder (issue #87)', () => {
 
       await trace.checkpoint('the end', { reason: 'failure' });
       assert.strictEqual(page.state.screenshots, 1);
+      await trace.stop();
     });
 
     it('should keep a gap rather than fail when the page has closed', async () => {
@@ -237,6 +239,7 @@ describe('trace recorder (issue #87)', () => {
       // Once at the start, and once after each of the two checkpoints - the
       // base one the recorder takes itself and the one named above.
       assert.strictEqual(installs.length, 3);
+      await trace.stop();
     });
   });
 

package/tests/unit/traces/viewer.test.js

@@ -282,6 +282,10 @@ describe('offline trace viewer (issue #87)', () => {
 
       assert.match(body, /outcome truncated/);
       assert.match(body, /the last thing it did|1 checkpoints/);
+
+      // The assertions model an interrupted process; this test process keeps
+      // running, so explicitly release the descriptor afterwards.
+      await trace.stop();
     });
 
     it('should refuse a directory that is not a bundle', async () => {