browser-commander 0.17.2 → 0.18.0

package/tests/e2e/click-readiness.e2e.test.js

@@ -0,0 +1,240 @@
+/**
+ * Real-browser tests for issue #89.
+ *
+ * The three repros in that issue are all about claims the library made
+ * without checking: a page reported ready after the wait failed, a no-op
+ * button reported as verified, and `noAutoScroll` scrolling the page anyway.
+ * Only a real browser can disprove the last one, so these run against
+ * Chromium and a local fixture server.
+ *
+ * Run with: npm run test:e2e:click-readiness
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+
+import { startFixtureServer } from '../helpers/readiness-server.js';
+
+const VIEWPORT = { width: 800, height: 600 };
+
+describe(
+  'E2E - truthful readiness and click results (issue #89)',
+  { skip: !process.env.RUN_E2E, timeout: 120000 },
+  () => {
+    let browser;
+    let context;
+    let page;
+    let commander;
+    let server;
+
+    before(async () => {
+      const { chromium } = await import('playwright');
+      const { createCommander } = await import('../../src/index.js');
+
+      server = await startFixtureServer();
+      browser = await chromium.launch({
+        headless: process.env.HEADLESS !== 'false',
+      });
+      context = await browser.newContext({ viewport: VIEWPORT });
+      page = await context.newPage();
+      commander = createCommander({ page, engine: 'playwright' });
+    });
+
+    after(async () => {
+      await browser?.close();
+      await server?.close();
+    });
+
+    /** Load a fixture page and reset the scroll position. */
+    const open = async (path) => {
+      await page.goto(`${server.baseUrl}${path}`, {
+        waitUntil: 'domcontentloaded',
+      });
+      await page.evaluate(() => window.scrollTo(0, 0));
+    };
+
+    const scrollY = () => page.evaluate(() => window.scrollY);
+    const clicks = () => page.evaluate(() => window.__clicks);
+
+    /**
+     * Open a fixture page and click one of its elements.
+     *
+     * @param {string} path - Fixture page path
+     * @param {string} selector - Element to click
+     * @param {Object} options - Click options passed straight through
+     * @returns {Promise<Object>} Click result
+     */
+    const clickOn = async (path, selector, options) => {
+      await open(path);
+      return commander.clickElement({
+        locatorOrElement: page.locator(selector),
+        ...options,
+      });
+    };
+
+    /**
+     * Wait for readiness and report how long the wait actually took.
+     *
+     * @param {Object} options - Options for `waitForReady`
+     * @returns {Promise<{result: Object, elapsed: number}>} Outcome and duration
+     */
+    const timeReadiness = async (options) => {
+      const started = Date.now();
+      const result = await commander.waitForReady(options);
+      return { result, elapsed: Date.now() - started };
+    };
+
+    describe("scroll: 'none'", () => {
+      it('does not scroll the page when the target is already visible', async () => {
+        await open('/far-below-fold');
+        // Put the target on screen without the click doing it for us.
+        await page.evaluate(() =>
+          document.getElementById('target').scrollIntoView({ block: 'center' })
+        );
+        const before = await scrollY();
+
+        const result = await commander.clickElement({
+          locatorOrElement: page.locator('#target'),
+          scroll: 'none',
+          verify: false,
+        });
+
+        assert.strictEqual(result.dispatched, true, result.reason);
+        assert.strictEqual(await clicks(), 1);
+        assert.strictEqual(
+          await scrollY(),
+          before,
+          'scroll: none must not move the page'
+        );
+      });
+
+      it('fails clearly instead of scrolling to an off-screen target', async () => {
+        // Regression test for issue #89 repro 3: this used to map to
+        // Playwright's `force: true`, which skips actionability checks but
+        // still scrolls, so the reported "no scroll" click scrolled to 3911.
+        const result = await clickOn('/far-below-fold', '#target', {
+          scroll: 'none',
+          verify: false,
+        });
+
+        assert.strictEqual(result.status, 'failed');
+        assert.strictEqual(result.dispatched, false);
+        assert.match(result.reason, /viewport|obscure/i);
+        assert.strictEqual(await scrollY(), 0, 'the page must not have moved');
+        assert.strictEqual(await clicks(), 0);
+      });
+
+      it('treats the legacy noAutoScroll flag the same way', async () => {
+        const result = await clickOn('/far-below-fold', '#target', {
+          noAutoScroll: true,
+          verify: false,
+        });
+
+        assert.strictEqual(result.dispatched, false);
+        assert.strictEqual(await scrollY(), 0);
+      });
+
+      it("scroll: 'auto' still scrolls, as it always did", async () => {
+        const result = await clickOn('/far-below-fold', '#target', {
+          scroll: 'auto',
+          verify: false,
+        });
+
+        assert.strictEqual(result.dispatched, true, result.reason);
+        assert.ok((await scrollY()) > 0, 'scroll: auto is allowed to scroll');
+        assert.strictEqual(await clicks(), 1);
+      });
+
+      it("scroll: 'preserve' restores the position it started from", async () => {
+        await clickOn('/far-below-fold', '#target', {
+          scroll: 'preserve',
+          verify: false,
+        });
+
+        assert.strictEqual(await clicks(), 1);
+        assert.strictEqual(await scrollY(), 0);
+      });
+    });
+
+    describe('click verification', () => {
+      it('reports unverified for a button that does nothing', async () => {
+        // Regression test for issue #89 repro 2: "element still connected"
+        // used to be reported as `verified: true`.
+        const result = await clickOn('/no-op', '#noop', { verify: true });
+
+        assert.strictEqual(await clicks(), 1, 'the click must still happen');
+        assert.strictEqual(result.dispatched, true);
+        assert.strictEqual(result.status, 'unverified');
+        assert.strictEqual(result.effect, 'not-observed');
+        assert.strictEqual(result.verified, false);
+        assert.ok(result.evidence.length > 0, 'a verdict needs evidence');
+      });
+
+      it('confirms a click that actually changed the element', async () => {
+        const result = await clickOn('/far-below-fold', '#target', {
+          scroll: 'auto',
+          verify: true,
+        });
+
+        assert.strictEqual(result.status, 'succeeded');
+        assert.strictEqual(result.effect, 'confirmed');
+        assert.strictEqual(result.verified, true);
+      });
+
+      it('carries an action id and an elapsed time on every result', async () => {
+        const result = await clickOn('/no-op', '#noop', { verify: true });
+
+        assert.strictEqual(typeof result.actionId, 'string');
+        assert.ok(result.actionId.length > 0);
+        assert.ok(Number.isFinite(result.elapsedMs));
+      });
+
+      it('does not claim a navigating click was verified by the navigation', async () => {
+        const result = await clickOn('/navigates', '#go', { verify: true });
+
+        await page.waitForSelector('#arrived');
+        // The click did navigate, but nothing proved the click caused it, so
+        // the result must not be dressed up as a confirmed effect.
+        assert.notStrictEqual(result.effect, 'confirmed');
+        assert.ok(
+          ['unverified', 'interrupted', 'succeeded'].includes(result.status),
+          `unexpected status ${result.status}`
+        );
+        assert.strictEqual(typeof result.actionId, 'string');
+      });
+    });
+
+    describe('readiness deadlines', () => {
+      it('reports timed_out instead of ready when the network never settles', async () => {
+        // Regression test for issue #89 repro 1: the wait failed and the page
+        // was announced as ready anyway.
+        await open('/never-idle');
+
+        const { result, elapsed } = await timeReadiness({
+          timeout: 1500,
+          reason: 'e2e deadline check',
+        });
+
+        assert.strictEqual(result.ready, false);
+        assert.strictEqual(result.status, 'timed_out');
+        assert.ok(
+          elapsed < 6000,
+          `the wait took ${elapsed}ms for a 1500ms budget`
+        );
+        assert.ok(result.evidence.length > 0);
+      });
+
+      it('never spends more than the budget it was given', async () => {
+        await open('/never-idle');
+
+        const { result, elapsed } = await timeReadiness({ timeout: 200 });
+
+        assert.strictEqual(result.ready, false);
+        assert.ok(
+          elapsed < 3000,
+          `a 200ms budget must not become ${elapsed}ms`
+        );
+      });
+    });
+  }
+);

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

@@ -0,0 +1,188 @@
+/**
+ * Real-browser tests for issue #88.
+ *
+ * The managed lifecycle only means something against a real engine: a browser
+ * decides for itself when a download starts, where it stages the bytes and
+ * whether a transfer failed. These tests run the same expectations against
+ * both engines, because the issue asks for a manager that behaves identically
+ * whichever one is driving.
+ *
+ * Run with: npm run test:e2e:downloads
+ */
+
+import { describe, it, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert';
+import { createHash } from 'node:crypto';
+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 {
+  PDF_BODY,
+  REPORT_BODY,
+  startDownloadServer,
+} from '../helpers/download-server.js';
+
+const ENGINES = ['playwright', 'puppeteer'];
+
+/**
+ * Run the managed-download expectations against one engine.
+ *
+ * @param {string} engine - 'playwright' or 'puppeteer'
+ * @returns {void}
+ */
+function describeDownloads(engine) {
+  describe(`E2E - managed downloads with ${engine} (issue #88)`, () => {
+    let server;
+    let browser;
+    let page;
+    let downloads;
+    let directory;
+    let cleanup;
+
+    before(async () => {
+      server = await startDownloadServer();
+      directory = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-e2e-downloads-'));
+      ({ browser, page, downloads, cleanup } = await launchE2EBrowser({
+        engine,
+        downloadDirectory: directory,
+      }));
+    });
+
+    // A download the browser decides to display instead - a PDF it can render -
+    // leaves the page somewhere else, so every test starts from the fixture.
+    beforeEach(async () => {
+      await page.goto(`${server.baseUrl}/`);
+    });
+
+    after(async () => {
+      await downloads?.dispose();
+      await cleanup?.();
+      await server?.close();
+      await fs.rm(directory, { recursive: true, force: true });
+    });
+
+    /**
+     * Click an element and wait for the download it triggers.
+     *
+     * @param {string} selector - Element to click
+     * @param {Object} [options] - Capture options
+     * @returns {Promise<Object>} The settled artifact
+     */
+    const captureClickOn = async (selector, options = {}) =>
+      downloads.capture({
+        action: () => page.click(selector),
+        timeout: 20000,
+        ...options,
+      });
+
+    it('should save a file the browser downloaded from a click', async () => {
+      const artifact = await captureClickOn('#link');
+
+      assert.strictEqual(artifact.state, 'completed');
+      assert.strictEqual(path.basename(artifact.path), 'report.pdf');
+      assert.strictEqual(await fs.readFile(artifact.path, 'utf8'), REPORT_BODY);
+      assert.strictEqual(
+        artifact.checksum,
+        createHash('sha256').update(REPORT_BODY).digest('hex')
+      );
+      assert.strictEqual(artifact.bytes, Buffer.byteLength(REPORT_BODY));
+    });
+
+    it('should save a file the page built from a blob', async () => {
+      const artifact = await captureClickOn('#blob');
+
+      assert.strictEqual(path.basename(artifact.path), 'generated.txt');
+      assert.strictEqual(await fs.readFile(artifact.path, 'utf8'), REPORT_BODY);
+    });
+
+    it('should save a navigation that turned into a download', async () => {
+      const artifact = await captureClickOn('#navigating');
+
+      assert.strictEqual(artifact.state, 'completed');
+      assert.strictEqual(path.basename(artifact.path), 'statement.pdf');
+    });
+
+    it('should give an unnamed download an extension from its bytes', async () => {
+      const artifact = await captureClickOn('#unnamed');
+
+      assert.ok(
+        artifact.path.endsWith('.pdf'),
+        `expected a .pdf suffix, got ${artifact.path}`
+      );
+      assert.strictEqual(await fs.readFile(artifact.path, 'utf8'), PDF_BODY);
+    });
+
+    it('should let the caller name a download as it is captured', async () => {
+      const artifact = await captureClickOn('#link', {
+        filename: 'named-by-the-caller.pdf',
+      });
+
+      assert.strictEqual(
+        path.basename(artifact.path),
+        'named-by-the-caller.pdf'
+      );
+    });
+
+    it('should report a transfer the server aborted, with no file left behind', async () => {
+      const failures = [];
+      downloads.on('failed', (artifact) => failures.push(artifact));
+      downloads.on('cancelled', (artifact) => failures.push(artifact));
+
+      // A download that never produced bytes is not a result: the awaited
+      // capture fails with the engine's own words, because "a download UI
+      // entry is not completion evidence" (issue #88).
+      await assert.rejects(captureClickOn('#broken'), /dl-\d+/);
+
+      assert.strictEqual(failures.length, 1);
+      assert.ok(failures[0].failure, 'the engine reason should be preserved');
+      const entries = await fs.readdir(directory);
+      assert.ok(
+        !entries.includes('broken.pdf'),
+        `a failed download must not appear under its final name: ${entries}`
+      );
+      assert.ok(
+        !entries.some((entry) => entry.endsWith('.partial')),
+        `no partial file should be left behind: ${entries}`
+      );
+    });
+
+    it('should manage a download the automation never started', async () => {
+      // The closest a test can get to a person downloading a file: a target
+      // the automation did not create, downloading through the browser rather
+      // 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 captured = downloads.capture({ timeout: 20000 });
+      await session.send('Target.createTarget', {
+        url: `${server.baseUrl}/file/manual.pdf`,
+      });
+
+      const artifact = await captured;
+      assert.strictEqual(path.basename(artifact.path), 'manual.pdf');
+      assert.strictEqual(await fs.readFile(artifact.path, 'utf8'), REPORT_BODY);
+    });
+
+    it('should keep every saved file after the browser closes', async () => {
+      const before = (await fs.readdir(directory)).sort();
+      await downloads.dispose();
+      await browser.close();
+      browser = undefined;
+
+      assert.deepStrictEqual((await fs.readdir(directory)).sort(), before);
+      assert.ok(before.length >= 5, `expected saved files, got ${before}`);
+    });
+  });
+}
+
+describe(
+  'E2E - managed downloads (issue #88)',
+  { skip: !process.env.RUN_E2E, timeout: 180000 },
+  () => {
+    for (const engine of ENGINES) {
+      describeDownloads(engine);
+    }
+  }
+);