@piwitests/reporter 0.23.0 → 0.24.0

package/dist/global-setup-module.js

@@ -107,7 +107,15 @@ var PIWI_ENV_KEYS = {
   captureServerTraces: "PIWI_CAPTURE_SERVER_TRACES",
   inspectOnFailure: "PIWI_INSPECT_ON_FAIL",
   pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL",
-  outputFile: "PIWI_OUTPUT_FILE"
+  outputFile: "PIWI_OUTPUT_FILE",
+  aiMode: "PIWI_AI",
+  aiDir: "PIWI_AI_DIR",
+  aiOnMiss: "PIWI_AI_ON_MISS",
+  aiMaxSteps: "PIWI_AI_MAX_FLOW_STEPS",
+  aiMaxSnapshotChars: "PIWI_AI_MAX_SNAPSHOT_CHARS",
+  aiOptionalProbeTimeout: "PIWI_AI_OPTIONAL_PROBE_TIMEOUT",
+  aiResponseWaitTimeout: "PIWI_AI_RESPONSE_WAIT_TIMEOUT",
+  aiScreenshotFallback: "PIWI_AI_SCREENSHOT_FALLBACK"
 };
 var PIWI_DESKTOP_CONFIG_ENV = "PIWI_DESKTOP_CONFIG";
 function readBool(val) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { FullConfig, Suite, TestCase, TestResult, FullResult } from '@playwright/test/reporter';
-import { PlaywrightTestConfig } from '@playwright/test';
+import { PlaywrightTestConfig, Locator, TestType, Page, Fixtures, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions } from '@playwright/test';
 export { PlaywrightTestConfig } from '@playwright/test';
 export { PiwiFixtures, extendPiwiFixtures, piwiFixtures } from './internal/capture/capture-fixtures.js';
 import '@piwitests/picker-dom';
@@ -114,6 +114,61 @@ interface PiwiDashboardOptions {
     tags?: string[];
     /** Additional custom metadata as key-value pairs */
     customData?: Record<string, unknown>;
+    /**
+     * Natural-language locators and flows (`page.piwiLocator(...)` /
+     * `page.piwiRun(...)`). An agent resolves each prompt once into a committed,
+     * deterministic artifact; every run replays that artifact with plain
+     * Playwright calls — zero LLM calls in the default `replay` mode.
+     */
+    ai?: {
+        /**
+         * `replay` (default) executes committed artifacts read-only and fails closed
+         * on a miss; `resolve` authors missing entries; `heal` repairs entries that
+         * no longer replay. Can also be set with `PIWI_AI`.
+         */
+        mode?: 'replay' | 'resolve' | 'heal';
+        /**
+         * Directory name (per spec) that holds the committed entries. Defaults to
+         * `__piwi__`. Can also be set with `PIWI_AI_DIR`.
+         */
+        dir?: string;
+        /**
+         * On a replay miss: `fail` (default) errors with repro instructions, or
+         * `fixme` marks the test fixme (yellow) instead. Can also be set with
+         * `PIWI_AI_ON_MISS`.
+         */
+        onMiss?: 'fail' | 'fixme';
+        /**
+         * Max steps the agent may take resolving one `piwiRun` flow (the authoring
+         * budget). Defaults to `20`. Can also be set with `PIWI_AI_MAX_FLOW_STEPS`.
+         */
+        maxSteps?: number;
+        /**
+         * Max characters of the page ARIA snapshot sent to the authoring model per
+         * iteration (cost control). Defaults to `24000`. Can also be set with
+         * `PIWI_AI_MAX_SNAPSHOT_CHARS`.
+         */
+        maxSnapshotChars?: number;
+        /**
+         * Timeout (ms) for the existence probe of an `optional` step during replay.
+         * Defaults to `2000`. Can also be set with `PIWI_AI_OPTIONAL_PROBE_TIMEOUT`.
+         */
+        optionalProbeTimeout?: number;
+        /**
+         * Timeout (ms) for a step's `waitForResponse` (the Ajax wait) during replay,
+         * and the network-settle window during authoring. Omitted uses Playwright's
+         * default action timeout. Can also be set with `PIWI_AI_RESPONSE_WAIT_TIMEOUT`.
+         */
+        responseWaitTimeout?: number;
+        /**
+         * Send a screenshot to the authoring model as a vision fallback when the page's
+         * ARIA snapshot is empty (a canvas-heavy page the model otherwise can't ground
+         * against). **Requires a vision-capable model** — leave it off (the default) for
+         * models that don't accept images. Only affects `resolve`/`heal`, never replay.
+         * Can also be set with `PIWI_AI_SCREENSHOT_FALLBACK`.
+         */
+        screenshotFallback?: boolean;
+    };
     /**
      * Write a JSON file with the submitted run's dashboard URL, id, project id and
      * status after the run lands, so a CI pipeline can consume it (e.g. feed the
@@ -228,6 +283,59 @@ declare class PiwiDashboardReporter {
     onEnd(result: FullResult): Promise<void>;
 }
 
+/**
+ * Parameters are first-class: a template like `row for {name}` is the cache key,
+ * so one entry serves every value. Placeholders survive compilation as `{{name}}`
+ * markers inside locator args and step values; replay substitutes the runtime
+ * value locally. Param values are masked out of any snapshot sent to the model,
+ * so secrets never leave the machine.
+ */
+
+/**
+ * Extract the placeholder names from a template string literal at the type level,
+ * so a missing or misspelled parameter is a compile error. Placeholder names are
+ * assumed brace-free (`{email}`, not `{a{b}}`).
+ */
+type ExtractParams<S extends string> = S extends `${string}{${infer Param}}${infer Rest}` ? Param | ExtractParams<Rest> : never;
+/**
+ * The parameter argument list for a template: no argument when the template has
+ * no placeholders, otherwise a required record of every placeholder → string.
+ */
+type ParamArgs<S extends string> = [ExtractParams<S>] extends [never] ? [] : [params: Record<ExtractParams<S>, string>];
+
+/** How the fixture behaves on a cache miss. */
+type AiMode = 'replay' | 'resolve' | 'heal';
+/** What to do when replay finds no committed entry. */
+type AiOnMiss = 'fail' | 'fixme';
+/**
+ * The natural-language surface attached to `page`. Template-literal types make a
+ * missing or misspelled `{param}` a compile error (`ParamArgs`): a template with
+ * placeholders requires a matching params object, one without takes no argument.
+ */
+interface PiwiAi {
+    /** Resolve a single element by description. Returns a real, synchronous `Locator`. */
+    piwiLocator<S extends string>(template: S, ...params: ParamArgs<S>): Locator;
+    /** Replay a compiled flow (steps + postcondition oracle). */
+    piwiRun<S extends string>(template: S, ...params: ParamArgs<S>): Promise<void>;
+}
+/** Local `{ [key: string]: any }` used by the extend signature (mirrors capture fixtures). */
+type FixtureArgs = {
+    [key: string]: any;
+};
+/**
+ * Fixtures that override `page` to carry the `PiwiAi` surface. Composable with
+ * `piwiFixtures`; keep this separate so a project can opt into AI steps without
+ * the capture fixtures (and vice versa).
+ */
+declare const piwiAiFixtures: Fixtures<{}, {}, PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
+/**
+ * Add the `PiwiAi` surface to a test's `page`. Compose over `extendPiwiFixtures`
+ * (or a base `test`) — e.g. `export const test = extendPiwiAi(extendPiwiFixtures(base))`.
+ */
+declare function extendPiwiAi<TestArgs extends FixtureArgs, WorkerArgs extends FixtureArgs>(test: TestType<TestArgs, WorkerArgs>): TestType<TestArgs & {
+    page: Page & PiwiAi;
+}, WorkerArgs>;
+
 /**
  * Public API of `@piwitests/reporter`.
  *
@@ -237,4 +345,4 @@ declare class PiwiDashboardReporter {
  * exported from this file, it isn't part of the supported API.
  */
 
-export { type PiwiDashboardOptions, PiwiDashboardReporter, createGlobalSetup, PiwiDashboardReporter as default, wrapConfig };
+export { type AiMode, type AiOnMiss, type PiwiAi, type PiwiDashboardOptions, PiwiDashboardReporter, createGlobalSetup, PiwiDashboardReporter as default, extendPiwiAi, piwiAiFixtures, wrapConfig };