@harnessed-ts/puppeteer 0.0.0-stage → 0.7.0

package/dist/index.cjs

@@ -0,0 +1,598 @@
+'use strict';
+
+var core = require('@harnessed-ts/core');
+var inject = require('@harnessed-ts/resolve/inject');
+
+// src/driver-id.ts
+var PUPPETEER_DRIVER = "puppeteer";
+var FrameEntryError = class extends Error {
+  name = "FrameEntryError";
+};
+var POLL_MS = 50;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function apiOptions(timeout) {
+  return { testIdAttribute: core.getConfig().testIdAttribute, timeout };
+}
+function isMissingApi(error) {
+  return error instanceof Error && error.message.includes(`${inject.PAGE_API_GLOBAL} is not installed`);
+}
+var NAVIGATION_ERRORS = [
+  "Execution context was destroyed",
+  "Cannot find context with specified id",
+  "Execution context is not available in detached frame",
+  "Attempted to use detached Frame"
+];
+function isNavigationError(error) {
+  return error instanceof Error && NAVIGATION_ERRORS.some((message) => error.message.includes(message));
+}
+function isNotFound(error) {
+  return error instanceof Error && error.message.startsWith("Unable to find");
+}
+function isAbsence(error) {
+  return isNotFound(error) || error instanceof Error && /^harnessed: index \d+ is out of range/.test(error.message);
+}
+function isResolverOutcome(error) {
+  if (error instanceof FrameEntryError) return false;
+  return isNotFound(error) || error instanceof Error && error.message.startsWith("harnessed: ");
+}
+async function withApi(frame, timeout, call) {
+  const deadline = Date.now() + core.timeoutFor(timeout);
+  let injected = false;
+  for (; ; ) {
+    try {
+      return await call(apiOptions(Math.max(0, deadline - Date.now())));
+    } catch (error) {
+      const expired = Date.now() >= deadline;
+      if (isMissingApi(error) && !(expired && injected)) {
+        injected = true;
+        try {
+          await frame.evaluate(inject.injectSource());
+        } catch (injectError) {
+          if (!isNavigationError(injectError) || frame.detached) throw injectError;
+        }
+        continue;
+      }
+      if (!isNavigationError(error) || frame.detached || expired) throw error;
+      await sleep(POLL_MS);
+    }
+  }
+}
+function restate(error, prefix, scope, selector) {
+  if (prefix.length === 0 || !(error instanceof Error)) return error;
+  if (!error.message.startsWith("harnessed: ")) return error;
+  const head = scope[0] ?? selector;
+  const restated = core.describeScope(prefix, head);
+  error.message = error.message.replace(core.describeSelector(head), () => restated);
+  return error;
+}
+function pageOne(name, method, scope, selector, options) {
+  const api = globalThis[name];
+  if (api === void 0) throw new Error(`${name} is not installed`);
+  return api[method](null, scope, selector, options);
+}
+function pageCount(name, scope, selector, options) {
+  const api = globalThis[name];
+  if (api === void 0) throw new Error(`${name} is not installed`);
+  return api.count(null, scope, selector, options);
+}
+function pageVisible(element, name) {
+  const api = globalThis[name];
+  if (api === void 0) throw new Error(`${name} is not installed`);
+  return api.visible(element);
+}
+function pageFileTarget(element, name) {
+  const api = globalThis[name];
+  if (api === void 0) throw new Error(`${name} is not installed`);
+  return api.fileTarget(element);
+}
+async function fileTargetOf(element) {
+  return element.evaluate(pageFileTarget, inject.PAGE_API_GLOBAL);
+}
+async function visibleInOwnDocument(element) {
+  return element.evaluate(pageVisible, inject.PAGE_API_GLOBAL);
+}
+async function oneIn(frame, prefix, scope, selector, lookup, timeout) {
+  const method = lookup === "wait" ? "one" : "oneNow";
+  let handle;
+  try {
+    handle = await withApi(
+      frame,
+      timeout,
+      (options) => frame.evaluateHandle(
+        pageOne,
+        inject.PAGE_API_GLOBAL,
+        method,
+        scope.map(inject.encodeSelector),
+        inject.encodeSelector(selector),
+        options
+      )
+    );
+  } catch (error) {
+    throw restate(core.reviveStrictViolation(error), prefix, scope, selector);
+  }
+  const element = handle.asElement();
+  if (element === null) await handle.dispose();
+  return element;
+}
+async function countIn(frame, prefix, scope, selector, timeout) {
+  try {
+    return await withApi(
+      frame,
+      timeout,
+      (options) => frame.evaluate(
+        pageCount,
+        inject.PAGE_API_GLOBAL,
+        scope.map(inject.encodeSelector),
+        inject.encodeSelector(selector),
+        options
+      )
+    );
+  } catch (error) {
+    throw restate(core.reviveStrictViolation(error), prefix, scope, selector);
+  }
+}
+async function enterFrames(page, scope, lookup, timeout) {
+  let frame = page.mainFrame();
+  let start = 0;
+  const hosts = [];
+  try {
+    for (const [index, link] of scope.entries()) {
+      if (link.frame !== true) continue;
+      const path = scope.slice(0, index);
+      const host = await oneIn(
+        frame,
+        scope.slice(0, start),
+        scope.slice(start, index),
+        link,
+        lookup,
+        timeout
+      );
+      if (host === null) {
+        await disposeAll(hosts);
+        return null;
+      }
+      hosts.push(host);
+      const tag = await host.evaluate((element) => element.localName);
+      if (tag !== "iframe") {
+        throw new FrameEntryError(
+          `harnessed: ${core.describeScope(path, link)} is marked as a frame but is a <${tag}>, not an <iframe>.`
+        );
+      }
+      const inner = await host.contentFrame();
+      if (inner === null) {
+        throw new FrameEntryError(
+          `harnessed: ${core.describeScope(path, link)} has no document to enter: the <iframe> is not attached to a frame.`
+        );
+      }
+      frame = inner;
+      start = index + 1;
+    }
+  } catch (error) {
+    await disposeAll(hosts);
+    throw error;
+  }
+  return { frame, scope: scope.slice(start), prefix: scope.slice(0, start), hosts };
+}
+async function disposeAll(handles) {
+  await Promise.all(handles.map((handle) => handle.dispose().catch(() => void 0)));
+}
+
+// src/puppeteer-query.ts
+var SET_VALUE_TYPES = ["color", "date", "time", "datetime-local", "month", "range", "week"];
+var NOT_EDITABLE = {
+  disabled: "it is disabled",
+  readonly: "it is readonly",
+  unfocused: "focus did not land on it"
+};
+function chord(key) {
+  if (key.length <= 1) return { modifiers: [], key };
+  const plus = key.endsWith("++");
+  const parts = (plus ? key.slice(0, -2) : key).split("+");
+  const main = plus ? "+" : parts.pop() ?? key;
+  return { modifiers: parts, key: main };
+}
+var PuppeteerQuery = class _PuppeteerQuery extends core.Query {
+  constructor(page, scope, selector) {
+    super(scope, selector);
+    this.page = page;
+  }
+  page;
+  clone(selector) {
+    return new _PuppeteerQuery(this.page, this.scope, selector);
+  }
+  /**
+   * The target and the frames crossed to reach it, or `null` under `now` when
+   * something on the way is not on screen yet. The caller owns every handle.
+   */
+  async resolve(lookup, timeout) {
+    core.checkTestIds(this.scope, this.selector);
+    const entered = await enterFrames(this.page, this.scope, lookup, timeout);
+    if (entered === null) return null;
+    try {
+      const element = await oneIn(
+        entered.frame,
+        entered.prefix,
+        entered.scope,
+        this.selector,
+        lookup,
+        timeout
+      );
+      if (element === null) {
+        await disposeAll(entered.hosts);
+        return null;
+      }
+      return { element, entered };
+    } catch (error) {
+      await disposeAll(entered.hosts);
+      throw error;
+    }
+  }
+  /** The single target, waiting for it to appear. */
+  async target(timeout) {
+    const target = await this.resolve("wait", timeout);
+    if (target === null) {
+      throw new Error(`harnessed: ${core.describeScope(this.scope, this.selector)} resolved to nothing.`);
+    }
+    return target;
+  }
+  /** Resolves the single target, runs `use`, and lets go of every handle after. */
+  async withTarget(options, use) {
+    const target = await this.target(options?.timeout);
+    try {
+      return await use(target.element);
+    } finally {
+      await release(target);
+    }
+  }
+  /**
+   * Visible by the shared layout rule, in a visible frame. Each iframe crossed is
+   * judged in its own document, which is how a cross-origin frame is covered.
+   */
+  async visible(target) {
+    for (const element of [...target.entered.hosts, target.element]) {
+      if (!await visibleInOwnDocument(element)) return false;
+    }
+    return true;
+  }
+  /** Whether the target is visible now. Absent is not visible; ambiguity still throws. */
+  async visibleNow(timeout) {
+    let target;
+    try {
+      target = await this.resolve("now", timeout);
+    } catch (error) {
+      if (!isAbsence(error)) throw error;
+      return false;
+    }
+    if (target === null) return false;
+    try {
+      return await this.visible(target);
+    } finally {
+      await release(target);
+    }
+  }
+  // --- interactions -------------------------------------------------------
+  async click(options) {
+    await this.withTarget(options, (element) => element.click());
+  }
+  async fill(value, options) {
+    await this.replaceValue("fill", value, options);
+  }
+  async clear(options) {
+    await this.replaceValue("clear", "", options);
+  }
+  /**
+   * Replaces the value, as Playwright's `fill()` does: select what is there, then
+   * insert the new text as one input event — or delete the selection, which is
+   * what makes `fill('')` clear rather than type nothing.
+   *
+   * The keys go to whatever has focus, so the target must be editable and hold
+   * focus first. Until it does — disabled, readonly, or focus refused — this
+   * waits, within the same timeout as the lookup, and then fails rather than
+   * typing into some other element.
+   */
+  async replaceValue(action, value, options) {
+    const timeout = core.timeoutFor(options?.timeout);
+    const deadline = Date.now() + timeout;
+    await this.withTarget(options, async (element) => {
+      for (; ; ) {
+        const mode = await element.evaluate(prepareEdit, SET_VALUE_TYPES, value);
+        if (mode === "done") return;
+        if (mode === "type") break;
+        if (Date.now() >= deadline) {
+          throw new Error(
+            `harnessed: ${action}() could not edit ${core.describeScope(this.scope, this.selector)} within ${timeout}ms: ${NOT_EDITABLE[mode]}.`
+          );
+        }
+        await sleep(POLL_MS);
+      }
+      if (value === "") await this.page.keyboard.press("Delete");
+      else await this.page.keyboard.sendCharacter(value);
+    });
+  }
+  async check(options) {
+    await this.setChecked(true, options);
+  }
+  async uncheck(options) {
+    await this.setChecked(false, options);
+  }
+  /** Idempotent, and verified: a click that did not change the state is an error. */
+  async setChecked(wanted, options) {
+    await this.withTarget(options, async (element) => {
+      if (await checkedOf(element) === wanted) return;
+      await element.click();
+      if (await checkedOf(element) !== wanted) {
+        throw new Error(
+          `harnessed: clicking ${core.describeScope(this.scope, this.selector)} did not ${wanted ? "check" : "uncheck"} it.`
+        );
+      }
+    });
+  }
+  /**
+   * Matches each value against an option's value, then its label, as Playwright
+   * does — and replaces a multi-select's selection rather than adding to it.
+   */
+  async selectOption(value, options) {
+    const wanted = Array.isArray(value) ? value : [value];
+    await this.withTarget(
+      options,
+      (element) => element.evaluate((node, values) => {
+        if (node.localName !== "select") {
+          throw new Error(`harnessed: selectOption() needs a <select>, not a <${node.localName}>.`);
+        }
+        const select = node;
+        const all = [...select.options];
+        const picked = values.map(
+          (want) => all.find((option) => option.value === want) ?? all.find((o) => o.label === want)
+        );
+        const missing = values.filter((_, index) => picked[index] === void 0);
+        if (missing.length > 0) {
+          throw new Error(`harnessed: no option matches ${missing.map((m) => `"${m}"`).join(", ")}.`);
+        }
+        if (!select.multiple && picked.length > 1) {
+          throw new Error("harnessed: cannot select several options in a single-select.");
+        }
+        for (const option of all) option.selected = picked.includes(option);
+        select.dispatchEvent(new Event("input", { bubbles: true, composed: true }));
+        select.dispatchEvent(new Event("change", { bubbles: true }));
+      }, wanted)
+    );
+  }
+  async hover(options) {
+    await this.withTarget(options, (element) => element.hover());
+  }
+  async focus(options) {
+    await this.withTarget(options, (element) => element.focus());
+  }
+  async blur(options) {
+    await this.withTarget(
+      options,
+      (element) => element.evaluate((node) => node.blur())
+    );
+  }
+  async press(key, options) {
+    await this.withTarget(options, async (element) => {
+      await element.focus();
+      const { modifiers, key: main } = chord(key);
+      for (const modifier of modifiers) await this.page.keyboard.down(modifier);
+      try {
+        await this.page.keyboard.press(main);
+      } finally {
+        for (const modifier of modifiers.reverse()) {
+          await this.page.keyboard.up(modifier);
+        }
+      }
+    });
+  }
+  /**
+   * Puppeteer sets files only from paths, so each File is written to disk
+   * first (see `filesOnDisk`): the name and bytes arrive, and the browser
+   * infers the type from the extension.
+   */
+  async upload(files, options) {
+    const list = Array.isArray(files) ? files : [files];
+    await this.withTarget(options, async (element) => {
+      core.checkFileTarget(await fileTargetOf(element), list.length, this.scope, this.selector);
+      const paths = await inject.filesOnDisk(list);
+      const input = await element.evaluateHandle(
+        (node) => node.localName === "label" ? node.control : node
+      );
+      try {
+        await input.uploadFile(...paths);
+      } finally {
+        await input.dispose();
+      }
+    });
+  }
+  // --- observations -------------------------------------------------------
+  async text(options) {
+    return this.withTarget(
+      options,
+      (element) => element.evaluate((node) => (node.textContent ?? "").trim())
+    );
+  }
+  async inputValue(options) {
+    return this.withTarget(
+      options,
+      (element) => element.evaluate((node) => node.value ?? "")
+    );
+  }
+  async attribute(name, options) {
+    return this.withTarget(
+      options,
+      (element) => element.evaluate((node, attribute) => node.getAttribute(attribute), name)
+    );
+  }
+  /** Puppeteer's own box, relative to the main frame; `null` (no box) reads as zeros. */
+  async boundingBox(options) {
+    const box = await this.withTarget(options, (element) => element.boundingBox());
+    return box ?? { x: 0, y: 0, width: 0, height: 0 };
+  }
+  async isVisible(options) {
+    let target;
+    try {
+      target = await this.target(options?.timeout);
+    } catch (error) {
+      if (!isAbsence(error)) throw error;
+      return false;
+    }
+    try {
+      return await this.visible(target);
+    } finally {
+      await release(target);
+    }
+  }
+  async isEnabled(options) {
+    return this.withTarget(options, async (element) => {
+      const [disabled, aria] = await element.evaluate(
+        (node) => [node.matches(":disabled"), node.getAttribute("aria-disabled")]
+      );
+      return core.enabledFrom(disabled, aria);
+    });
+  }
+  async isChecked(options) {
+    return this.withTarget(options, (element) => checkedOf(element));
+  }
+  async selectedOptions(options) {
+    return this.withTarget(
+      options,
+      (element) => element.evaluate(
+        (node) => [...node.selectedOptions ?? []].map((option) => option.value)
+      )
+    );
+  }
+  // --- waiting ------------------------------------------------------------
+  /**
+   * Polls from Node rather than waiting inside the page: the target can sit
+   * behind frames, each its own document, and a navigation mid-wait would take
+   * an in-page wait down with the document it ran in. A poll a navigation tore
+   * down answers nothing, and the next poll asks the new document.
+   */
+  async waitFor(state, options) {
+    const timeout = core.timeoutFor(options?.timeout);
+    const deadline = Date.now() + timeout;
+    for (; ; ) {
+      const visible = await this.visibleNow(Math.max(0, deadline - Date.now())).catch(
+        (error) => {
+          if (isNavigationError(error)) return void 0;
+          throw error;
+        }
+      );
+      if (visible !== void 0 && visible === (state === "visible")) return;
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `harnessed: ${core.describeScope(this.scope, this.selector)} did not become ${state} within ${timeout}ms.`
+        );
+      }
+      await sleep(POLL_MS);
+    }
+  }
+  async count() {
+    core.checkTestIds(this.scope, this.selector);
+    let entered;
+    try {
+      entered = await enterFrames(this.page, this.scope, "wait");
+    } catch (error) {
+      if (!isResolverOutcome(error)) throw error;
+      return 0;
+    }
+    if (entered === null) return 0;
+    try {
+      return await countIn(entered.frame, entered.prefix, entered.scope, this.selector);
+    } finally {
+      await disposeAll(entered.hosts);
+    }
+  }
+};
+function prepareEdit(node, setValueTypes, next) {
+  const element = node;
+  const control = node.localName === "input" || node.localName === "textarea";
+  if (!control && !element.isContentEditable) {
+    throw new Error(
+      `harnessed: fill() needs an <input>, <textarea> or [contenteditable] element, not a <${node.localName}>.`
+    );
+  }
+  const input = node;
+  if (control && node.matches(":disabled")) return "disabled";
+  if (control && input.readOnly) return "readonly";
+  element.focus();
+  const active = node.ownerDocument.activeElement;
+  const host = active;
+  const focused = active === node || !control && host !== null && host.isContentEditable && host.contains(node);
+  if (!focused) return "unfocused";
+  if (node.localName === "input" && setValueTypes.includes(input.type)) {
+    input.value = next;
+    if (input.value !== next) throw new Error(`harnessed: malformed value "${next}".`);
+    node.dispatchEvent(new Event("input", { bubbles: true, composed: true }));
+    node.dispatchEvent(new Event("change", { bubbles: true }));
+    return "done";
+  }
+  if (control) {
+    input.select();
+    return "type";
+  }
+  const range = node.ownerDocument.createRange();
+  range.selectNodeContents(node);
+  const selection = node.ownerDocument.getSelection();
+  selection?.removeAllRanges();
+  selection?.addRange(range);
+  return "type";
+}
+async function release(target) {
+  await disposeAll([target.element, ...target.entered.hosts]);
+}
+async function checkedOf(element) {
+  const [aria, native] = await element.evaluate(
+    (node) => [node.getAttribute("aria-checked"), Boolean(node.checked)]
+  );
+  return core.checkedFrom(aria, native);
+}
+core.registerDriver(PUPPETEER_DRIVER, (env, scope, selector) => {
+  return new PuppeteerQuery(env.page, scope, selector);
+});
+function absolute(env, url) {
+  const base = env.baseURL ?? env.page.url();
+  try {
+    return new URL(url, base).href;
+  } catch {
+    throw new Error(
+      `harnessed: cannot resolve "${url}" against "${base}". Pass a baseURL: puppeteer(page, { baseURL: 'http://localhost:3000' }).`
+    );
+  }
+}
+core.registerNavigation(PUPPETEER_DRIVER, {
+  async goto(env, url) {
+    const puppeteerEnv = env;
+    await puppeteerEnv.page.goto(absolute(puppeteerEnv, url), { waitUntil: "domcontentloaded" });
+  },
+  currentUrl(env) {
+    return env.page.url();
+  },
+  /**
+   * Polled from Node: `page.url()` is tracked by Puppeteer across every kind of
+   * navigation, including a client-side `history.pushState`, where an in-page
+   * wait would not survive a full navigation.
+   */
+  async waitForUrl(env, matches, timeout) {
+    const { page } = env;
+    const deadline = Date.now() + timeout;
+    while (!matches(new URL(page.url()))) {
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `harnessed: the URL did not match within ${timeout}ms; it is still ${page.url()}.`
+        );
+      }
+      await sleep(POLL_MS);
+    }
+  }
+});
+
+// src/env.ts
+function puppeteer(page, options = {}) {
+  return { driver: PUPPETEER_DRIVER, page, baseURL: options.baseURL };
+}
+
+exports.PUPPETEER_DRIVER = PUPPETEER_DRIVER;
+exports.PuppeteerQuery = PuppeteerQuery;
+exports.puppeteer = puppeteer;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map