effect-browser 0.2.0-beta.0 → 0.2.0-beta.1

package/dist/Testing.d.mts

@@ -0,0 +1,437 @@
+import { BrowserError, BrowserOperation, BrowserOutcome, BrowserReason, InitializationError } from "./Errors.mjs";
+import { a as BrowserPolicy, et as Viewport, n as AutomationOptions, nt as ViewportPoint } from "./BrowserData-CRuxEZcn.mjs";
+import { BrowserSession, OpenOptions } from "./Browser.mjs";
+import { r as BrowserBinding } from "./BrowserRuntime-Coz-5DYb.mjs";
+import { Crypto, Effect, Layer, Option, Schema, Scope } from "effect";
+//#region src/internal/testing/Frame.d.ts
+/** A valid 64×48 baseline JPEG, the bytes a scripted capture frame carries by default. */
+declare const jpegFrame: () => Uint8Array;
+//#endregion
+//#region src/internal/testing/Script.d.ts
+/** Host-only facts a scripted control reports beyond what its observed fields imply. */
+export declare const ControlFactsScript: Schema.Struct<{
+  readonly editable: Schema.optionalKey<Schema.Boolean>;
+  readonly formMethod: Schema.optionalKey<Schema.Literals<readonly ["get", "post", "dialog"]>>;
+  readonly hitTest: Schema.optionalKey<Schema.Literals<readonly ["self", "covered", "uncertain", "unsampled"]>>;
+  readonly placement: Schema.optionalKey<Schema.Literals<readonly ["inside", "partial", "outside"]>>;
+  readonly autocomplete: Schema.optionalKey<Schema.String>;
+  readonly box: Schema.optionalKey<Schema.Struct<{
+    readonly x: Schema.Finite;
+    readonly y: Schema.Finite;
+    readonly width: Schema.Finite;
+    readonly height: Schema.Finite;
+  }>>;
+}>;
+/**
+ * One control a scripted document offers. `id` becomes the issued `elementId`, so a scripted
+ * model turn can name it statically. Nothing here is a live capability.
+ */
+export declare const ControlScript: Schema.Struct<{
+  readonly id: Schema.NonEmptyString;
+  readonly kind: Schema.Literals<readonly ["link", "button", "input", "select", "textarea", "other"]>;
+  readonly label: Schema.String;
+  readonly disabled: Schema.optionalKey<Schema.Boolean>;
+  /** A checkbox or radio `input` without it starts unchecked, as a real one does. */
+  readonly checked: Schema.optionalKey<Schema.Boolean>;
+  readonly selected: Schema.optionalKey<Schema.Boolean>;
+  readonly inputType: Schema.optionalKey<Schema.String>;
+  readonly required: Schema.optionalKey<Schema.Boolean>;
+  readonly multiple: Schema.optionalKey<Schema.Boolean>;
+  /** The scripted select this option belongs to; it must be in the same document. */
+  readonly selectElementId: Schema.optionalKey<Schema.NonEmptyString>;
+  /**
+   * The link target, or the form action a submit control sends to: reported as the control's
+   * destination fact, and where activating it leads. Only a `link`, or a `button`/`input` whose
+   * `inputType` is `submit` or `image`, has one, because that is all a real document reports.
+   */
+  readonly destination: Schema.optionalKey<Schema.NonEmptyString>;
+  /** Where activation leads with no destination fact: what an `onclick` handler does. */
+  readonly activates: Schema.optionalKey<Schema.NonEmptyString>;
+  /** Outside the viewport: absent from viewport readings and refused by hover. */
+  readonly offscreen: Schema.optionalKey<Schema.Boolean>;
+  /** What `readText({ selector: "#id" })` returns; defaults to the label. */
+  readonly text: Schema.optionalKey<Schema.String>;
+  /** Clicking for a download completes one with this name. */
+  readonly download: Schema.optionalKey<Schema.NonEmptyString>;
+  readonly facts: Schema.optionalKey<Schema.Struct<{
+    readonly editable: Schema.optionalKey<Schema.Boolean>;
+    readonly formMethod: Schema.optionalKey<Schema.Literals<readonly ["get", "post", "dialog"]>>;
+    readonly hitTest: Schema.optionalKey<Schema.Literals<readonly ["self", "covered", "uncertain", "unsampled"]>>;
+    readonly placement: Schema.optionalKey<Schema.Literals<readonly ["inside", "partial", "outside"]>>;
+    readonly autocomplete: Schema.optionalKey<Schema.String>;
+    readonly box: Schema.optionalKey<Schema.Struct<{
+      readonly x: Schema.Finite;
+      readonly y: Schema.Finite;
+      readonly width: Schema.Finite;
+      readonly height: Schema.Finite;
+    }>>;
+  }>>;
+}>;
+export type ControlScript = typeof ControlScript.Type;
+export declare const DocumentScript: Schema.Struct<{
+  readonly url: Schema.NonEmptyString;
+  readonly title: Schema.optionalKey<Schema.String>;
+  readonly text: Schema.String;
+  readonly controls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly id: Schema.NonEmptyString;
+    readonly kind: Schema.Literals<readonly ["link", "button", "input", "select", "textarea", "other"]>;
+    readonly label: Schema.String;
+    readonly disabled: Schema.optionalKey<Schema.Boolean>;
+    /** A checkbox or radio `input` without it starts unchecked, as a real one does. */
+    readonly checked: Schema.optionalKey<Schema.Boolean>;
+    readonly selected: Schema.optionalKey<Schema.Boolean>;
+    readonly inputType: Schema.optionalKey<Schema.String>;
+    readonly required: Schema.optionalKey<Schema.Boolean>;
+    readonly multiple: Schema.optionalKey<Schema.Boolean>;
+    /** The scripted select this option belongs to; it must be in the same document. */
+    readonly selectElementId: Schema.optionalKey<Schema.NonEmptyString>;
+    /**
+     * The link target, or the form action a submit control sends to: reported as the control's
+     * destination fact, and where activating it leads. Only a `link`, or a `button`/`input` whose
+     * `inputType` is `submit` or `image`, has one, because that is all a real document reports.
+     */
+    readonly destination: Schema.optionalKey<Schema.NonEmptyString>;
+    /** Where activation leads with no destination fact: what an `onclick` handler does. */
+    readonly activates: Schema.optionalKey<Schema.NonEmptyString>;
+    /** Outside the viewport: absent from viewport readings and refused by hover. */
+    readonly offscreen: Schema.optionalKey<Schema.Boolean>;
+    /** What `readText({ selector: "#id" })` returns; defaults to the label. */
+    readonly text: Schema.optionalKey<Schema.String>;
+    /** Clicking for a download completes one with this name. */
+    readonly download: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly facts: Schema.optionalKey<Schema.Struct<{
+      readonly editable: Schema.optionalKey<Schema.Boolean>;
+      readonly formMethod: Schema.optionalKey<Schema.Literals<readonly ["get", "post", "dialog"]>>;
+      readonly hitTest: Schema.optionalKey<Schema.Literals<readonly ["self", "covered", "uncertain", "unsampled"]>>;
+      readonly placement: Schema.optionalKey<Schema.Literals<readonly ["inside", "partial", "outside"]>>;
+      readonly autocomplete: Schema.optionalKey<Schema.String>;
+      readonly box: Schema.optionalKey<Schema.Struct<{
+        readonly x: Schema.Finite;
+        readonly y: Schema.Finite;
+        readonly width: Schema.Finite;
+        readonly height: Schema.Finite;
+      }>>;
+    }>>;
+  }>>>;
+}>;
+export type DocumentScript = typeof DocumentScript.Type;
+/**
+ * The documents a scripted browser can show. A navigation to a listed address reaches that
+ * document; an unlisted address reaches an empty document with that address.
+ */
+export declare const Script: Schema.Struct<{
+  readonly documents: Schema.$Array<Schema.Struct<{
+    readonly url: Schema.NonEmptyString;
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly text: Schema.String;
+    readonly controls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+      readonly id: Schema.NonEmptyString;
+      readonly kind: Schema.Literals<readonly ["link", "button", "input", "select", "textarea", "other"]>;
+      readonly label: Schema.String;
+      readonly disabled: Schema.optionalKey<Schema.Boolean>;
+      /** A checkbox or radio `input` without it starts unchecked, as a real one does. */
+      readonly checked: Schema.optionalKey<Schema.Boolean>;
+      readonly selected: Schema.optionalKey<Schema.Boolean>;
+      readonly inputType: Schema.optionalKey<Schema.String>;
+      readonly required: Schema.optionalKey<Schema.Boolean>;
+      readonly multiple: Schema.optionalKey<Schema.Boolean>;
+      /** The scripted select this option belongs to; it must be in the same document. */
+      readonly selectElementId: Schema.optionalKey<Schema.NonEmptyString>;
+      /**
+       * The link target, or the form action a submit control sends to: reported as the control's
+       * destination fact, and where activating it leads. Only a `link`, or a `button`/`input` whose
+       * `inputType` is `submit` or `image`, has one, because that is all a real document reports.
+       */
+      readonly destination: Schema.optionalKey<Schema.NonEmptyString>;
+      /** Where activation leads with no destination fact: what an `onclick` handler does. */
+      readonly activates: Schema.optionalKey<Schema.NonEmptyString>;
+      /** Outside the viewport: absent from viewport readings and refused by hover. */
+      readonly offscreen: Schema.optionalKey<Schema.Boolean>;
+      /** What `readText({ selector: "#id" })` returns; defaults to the label. */
+      readonly text: Schema.optionalKey<Schema.String>;
+      /** Clicking for a download completes one with this name. */
+      readonly download: Schema.optionalKey<Schema.NonEmptyString>;
+      readonly facts: Schema.optionalKey<Schema.Struct<{
+        readonly editable: Schema.optionalKey<Schema.Boolean>;
+        readonly formMethod: Schema.optionalKey<Schema.Literals<readonly ["get", "post", "dialog"]>>;
+        readonly hitTest: Schema.optionalKey<Schema.Literals<readonly ["self", "covered", "uncertain", "unsampled"]>>;
+        readonly placement: Schema.optionalKey<Schema.Literals<readonly ["inside", "partial", "outside"]>>;
+        readonly autocomplete: Schema.optionalKey<Schema.String>;
+        readonly box: Schema.optionalKey<Schema.Struct<{
+          readonly x: Schema.Finite;
+          readonly y: Schema.Finite;
+          readonly width: Schema.Finite;
+          readonly height: Schema.Finite;
+        }>>;
+      }>>;
+    }>>>;
+  }>>;
+  /** The first page's document at connect; defaults to the first listed document. */
+  readonly start: Schema.optionalKey<Schema.NonEmptyString>;
+  /**
+   * What successive connection attempts to one browser do: `refuse` fails the attempt as an
+   * unreachable endpoint would, and `accept` connects. Attempts past the list connect.
+   */
+  readonly connections: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["accept", "refuse"]>>>;
+}>;
+export type Script = typeof Script.Type;
+declare const ScriptedReference_base: Schema.Class<ScriptedReference, Schema.Struct<{
+  readonly provider: Schema.Literal<"scripted">;
+  readonly id: Schema.NonEmptyString;
+}>, {}>;
+export declare class ScriptedReference extends ScriptedReference_base {}
+declare const ScriptedCleanupIssue_base: Schema.Class<ScriptedCleanupIssue, Schema.Struct<{
+  readonly step: Schema.Literals<readonly ["fence", "capture", "initialization", "disconnect"]>;
+  readonly reason: Schema.Literals<readonly ["timeout", "failed", "interrupted"]>;
+}>, {}>;
+export declare class ScriptedCleanupIssue extends ScriptedCleanupIssue_base {}
+declare const ScriptedCleanupResult_base: Schema.Class<ScriptedCleanupResult, Schema.Struct<{
+  readonly reference: typeof ScriptedReference;
+  readonly connection: Schema.Literals<readonly ["closed", "failed", "not-connected", "pending"]>;
+  readonly issues: Schema.$Array<typeof ScriptedCleanupIssue>;
+}>, {}>;
+/** Connection teardown facts for a scripted browser; there is no process or provider status. */
+export declare class ScriptedCleanupResult extends ScriptedCleanupResult_base {}
+/**
+ * The operations whose next call a test may script. `disconnect` is the owner's native teardown
+ * of a connection: a `Fail` makes it fail and a `Hold` parks it, however long cleanup waits.
+ */
+export declare const ScriptableOperation: Schema.Literals<("capture-stop" | "checkpoint" | "click" | "click-and-wait" | "close-page" | "control-facts" | "disconnect" | "download-action" | "file-chooser" | "fill" | "fill-form" | "hover" | "list-frames" | "list-pages" | "navigate" | "navigate-stop" | "new-page" | "observe" | "page-resume" | "page-suspend" | "pointer-move" | "press" | "read-text" | "resize" | "revalidate" | "screenshot" | "scroll" | "select-files" | "select-frame" | "select-option" | "select-page" | "type" | "wait" | "wheel")[]>;
+export type ScriptableOperation = typeof ScriptableOperation.Type;
+/** A held native call: the test learns that it arrived, then decides when it may finish. */
+interface Gate {
+  /** Resolves once the held call has reached the engine. */
+  readonly reached: Effect.Effect<void>;
+  /** Lets the held call finish normally. */
+  readonly open: Effect.Effect<void>;
+}
+/**
+ * What the next admitted call of one operation does instead of following the document model.
+ * `Fail` with `outcome: "unknown"` dispatches first and then fails, so the owner fences the
+ * session; the other outcomes never dispatch. `Hold` parks the call until its gate opens, before
+ * or after native dispatch. `Disconnect` drops the connection inside the call.
+ */
+type ScriptedOutcome = {
+  readonly _tag: "Fail";
+  readonly reason: BrowserReason;
+  readonly outcome: BrowserOutcome;
+} | {
+  readonly _tag: "Hold";
+  readonly gate: Gate;
+  readonly dispatched: boolean;
+} | {
+  readonly _tag: "Disconnect";
+  readonly dispatched?: boolean;
+};
+/** Evidence of one admitted call. It never carries filled values, typed text or addresses. */
+interface RecordedCall {
+  readonly sequence: number;
+  readonly operation: BrowserOperation;
+  readonly pageId: string;
+  readonly elementId?: string;
+  readonly selector?: string;
+  /** The engine was asked to act: the moment after which an outcome can be unknown. */
+  readonly dispatched: boolean;
+  readonly settled: "completed" | "failed" | "pending";
+}
+/** One frame a test hands to a running capture interval; omitted fields take defaults. */
+interface ScriptedFrame {
+  readonly bytes?: Uint8Array;
+  /** Presentation time in Unix milliseconds; defaults to forty milliseconds after the last frame. */
+  readonly timestamp?: number;
+  readonly viewportWidth?: number;
+  readonly viewportHeight?: number;
+}
+/**
+ * How one connection to a scripted browser went: refused by the script, still open, closed by
+ * its owner, dropped (as `disconnect` or an armed `Disconnect` drops it), or failed to close.
+ */
+type ScriptedConnection = "refused" | "open" | "closed" | "dropped" | "close-failed";
+/** What a page would see when it calls a registered binding: a reply, or a bare rejection. */
+type BindingReply = {
+  readonly ok: true;
+  readonly output: unknown;
+} | {
+  readonly ok: false;
+};
+/**
+ * The test's side of one scripted browser. The browser outlives any one connection, as a
+ * keep-alive browser does: a reconnection finds the same pages, and this handle keeps working
+ * while no connection is open.
+ */
+interface ScriptedControl {
+  readonly calls: Effect.Effect<ReadonlyArray<RecordedCall>>;
+  /** Arm the next admitted call of one operation. Arms are consumed one-shot in arming order. */
+  readonly next: (operation: ScriptableOperation, outcome: ScriptedOutcome) => Effect.Effect<void>;
+  readonly gate: Effect.Effect<Gate>;
+  readonly document: {
+    /**
+     * The document of the page selected last, whether or not a connection is open; `Closed`
+     * once that page is closed.
+     */
+    readonly current: Effect.Effect<DocumentScript, BrowserError>;
+    /**
+     * The document is replaced, as a navigation replaces it: every retained node and every
+     * pending wait on that page becomes stale, and a capture learns of a new document.
+     */
+    readonly replace: (next: DocumentScript) => Effect.Effect<void, BrowserError>;
+    /**
+     * The same document changes, as its own script would change it: controls that keep their
+     * id keep their identity, removed ones detach, waits re-evaluate, nothing goes stale.
+     */
+    readonly update: (next: DocumentScript) => Effect.Effect<void, BrowserError>;
+    /** What `fill` and `type` put into which control id. Never part of `calls`. */
+    readonly values: Effect.Effect<ReadonlyMap<string, string>>;
+    /** File names attached to which control id by file selection. */
+    readonly files: Effect.Effect<ReadonlyMap<string, ReadonlyArray<string>>>;
+  };
+  /**
+   * The last point a pointer command placed on any page, or null when none was placed yet. An
+   * input receipt reports the point placed on its own page, as Chromium's per-page pointer does.
+   */
+  readonly pointer: Effect.Effect<ViewportPoint | null>;
+  readonly capture: {
+    /** Deliver one frame to the interval capturing the selected page. */
+    readonly emit: (frame?: ScriptedFrame) => Effect.Effect<void, BrowserError>;
+  };
+  /** A page-side call of a registered `Bootstrap.binding`, through the real admission path. */
+  readonly invoke: (name: string, input: unknown, options?: {
+    readonly origin?: string;
+  }) => Effect.Effect<BindingReply>;
+  /** Every open connection drops; each owner reports its session as disconnected. */
+  readonly disconnect: Effect.Effect<void>;
+  /** Every connection made to this browser, in order, and how each has ended so far. */
+  readonly connections: Effect.Effect<ReadonlyArray<ScriptedConnection>>;
+}
+/** The real public session over the scripted engine, decorated the way owned sessions are. */
+interface ScriptedSession<E = never> extends BrowserSession<E> {
+  readonly reference: ScriptedReference;
+  readonly control: ScriptedControl;
+  readonly closeChecked: Effect.Effect<ScriptedCleanupResult, BrowserError>;
+  readonly close: Effect.Effect<ScriptedCleanupResult>;
+  readonly cleanupResult: Effect.Effect<Option.Option<ScriptedCleanupResult>>;
+}
+//#endregion
+//#region src/Testing.d.ts
+/**
+ * How a scripted browser is opened. The defaults are the ones a Chromium launch would use: an
+ * unrestricted policy of 100 actions, five minutes and 2 MiB, a 1280×720 viewport and a
+ * ten-second action timeout.
+ */
+export interface ScriptedOptions<E = never, R = never> extends OpenOptions<E, R> {
+  readonly policy?: BrowserPolicy;
+  readonly automation?: AutomationOptions;
+  readonly viewport?: Viewport;
+  readonly onCleanup?: (result: ScriptedCleanupResult) => Effect.Effect<void>;
+}
+/**
+ * The scripted engine as an opaque binding. Connections to one address reach one browser, so a
+ * reconnection finds the pages it left; each browser has one control handle.
+ */
+export interface ScriptedBinding {
+  readonly binding: BrowserBinding;
+  /** One control for each browser connected to so far, in first-connection order. */
+  readonly browsers: Effect.Effect<ReadonlyArray<ScriptedControl>>;
+}
+/**
+ * Open one scripted browser in the caller's Scope. The session is the real owner over a
+ * scripted native engine: admission, budgets, staleness, dispatch evidence, capture, page holds
+ * and typed callbacks are the production code paths. Only the page and its outcomes are scripted,
+ * and the owner's ids and handoff tokens come from `sequentialCrypto`.
+ */
+export declare const open: <E = never, R = never>(script: {
+  readonly documents: readonly {
+    readonly url: string;
+    readonly title?: string | undefined;
+    readonly text: string;
+    readonly controls?: readonly {
+      readonly id: string;
+      readonly kind: "button" | "input" | "link" | "other" | "select" | "textarea";
+      readonly label: string;
+      readonly disabled?: boolean | undefined;
+      readonly checked?: boolean | undefined;
+      readonly selected?: boolean | undefined;
+      readonly inputType?: string | undefined;
+      readonly required?: boolean | undefined;
+      readonly multiple?: boolean | undefined;
+      readonly selectElementId?: string | undefined;
+      readonly destination?: string | undefined;
+      readonly activates?: string | undefined;
+      readonly offscreen?: boolean | undefined;
+      readonly text?: string | undefined;
+      readonly download?: string | undefined;
+      readonly facts?: {
+        readonly editable?: boolean | undefined;
+        readonly formMethod?: "dialog" | "get" | "post" | undefined;
+        readonly hitTest?: "covered" | "self" | "uncertain" | "unsampled" | undefined;
+        readonly placement?: "inside" | "outside" | "partial" | undefined;
+        readonly autocomplete?: string | undefined;
+        readonly box?: {
+          readonly x: number;
+          readonly y: number;
+          readonly width: number;
+          readonly height: number;
+        } | undefined;
+      } | undefined;
+    }[] | undefined;
+  }[];
+  readonly start?: string | undefined;
+  readonly connections?: readonly ("accept" | "refuse")[] | undefined;
+}, options?: ScriptedOptions<E, R> | undefined) => Effect.Effect<ScriptedSession<E>, E | BrowserError | InitializationError, Scope.Scope | Exclude<R, Scope.Scope>>;
+/**
+ * The `Crypto` scripted browsers draw their ids and handoff tokens from. Its bytes count up from
+ * one on each build, so every value is predictable; it is not random and computes no digest.
+ * `open` uses it already. A provider Layer built over `binding` still requires a `Crypto`, and
+ * this one keeps such a test free of a platform package.
+ */
+export declare const sequentialCrypto: Layer.Layer<Crypto.Crypto>;
+/**
+ * The same engine for a provider Layer built on `browser-runtime`, such as
+ * `BrowserbaseBrowser.layer` with `BrowserBinding.layer(binding)`. Each address the Layer
+ * connects to is one browser with one control handle; reconnecting to it finds its pages.
+ */
+export declare const binding: (script: {
+  readonly documents: readonly {
+    readonly url: string;
+    readonly title?: string | undefined;
+    readonly text: string;
+    readonly controls?: readonly {
+      readonly id: string;
+      readonly kind: "button" | "input" | "link" | "other" | "select" | "textarea";
+      readonly label: string;
+      readonly disabled?: boolean | undefined;
+      readonly checked?: boolean | undefined;
+      readonly selected?: boolean | undefined;
+      readonly inputType?: string | undefined;
+      readonly required?: boolean | undefined;
+      readonly multiple?: boolean | undefined;
+      readonly selectElementId?: string | undefined;
+      readonly destination?: string | undefined;
+      readonly activates?: string | undefined;
+      readonly offscreen?: boolean | undefined;
+      readonly text?: string | undefined;
+      readonly download?: string | undefined;
+      readonly facts?: {
+        readonly editable?: boolean | undefined;
+        readonly formMethod?: "dialog" | "get" | "post" | undefined;
+        readonly hitTest?: "covered" | "self" | "uncertain" | "unsampled" | undefined;
+        readonly placement?: "inside" | "outside" | "partial" | undefined;
+        readonly autocomplete?: string | undefined;
+        readonly box?: {
+          readonly x: number;
+          readonly y: number;
+          readonly width: number;
+          readonly height: number;
+        } | undefined;
+      } | undefined;
+    }[] | undefined;
+  }[];
+  readonly start?: string | undefined;
+  readonly connections?: readonly ("accept" | "refuse")[] | undefined;
+}) => Effect.Effect<ScriptedBinding, BrowserError, never>;
+/** A valid 64×48 JPEG: the default bytes of a scripted capture frame, for a caller's own frames. */
+export declare const jpeg: typeof jpegFrame;
+//#endregion
+export type { BindingReply, Gate, RecordedCall, ScriptedConnection, ScriptedControl, ScriptedFrame, ScriptedOutcome, ScriptedSession };
+export {};
+//# sourceMappingURL=Testing.d.mts.map