browser-commander 0.17.2 → 0.19.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/
+      );
+    });
+  });
+});