browser-commander 0.17.1 → 0.18.0

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

@@ -0,0 +1,220 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  attachDownloads,
+  normalizeDownloadOptions,
+} from '../../../src/downloads/attach.js';
+import { connectBrowserWithDependencies } from '../../../src/browser/connector.js';
+import { makeBrowserCommander } from '../../../src/factory.js';
+import {
+  createFakeContext,
+  makeFakeDownload,
+  useTempDownloadDirectory,
+} from '../../helpers/download-fixtures.js';
+
+/**
+ * A page that belongs to the given context, as Playwright's page does.
+ *
+ * @param {Object} context - Fake browser context
+ * @returns {Object} Minimal page object
+ */
+function pageOf(context) {
+  return {
+    context: () => context,
+    // detectEngine() recognizes Playwright by locator() plus context().
+    locator: () => ({}),
+    on: () => {},
+    off: () => {},
+  };
+}
+
+/**
+ * Build a commander over a fake context, with only the download wiring on.
+ *
+ * @param {Object} context - Fake browser context
+ * @param {Object} [downloads] - A manager to expose as commander.downloads
+ * @returns {Object} Browser commander
+ */
+function commanderOver(context, downloads) {
+  return makeBrowserCommander({
+    page: pageOf(context),
+    enableNetworkTracking: false,
+    enableNavigationManager: false,
+    enableDialogManager: false,
+    downloads,
+  });
+}
+
+describe('download attachment (issue #88)', () => {
+  const directory = useTempDownloadDirectory();
+
+  describe('normalizeDownloadOptions', () => {
+    it('should treat an absent or disabled option as no manager', () => {
+      assert.strictEqual(normalizeDownloadOptions(undefined), null);
+      assert.strictEqual(normalizeDownloadOptions(false), null);
+      assert.strictEqual(normalizeDownloadOptions(null), null);
+    });
+
+    it('should read true as "manage downloads with the defaults"', () => {
+      assert.deepStrictEqual(normalizeDownloadOptions(true), {});
+    });
+
+    it('should pass an options object through untouched', () => {
+      const options = { directory: '/tmp/x', conflict: 'overwrite' };
+      assert.strictEqual(normalizeDownloadOptions(options), options);
+    });
+
+    it('should refuse a value that cannot describe a directory', () => {
+      assert.throws(
+        () => normalizeDownloadOptions('/tmp/downloads'),
+        /downloads must be true, false or an options object/
+      );
+    });
+  });
+
+  it('should attach nothing when the caller did not ask for downloads', () => {
+    assert.strictEqual(
+      attachDownloads({ engine: 'playwright', browser: createFakeContext() }),
+      null
+    );
+  });
+
+  it('should manage downloads from the context it was attached to', async () => {
+    const context = createFakeContext();
+    const manager = await attachDownloads({
+      engine: 'playwright',
+      browser: context,
+      downloads: { directory: directory.path },
+    });
+
+    await context.emitDownload(
+      await makeFakeDownload({
+        dir: directory.path,
+        suggestedFilename: 'a.txt',
+      })
+    );
+    await manager.idle();
+
+    assert.deepStrictEqual(
+      manager.list().map((artifact) => path.basename(artifact.path)),
+      ['a.txt']
+    );
+    await manager.dispose();
+  });
+
+  it('should give a connected browser the same lifecycle as a launched one', async () => {
+    // Issue #88 asks for one manager "identical across launchBrowser(),
+    // connectBrowser() and launchRealBrowser()", so the connector must return
+    // the same handle rather than leaving attached browsers unmanaged.
+    const context = createFakeContext();
+    const browser = { contexts: () => [context] };
+    context.pages = () => [pageOf(context)];
+
+    const connection = await connectBrowserWithDependencies(
+      {
+        engine: 'playwright',
+        cdpEndpoint: 'http://127.0.0.1:9222',
+        downloads: { directory: directory.path },
+      },
+      {
+        loadPlaywright: async () => ({
+          chromium: { connectOverCDP: async () => browser },
+        }),
+      }
+    );
+
+    assert.ok(connection.downloads, 'connectBrowser should return a manager');
+    assert.strictEqual(connection.downloads.directory, directory.path);
+
+    await context.emitDownload(
+      await makeFakeDownload({
+        dir: directory.path,
+        suggestedFilename: 'attached.txt',
+      })
+    );
+    await connection.downloads.idle();
+
+    assert.strictEqual(
+      await fs.readFile(path.join(directory.path, 'attached.txt'), 'utf8'),
+      'hello'
+    );
+    await connection.downloads.dispose();
+  });
+
+  it('should leave a connection unmanaged when downloads were not requested', async () => {
+    const context = createFakeContext();
+    context.pages = () => [pageOf(context)];
+
+    const connection = await connectBrowserWithDependencies(
+      { engine: 'playwright', cdpEndpoint: 'http://127.0.0.1:9222' },
+      {
+        loadPlaywright: async () => ({
+          chromium: {
+            connectOverCDP: async () => ({ contexts: () => [context] }),
+          },
+        }),
+      }
+    );
+
+    assert.strictEqual(connection.downloads, null);
+  });
+
+  describe('commander.configureDownloads', () => {
+    it('should expose a manager the caller already has', () => {
+      const context = createFakeContext();
+      const manager = { directory: directory.path };
+      const commander = commanderOver(context, manager);
+
+      assert.strictEqual(commander.downloads, manager);
+    });
+
+    it('should attach a manager to a commander built without one', async () => {
+      const context = createFakeContext();
+      const commander = commanderOver(context);
+      assert.strictEqual(commander.downloads, null);
+
+      const manager = await commander.configureDownloads({
+        directory: directory.path,
+      });
+
+      assert.strictEqual(commander.downloads, manager);
+      await context.emitDownload(
+        await makeFakeDownload({
+          dir: directory.path,
+          suggestedFilename: 'configured.txt',
+        })
+      );
+      await manager.idle();
+
+      assert.strictEqual(
+        path.basename(manager.list()[0].path),
+        'configured.txt'
+      );
+      await manager.dispose();
+    });
+
+    it('should keep downloaded files when the commander is destroyed', async () => {
+      // Persistence is the point: destroying the commander stops observation,
+      // it does not take the user's file away.
+      const context = createFakeContext();
+      const commander = commanderOver(context);
+      await commander.configureDownloads({ directory: directory.path });
+
+      await context.emitDownload(
+        await makeFakeDownload({
+          dir: directory.path,
+          suggestedFilename: 'kept.txt',
+        })
+      );
+      await commander.destroy();
+
+      assert.strictEqual(
+        await fs.readFile(path.join(directory.path, 'kept.txt'), 'utf8'),
+        'hello'
+      );
+    });
+  });
+});

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

@@ -0,0 +1,114 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  ARTIFACT_DIRECTORY_MODE,
+  prepareDownloadDirectory,
+  resolveDownloadDirectory,
+} from '../../../src/downloads/destination.js';
+import { useTempDownloadDirectory } from '../../helpers/download-fixtures.js';
+import { assertMode, HAS_POSIX_MODES } from '../../helpers/file-modes.js';
+
+describe('download destination (issue #88)', () => {
+  const directory = useTempDownloadDirectory();
+
+  describe('resolveDownloadDirectory', () => {
+    it('should resolve the temporary preset under the system temp directory', async () => {
+      const resolved = await resolveDownloadDirectory('temporary');
+
+      assert.strictEqual(
+        resolved,
+        path.join(os.tmpdir(), 'browser-commander-downloads')
+      );
+    });
+
+    it('should resolve the user preset to an absolute path', async () => {
+      const resolved = await resolveDownloadDirectory('user-downloads');
+
+      assert.ok(path.isAbsolute(resolved));
+    });
+
+    it('should default to the user preset', async () => {
+      assert.strictEqual(
+        await resolveDownloadDirectory(),
+        await resolveDownloadDirectory('user-downloads')
+      );
+    });
+
+    it('should accept an absolute custom path', async () => {
+      assert.strictEqual(
+        await resolveDownloadDirectory(directory.path),
+        directory.path
+      );
+    });
+
+    it('should refuse a relative path rather than guess a base for it', async () => {
+      await assert.rejects(
+        resolveDownloadDirectory('./downloads'),
+        /must be absolute/
+      );
+    });
+
+    it('should refuse a setting that is neither a path nor a preset', async () => {
+      await assert.rejects(resolveDownloadDirectory(42), TypeError);
+      await assert.rejects(resolveDownloadDirectory(''), TypeError);
+    });
+  });
+
+  describe('prepareDownloadDirectory', () => {
+    it('should create the directory owner-only before any download runs', async () => {
+      const nested = path.join(directory.path, 'deep', 'downloads');
+
+      assert.strictEqual(await prepareDownloadDirectory(nested), nested);
+
+      const stat = await fs.stat(nested);
+      assert.ok(stat.isDirectory());
+      await assertMode(nested, ARTIFACT_DIRECTORY_MODE);
+    });
+
+    it('should leave no probe file behind', async () => {
+      await prepareDownloadDirectory(directory.path);
+
+      assert.deepStrictEqual(await fs.readdir(directory.path), []);
+    });
+
+    it(
+      'should report an unwritable directory before the first download',
+      {
+        // Root may write into any directory, so the mode bits prove nothing
+        // there - and on Windows there are no mode bits to take away, since
+        // `chmod` only toggles a read-only flag that directories ignore.
+        skip:
+          (process.getuid?.() === 0 && 'running as root') ||
+          (!HAS_POSIX_MODES && 'Windows has no directory mode bits'),
+      },
+      async () => {
+        // Issue #88: the failure has to surface at configuration time, because a
+        // permission error discovered after a click looks like a missing file.
+        const readOnly = path.join(directory.path, 'read-only');
+        await fs.mkdir(readOnly);
+        await fs.chmod(readOnly, 0o500);
+
+        await assert.rejects(
+          prepareDownloadDirectory(readOnly),
+          /is not writable/
+        );
+
+        await fs.chmod(readOnly, 0o700);
+      }
+    );
+
+    it('should report a directory it cannot create', async () => {
+      const blocker = path.join(directory.path, 'blocker');
+      await fs.writeFile(blocker, 'not a directory');
+
+      await assert.rejects(
+        prepareDownloadDirectory(path.join(blocker, 'downloads')),
+        /could not be created/
+      );
+    });
+  });
+});

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

@@ -0,0 +1,354 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { setImmediate as yieldToEngine } from 'node:timers/promises';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  createDownloadManager,
+  DOWNLOAD_EVENT,
+} from '../../../src/downloads/manager.js';
+import { STAGING_DIRECTORY } from '../../../src/downloads/sources.js';
+import {
+  createFakeCdpSession,
+  createFakeContext,
+  makeFakeDownload,
+  makeTempDirectory,
+} from '../../helpers/download-fixtures.js';
+
+describe('download manager (issue #88)', () => {
+  let root;
+  let staging;
+  let context;
+  let manager;
+
+  beforeEach(async () => {
+    root = await makeTempDirectory();
+    staging = await makeTempDirectory();
+    context = createFakeContext();
+  });
+
+  afterEach(async () => {
+    await manager?.dispose();
+    manager = undefined;
+    await fs.rm(root, { recursive: true, force: true });
+    await fs.rm(staging, { recursive: true, force: true });
+  });
+
+  /**
+   * Start a manager over the fake Playwright context.
+   *
+   * @param {Object} [options] - Extra manager options
+   * @returns {Promise<Object>} The manager
+   */
+  const managerOver = async (options = {}) => {
+    manager = await createDownloadManager({
+      engine: 'playwright',
+      context,
+      directory: root,
+      ...options,
+    });
+    return manager;
+  };
+
+  /**
+   * Emit a fake download through the context.
+   *
+   * @param {Object} [options] - Fake download options
+   * @returns {Promise<Object>} The fake download
+   */
+  const emitDownload = async (options = {}) => {
+    const download = await makeFakeDownload({
+      dir: staging,
+      suggestedFilename: 'report.pdf',
+      ...options,
+    });
+    await context.emitDownload(download);
+    // Engine download events are fire-and-forget; the save they start is not.
+    await manager.idle();
+    return download;
+  };
+
+  /**
+   * Record every artifact published under one lifecycle event.
+   *
+   * @param {string} event - Lifecycle event to listen for
+   * @returns {Object[]} Artifacts, in the order they were published
+   */
+  const collect = (event) => {
+    const published = [];
+    manager.on(event, (artifact) => published.push(artifact));
+    return published;
+  };
+
+  /**
+   * List the managed directory, ignoring engine staging.
+   *
+   * @returns {Promise<string[]>} Sorted entry names
+   */
+  const listing = async () =>
+    (await fs.readdir(root)).filter((e) => e !== STAGING_DIRECTORY).sort();
+
+  it('should prepare the download directory before any download arrives', async () => {
+    const created = path.join(root, 'nested');
+
+    await managerOver({ directory: created });
+
+    assert.strictEqual(manager.directory, created);
+    assert.ok((await fs.stat(created)).isDirectory());
+  });
+
+  it('should save a download and report it as completed', async () => {
+    await managerOver();
+    const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+
+    await emitDownload({ body: 'report body' });
+
+    assert.strictEqual(completed.length, 1);
+    assert.strictEqual(completed[0].state, DOWNLOAD_EVENT.COMPLETED);
+    assert.strictEqual(path.basename(completed[0].path), 'report.pdf');
+    assert.strictEqual(completed[0].bytes, 11);
+    assert.match(completed[0].checksum, /^[0-9a-f]{64}$/);
+    assert.ok(completed[0].id.startsWith('dl-'));
+    assert.ok(completed[0].completedAt);
+    assert.strictEqual(
+      await fs.readFile(completed[0].path, 'utf8'),
+      'report body'
+    );
+  });
+
+  it('should keep the file after the browser that produced it is gone', async () => {
+    await managerOver();
+    await emitDownload({ body: 'persisted' });
+    const [artifact] = manager.list();
+
+    await manager.dispose();
+    manager = undefined;
+
+    assert.strictEqual(await fs.readFile(artifact.path, 'utf8'), 'persisted');
+  });
+
+  it('should report an engine failure with the engine reason preserved', async () => {
+    await managerOver();
+    const failed = collect(DOWNLOAD_EVENT.FAILED);
+
+    await emitDownload({ failure: 'net::ERR_CONNECTION_RESET' });
+
+    assert.strictEqual(failed.length, 1);
+    assert.strictEqual(failed[0].failure, 'net::ERR_CONNECTION_RESET');
+    assert.strictEqual(failed[0].path, null);
+    assert.deepStrictEqual(await listing(), []);
+  });
+
+  it('should report a cancelled download as cancelled, not as a failure', async () => {
+    await managerOver();
+    const events = [];
+    manager.on(DOWNLOAD_EVENT.CANCELLED, () => events.push('cancelled'));
+    manager.on(DOWNLOAD_EVENT.FAILED, () => events.push('failed'));
+
+    await emitDownload({ failure: 'canceled' });
+
+    assert.deepStrictEqual(events, ['cancelled']);
+  });
+
+  it('should report each download once when a listener and a capture both watch', async () => {
+    // Issue #88: "a download that a global listener and an awaited capture()
+    // both see must be saved once and reported once".
+    await managerOver();
+    const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+
+    const captured = await manager.capture({
+      action: () => emitDownload({ body: 'once' }),
+    });
+
+    assert.strictEqual(completed.length, 1);
+    assert.strictEqual(completed[0], captured);
+    assert.strictEqual(manager.list().length, 1);
+    assert.deepStrictEqual(await listing(), ['report.pdf']);
+  });
+
+  it('should catch a download that starts inside the triggering action', async () => {
+    // Arming after the action would lose this one: the race the issue calls out.
+    await managerOver();
+
+    const artifact = await manager.capture({
+      action: () => emitDownload({ body: 'raced' }),
+    });
+
+    assert.strictEqual(artifact.state, DOWNLOAD_EVENT.COMPLETED);
+  });
+
+  it('should name a captured download without losing the safety rules', async () => {
+    await managerOver();
+
+    const artifact = await manager.capture({
+      action: () =>
+        emitDownload({
+          suggestedFilename: '8d0f9e2c-4a11-4b22-9f00-1d2e3f405162',
+          body: '%PDF-1.7 invoice',
+        }),
+      filename: () => '../invoice.pdf',
+    });
+
+    assert.strictEqual(artifact.path, path.join(root, 'invoice.pdf'));
+  });
+
+  it('should fail a capture whose download does not validate', async () => {
+    await managerOver();
+
+    await assert.rejects(
+      manager.capture({
+        action: () => emitDownload({ body: '<html>login</html>' }),
+        validate: ({ bytes }) => {
+          if (bytes < 1000) {
+            throw new Error('expected a PDF, got a login page');
+          }
+        },
+      }),
+      /failed: expected a PDF/
+    );
+
+    assert.deepStrictEqual(await listing(), []);
+  });
+
+  it('should time out rather than wait forever for a download that never starts', async () => {
+    await managerOver();
+
+    await assert.rejects(
+      manager.capture({ action: () => {}, timeout: 50 }),
+      /no download completed within 50ms/
+    );
+  });
+
+  it('should propagate an error from the triggering action', async () => {
+    await managerOver();
+
+    await assert.rejects(
+      manager.capture({
+        action: () => {
+          throw new Error('the button was not there');
+        },
+      }),
+      /the button was not there/
+    );
+  });
+
+  it('should resolve a name collision without replacing the earlier file', async () => {
+    await managerOver();
+
+    await emitDownload({ body: 'first' });
+    await emitDownload({ body: 'second' });
+
+    assert.deepStrictEqual(await listing(), ['report (2).pdf', 'report.pdf']);
+    assert.strictEqual(manager.list().length, 2);
+  });
+
+  it('should list every download in the order it started', async () => {
+    await managerOver();
+
+    await emitDownload({ suggestedFilename: 'a.txt' });
+    await emitDownload({ suggestedFilename: 'b.txt' });
+
+    assert.deepStrictEqual(
+      manager.list().map((artifact) => artifact.suggestedFilename),
+      ['a.txt', 'b.txt']
+    );
+  });
+
+  describe('manual downloads over CDP', () => {
+    /**
+     * Start a manager whose only source is a fake CDP session.
+     *
+     * @param {Object} session - Fake CDP session
+     * @returns {Promise<Object>} The manager
+     */
+    const cdpManagerOver = async (session) =>
+      createDownloadManager({
+        engine: 'puppeteer',
+        directory: root,
+        browser: {
+          target: () => ({ createCDPSession: async () => session }),
+        },
+      });
+
+    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,
+          },
+        },
+      ]);
+    });
+
+    it('should place a manually started download like an automated one', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+      const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+
+      const guid = 'guid-0001';
+      session.emit('Browser.downloadWillBegin', {
+        guid,
+        url: 'https://example.com/manual.pdf',
+        suggestedFilename: 'manual.pdf',
+      });
+      await fs.writeFile(
+        path.join(root, STAGING_DIRECTORY, guid),
+        'manual body'
+      );
+      session.emit('Browser.downloadProgress', { guid, state: 'completed' });
+      await manager.idle();
+
+      assert.strictEqual(completed.length, 1);
+      assert.strictEqual(completed[0].path, path.join(root, 'manual.pdf'));
+      assert.strictEqual(
+        await fs.readFile(completed[0].path, 'utf8'),
+        'manual body'
+      );
+      // The staged copy is the engine's, not the user's: it does not linger.
+      assert.deepStrictEqual(
+        await fs.readdir(path.join(root, STAGING_DIRECTORY)),
+        []
+      );
+    });
+
+    it('should report a download the browser refused', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+      const cancelled = collect(DOWNLOAD_EVENT.CANCELLED);
+
+      session.emit('Browser.downloadWillBegin', {
+        guid: 'guid-0002',
+        url: 'https://example.com/blocked.exe',
+        suggestedFilename: 'blocked.exe',
+      });
+      session.emit('Browser.downloadProgress', {
+        guid: 'guid-0002',
+        state: 'canceled',
+      });
+      await yieldToEngine();
+
+      assert.strictEqual(cancelled.length, 1);
+      assert.match(cancelled[0].failure, /canceled/);
+    });
+
+    it('should ignore progress for a download it never saw start', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+
+      session.emit('Browser.downloadProgress', {
+        guid: 'unknown',
+        state: 'completed',
+      });
+      await yieldToEngine();
+
+      assert.deepStrictEqual(manager.list(), []);
+    });
+  });
+});