@humanjs/playwright 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -163,6 +163,28 @@ interface CaptureResult {
     cleanup(): Promise<void>;
 }
 
+/** Options for {@link generatePlaywrightTest} / `Recording.toPlaywright`. */
+interface PlaywrightTestOptions {
+    /**
+     * Keep recorded `sleep()` pauses. Default `false` — a test shouldn't carry
+     * human-timing waits (slow + flaky in CI; Playwright auto-waits instead).
+     */
+    readonly keepSleeps?: boolean;
+    /** Test title. Defaults to the recording's name, else `'recorded session'`. */
+    readonly title?: string;
+    /**
+     * Wrap actions in `test.step(...)` groups — a new step per navigation — so
+     * they show as collapsible sections in the HTML report / trace. Default false.
+     */
+    readonly steps?: boolean;
+    /**
+     * When all `goto`s share one origin, emit them as relative paths and add a
+     * note to set `use.baseURL` in the Playwright config (portable across
+     * environments). Default false — absolute URLs that run without any config.
+     */
+    readonly baseUrl?: boolean;
+}
+
 /**
  * Encoding quality preset. Picks the per-frame capture quality + the
  * ffmpeg encode settings used to assemble them into a video.
@@ -212,10 +234,18 @@ interface TimelineEvent {
     readonly durationMs: number;
     /** Error message, present only if the action threw. */
     readonly error?: string;
+    /**
+     * For `type` / `paste`: the actual text written, captured when
+     * `captureInputs` is on (the default). Omitted when capture is off or the
+     * target is a password field (always masked). Flows into exported code.
+     */
+    readonly inputValue?: string;
 }
 /** Structured action timeline of a recording. */
 interface Timeline {
     readonly version: 1;
+    /** Optional label for the recording (used as the generated test's title). */
+    readonly name?: string;
     readonly personality: string;
     readonly seed: string | null;
     readonly speed: string;
@@ -224,6 +254,7 @@ interface Timeline {
 }
 /** Metadata passed from `human.record()` into the Recording constructor. */
 interface RecordingTimelineSource {
+    readonly name?: string;
     readonly personality: string;
     readonly seed: string | null;
     readonly speed: string;
@@ -288,6 +319,30 @@ declare class Recording {
      * @returns the resolved output path.
      */
     toTimeline(outputPath: string): Promise<string>;
+    /**
+     * Generates a standalone, runnable HumanJS script from the timeline and
+     * writes it to `outputPath`. String selectors round-trip verbatim; typed
+     * values are included when `captureInputs` was on (passwords masked).
+     *
+     * Independent of frame capture — works on timeline-only recordings and is
+     * unaffected by `dispose()`.
+     *
+     * @returns the resolved output path.
+     */
+    toHumanJS(outputPath: string): Promise<string>;
+    /**
+     * Generates a `@playwright/test` spec from the timeline — a humanized test
+     * (uses `createHuman` + `human.*`), not raw Playwright — and writes it to
+     * `outputPath`. Runs instant in CI / recorded speed locally, drops timing
+     * `sleep()`s (pass `{ keepSleeps: true }` to keep them), and derives the
+     * assertions it safely can.
+     *
+     * Independent of frame capture — works on timeline-only recordings and is
+     * unaffected by `dispose()`.
+     *
+     * @returns the resolved output path.
+     */
+    toPlaywright(outputPath: string, options?: PlaywrightTestOptions): Promise<string>;
     /**
      * Releases the captured-frames temp directory. After this call, `toVideo()`
      * and `toGif()` throw — but `toTimeline()` and the in-memory `timeline`
@@ -458,21 +513,29 @@ interface Human {
     /**
      * Move the mouse along a humanized Bezier path to `target` and click.
      *
-     * `target` accepts either a Playwright-compatible selector string (e.g.
-     * `'button:has-text("Buy now")'`) or a built `Locator`. The click point
-     * inside the element is Gaussian-distributed around the center.
+     * `target` accepts a Playwright-compatible selector string (e.g.
+     * `'button:has-text("Buy now")'`), a built `Locator`, or a raw `Point`.
+     * For element targets the click point is Gaussian-distributed around the
+     * center; for a raw `Point` the exact coordinates are clicked. The
+     * `Point` form is the fallback for things with no clean selector —
+     * icon-only buttons, canvas, SVG — where you can see the pixel position
+     * but can't address the element.
      *
-     * In `speed: 'instant'`, all humanization is skipped and Playwright's
-     * native `locator.click()` is used directly.
+     * In `speed: 'instant'`, all humanization is skipped: element targets use
+     * Playwright's native `locator.click()`; a `Point` dispatches one
+     * `mouse.click()` at the coordinates.
      */
-    click(target: Locator | string): Promise<void>;
+    click(target: MouseTarget): Promise<void>;
     /**
      * Right-click `target` — opens a native context menu. Same Bezier-path
      * motion and hover dwell as `click()`; only the dispatched button differs.
+     * Accepts the same selector / `Locator` / `Point` targets as `click()`.
      *
-     * In `speed: 'instant'`, falls back to `locator.click({ button: 'right' })`.
+     * In `speed: 'instant'`, element targets fall back to
+     * `locator.click({ button: 'right' })`; a `Point` dispatches one
+     * `mouse.click({ button: 'right' })` at the coordinates.
      */
-    rightClick(target: Locator | string): Promise<void>;
+    rightClick(target: MouseTarget): Promise<void>;
     /**
      * Move the cursor to `target` along a humanized Bezier path and settle
      * on it — no click is dispatched. Useful for hover-triggered UI
@@ -670,9 +733,110 @@ interface Human {
      */
     record(fn: () => Promise<void>): Promise<Recording>;
     record(options: HumanRecordOptions, fn: () => Promise<void>): Promise<Recording>;
+    /**
+     * Take a screenshot of the page. Forwards to `page.screenshot(options)`
+     * unchanged — see Playwright docs for the full options shape.
+     *
+     * Not a humanized action: no plugin events fire. Pure ergonomic
+     * re-export so `human.*` stays a single surface.
+     */
+    screenshot(options?: Parameters<Page['screenshot']>[0]): Promise<Buffer>;
+    /**
+     * Visible text content of the page (`document.body.innerText`). Forwards
+     * to `page.innerText('body')`. Useful for AI agents that need to
+     * understand what's on screen without parsing HTML.
+     *
+     * For a region instead of the whole page, use `page.innerText(selector)`.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    pageText(): Promise<string>;
+    /**
+     * Full HTML of the page. Forwards to `page.content()`. Often large
+     * (50–500 KB on typical sites) — prefer {@link Human.pageText} when
+     * passing to an LLM unless structure matters.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    content(): Promise<string>;
+    /**
+     * Current URL of the page. Forwards to `page.url()`. Synchronous return
+     * because Playwright's underlying API is sync.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    url(): string;
+    /**
+     * Current document title. Forwards to `page.title()`.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    title(): Promise<string>;
+    /**
+     * Reload the current page. Forwards to `page.reload(options)`. Real-user
+     * analog of hitting the refresh button — the click motion is *not*
+     * humanized (we treat reload as navigation, not a cursor action).
+     *
+     * Plugins observe a `'reload'` action.
+     */
+    reload(options?: Parameters<Page['reload']>[0]): Promise<void>;
+    /**
+     * Navigate back in the browser history. Forwards to `page.goBack(options)`.
+     *
+     * Plugins observe a `'goBack'` action.
+     */
+    goBack(options?: Parameters<Page['goBack']>[0]): Promise<void>;
+    /**
+     * Navigate forward in the browser history. Forwards to
+     * `page.goForward(options)`.
+     *
+     * Plugins observe a `'goForward'` action.
+     */
+    goForward(options?: Parameters<Page['goForward']>[0]): Promise<void>;
+    /**
+     * Wait until the page reaches the specified load state. Forwards to
+     * `page.waitForLoadState(state, options)`. Common after a humanized
+     * click that triggers navigation — gives the page time to settle before
+     * the next action.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    waitForLoadState(state?: Parameters<Page['waitForLoadState']>[0], options?: Parameters<Page['waitForLoadState']>[1]): Promise<void>;
+    /**
+     * Wait until the page's URL matches `url` (string, RegExp, or predicate).
+     * Forwards to `page.waitForURL(url, options)`. Common post-action wait
+     * (e.g. after `human.click('#login')`, wait for `/dashboard`).
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    waitForURL(url: Parameters<Page['waitForURL']>[0], options?: Parameters<Page['waitForURL']>[1]): Promise<void>;
+    /**
+     * Resize the viewport. Forwards to `page.setViewportSize(size)`. Useful
+     * for testing responsive layouts or switching between breakpoints
+     * mid-session.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /**
+     * Render the page as a PDF. Forwards to `page.pdf(options)`. Chromium
+     * only; works most reliably in headless mode (in headed mode, Playwright
+     * silently switches to a print-style render).
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    pdf(options?: Parameters<Page['pdf']>[0]): Promise<Buffer>;
 }
 /** Options for {@link Human.record}. */
 interface HumanRecordOptions {
+    /**
+     * Optional label for the recording. Stored on the timeline and used as the
+     * title of a generated `toPlaywright()` test.
+     */
+    readonly name?: string;
     /**
      * Whether to capture frames for video output. Defaults to `true`.
      * Set to `false` for timeline-only recordings (no capture loop, no
@@ -685,6 +849,21 @@ interface HumanRecordOptions {
      * Defaults to `'high'`. Ignored when `video: false`.
      */
     readonly quality?: RecordingQuality;
+    /**
+     * Capture the actual typed/pasted text into the timeline (and therefore
+     * into code generated by `toHumanJS()` / `toPlaywright()`). Defaults to
+     * `true`.
+     *
+     * Values typed/pasted into `input[type="password"]` are always masked
+     * (omitted) regardless of this flag — the video already renders them as
+     * dots, and freezing a cleartext secret into an artifact would leak more
+     * than the recording itself. Set `false` to record no input values at all;
+     * exporters then emit empty-string placeholders.
+     *
+     * Captured values land in the timeline JSON and any exported test, so treat
+     * those artifacts with the same care as the values themselves.
+     */
+    readonly captureInputs?: boolean;
 }
 /**
  * Creates a humanized session bound to a Playwright `Page`.
@@ -707,4 +886,4 @@ interface HumanRecordOptions {
  */
 declare function createHuman(page: Page, options?: CreateHumanOptions): Promise<Human>;
 
-export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type KeyModifier, type KeyName, type KeyOrChord, type MouseTarget, type PressResult, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, createHuman, installMouseHelper };
+export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type KeyModifier, type KeyName, type KeyOrChord, type MouseTarget, type PlaywrightTestOptions, type PressResult, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, createHuman, installMouseHelper };

package/dist/index.d.ts

@@ -163,6 +163,28 @@ interface CaptureResult {
     cleanup(): Promise<void>;
 }
 
+/** Options for {@link generatePlaywrightTest} / `Recording.toPlaywright`. */
+interface PlaywrightTestOptions {
+    /**
+     * Keep recorded `sleep()` pauses. Default `false` — a test shouldn't carry
+     * human-timing waits (slow + flaky in CI; Playwright auto-waits instead).
+     */
+    readonly keepSleeps?: boolean;
+    /** Test title. Defaults to the recording's name, else `'recorded session'`. */
+    readonly title?: string;
+    /**
+     * Wrap actions in `test.step(...)` groups — a new step per navigation — so
+     * they show as collapsible sections in the HTML report / trace. Default false.
+     */
+    readonly steps?: boolean;
+    /**
+     * When all `goto`s share one origin, emit them as relative paths and add a
+     * note to set `use.baseURL` in the Playwright config (portable across
+     * environments). Default false — absolute URLs that run without any config.
+     */
+    readonly baseUrl?: boolean;
+}
+
 /**
  * Encoding quality preset. Picks the per-frame capture quality + the
  * ffmpeg encode settings used to assemble them into a video.
@@ -212,10 +234,18 @@ interface TimelineEvent {
     readonly durationMs: number;
     /** Error message, present only if the action threw. */
     readonly error?: string;
+    /**
+     * For `type` / `paste`: the actual text written, captured when
+     * `captureInputs` is on (the default). Omitted when capture is off or the
+     * target is a password field (always masked). Flows into exported code.
+     */
+    readonly inputValue?: string;
 }
 /** Structured action timeline of a recording. */
 interface Timeline {
     readonly version: 1;
+    /** Optional label for the recording (used as the generated test's title). */
+    readonly name?: string;
     readonly personality: string;
     readonly seed: string | null;
     readonly speed: string;
@@ -224,6 +254,7 @@ interface Timeline {
 }
 /** Metadata passed from `human.record()` into the Recording constructor. */
 interface RecordingTimelineSource {
+    readonly name?: string;
     readonly personality: string;
     readonly seed: string | null;
     readonly speed: string;
@@ -288,6 +319,30 @@ declare class Recording {
      * @returns the resolved output path.
      */
     toTimeline(outputPath: string): Promise<string>;
+    /**
+     * Generates a standalone, runnable HumanJS script from the timeline and
+     * writes it to `outputPath`. String selectors round-trip verbatim; typed
+     * values are included when `captureInputs` was on (passwords masked).
+     *
+     * Independent of frame capture — works on timeline-only recordings and is
+     * unaffected by `dispose()`.
+     *
+     * @returns the resolved output path.
+     */
+    toHumanJS(outputPath: string): Promise<string>;
+    /**
+     * Generates a `@playwright/test` spec from the timeline — a humanized test
+     * (uses `createHuman` + `human.*`), not raw Playwright — and writes it to
+     * `outputPath`. Runs instant in CI / recorded speed locally, drops timing
+     * `sleep()`s (pass `{ keepSleeps: true }` to keep them), and derives the
+     * assertions it safely can.
+     *
+     * Independent of frame capture — works on timeline-only recordings and is
+     * unaffected by `dispose()`.
+     *
+     * @returns the resolved output path.
+     */
+    toPlaywright(outputPath: string, options?: PlaywrightTestOptions): Promise<string>;
     /**
      * Releases the captured-frames temp directory. After this call, `toVideo()`
      * and `toGif()` throw — but `toTimeline()` and the in-memory `timeline`
@@ -458,21 +513,29 @@ interface Human {
     /**
      * Move the mouse along a humanized Bezier path to `target` and click.
      *
-     * `target` accepts either a Playwright-compatible selector string (e.g.
-     * `'button:has-text("Buy now")'`) or a built `Locator`. The click point
-     * inside the element is Gaussian-distributed around the center.
+     * `target` accepts a Playwright-compatible selector string (e.g.
+     * `'button:has-text("Buy now")'`), a built `Locator`, or a raw `Point`.
+     * For element targets the click point is Gaussian-distributed around the
+     * center; for a raw `Point` the exact coordinates are clicked. The
+     * `Point` form is the fallback for things with no clean selector —
+     * icon-only buttons, canvas, SVG — where you can see the pixel position
+     * but can't address the element.
      *
-     * In `speed: 'instant'`, all humanization is skipped and Playwright's
-     * native `locator.click()` is used directly.
+     * In `speed: 'instant'`, all humanization is skipped: element targets use
+     * Playwright's native `locator.click()`; a `Point` dispatches one
+     * `mouse.click()` at the coordinates.
      */
-    click(target: Locator | string): Promise<void>;
+    click(target: MouseTarget): Promise<void>;
     /**
      * Right-click `target` — opens a native context menu. Same Bezier-path
      * motion and hover dwell as `click()`; only the dispatched button differs.
+     * Accepts the same selector / `Locator` / `Point` targets as `click()`.
      *
-     * In `speed: 'instant'`, falls back to `locator.click({ button: 'right' })`.
+     * In `speed: 'instant'`, element targets fall back to
+     * `locator.click({ button: 'right' })`; a `Point` dispatches one
+     * `mouse.click({ button: 'right' })` at the coordinates.
      */
-    rightClick(target: Locator | string): Promise<void>;
+    rightClick(target: MouseTarget): Promise<void>;
     /**
      * Move the cursor to `target` along a humanized Bezier path and settle
      * on it — no click is dispatched. Useful for hover-triggered UI
@@ -670,9 +733,110 @@ interface Human {
      */
     record(fn: () => Promise<void>): Promise<Recording>;
     record(options: HumanRecordOptions, fn: () => Promise<void>): Promise<Recording>;
+    /**
+     * Take a screenshot of the page. Forwards to `page.screenshot(options)`
+     * unchanged — see Playwright docs for the full options shape.
+     *
+     * Not a humanized action: no plugin events fire. Pure ergonomic
+     * re-export so `human.*` stays a single surface.
+     */
+    screenshot(options?: Parameters<Page['screenshot']>[0]): Promise<Buffer>;
+    /**
+     * Visible text content of the page (`document.body.innerText`). Forwards
+     * to `page.innerText('body')`. Useful for AI agents that need to
+     * understand what's on screen without parsing HTML.
+     *
+     * For a region instead of the whole page, use `page.innerText(selector)`.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    pageText(): Promise<string>;
+    /**
+     * Full HTML of the page. Forwards to `page.content()`. Often large
+     * (50–500 KB on typical sites) — prefer {@link Human.pageText} when
+     * passing to an LLM unless structure matters.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    content(): Promise<string>;
+    /**
+     * Current URL of the page. Forwards to `page.url()`. Synchronous return
+     * because Playwright's underlying API is sync.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    url(): string;
+    /**
+     * Current document title. Forwards to `page.title()`.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    title(): Promise<string>;
+    /**
+     * Reload the current page. Forwards to `page.reload(options)`. Real-user
+     * analog of hitting the refresh button — the click motion is *not*
+     * humanized (we treat reload as navigation, not a cursor action).
+     *
+     * Plugins observe a `'reload'` action.
+     */
+    reload(options?: Parameters<Page['reload']>[0]): Promise<void>;
+    /**
+     * Navigate back in the browser history. Forwards to `page.goBack(options)`.
+     *
+     * Plugins observe a `'goBack'` action.
+     */
+    goBack(options?: Parameters<Page['goBack']>[0]): Promise<void>;
+    /**
+     * Navigate forward in the browser history. Forwards to
+     * `page.goForward(options)`.
+     *
+     * Plugins observe a `'goForward'` action.
+     */
+    goForward(options?: Parameters<Page['goForward']>[0]): Promise<void>;
+    /**
+     * Wait until the page reaches the specified load state. Forwards to
+     * `page.waitForLoadState(state, options)`. Common after a humanized
+     * click that triggers navigation — gives the page time to settle before
+     * the next action.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    waitForLoadState(state?: Parameters<Page['waitForLoadState']>[0], options?: Parameters<Page['waitForLoadState']>[1]): Promise<void>;
+    /**
+     * Wait until the page's URL matches `url` (string, RegExp, or predicate).
+     * Forwards to `page.waitForURL(url, options)`. Common post-action wait
+     * (e.g. after `human.click('#login')`, wait for `/dashboard`).
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    waitForURL(url: Parameters<Page['waitForURL']>[0], options?: Parameters<Page['waitForURL']>[1]): Promise<void>;
+    /**
+     * Resize the viewport. Forwards to `page.setViewportSize(size)`. Useful
+     * for testing responsive layouts or switching between breakpoints
+     * mid-session.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /**
+     * Render the page as a PDF. Forwards to `page.pdf(options)`. Chromium
+     * only; works most reliably in headless mode (in headed mode, Playwright
+     * silently switches to a print-style render).
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    pdf(options?: Parameters<Page['pdf']>[0]): Promise<Buffer>;
 }
 /** Options for {@link Human.record}. */
 interface HumanRecordOptions {
+    /**
+     * Optional label for the recording. Stored on the timeline and used as the
+     * title of a generated `toPlaywright()` test.
+     */
+    readonly name?: string;
     /**
      * Whether to capture frames for video output. Defaults to `true`.
      * Set to `false` for timeline-only recordings (no capture loop, no
@@ -685,6 +849,21 @@ interface HumanRecordOptions {
      * Defaults to `'high'`. Ignored when `video: false`.
      */
     readonly quality?: RecordingQuality;
+    /**
+     * Capture the actual typed/pasted text into the timeline (and therefore
+     * into code generated by `toHumanJS()` / `toPlaywright()`). Defaults to
+     * `true`.
+     *
+     * Values typed/pasted into `input[type="password"]` are always masked
+     * (omitted) regardless of this flag — the video already renders them as
+     * dots, and freezing a cleartext secret into an artifact would leak more
+     * than the recording itself. Set `false` to record no input values at all;
+     * exporters then emit empty-string placeholders.
+     *
+     * Captured values land in the timeline JSON and any exported test, so treat
+     * those artifacts with the same care as the values themselves.
+     */
+    readonly captureInputs?: boolean;
 }
 /**
  * Creates a humanized session bound to a Playwright `Page`.
@@ -707,4 +886,4 @@ interface HumanRecordOptions {
  */
 declare function createHuman(page: Page, options?: CreateHumanOptions): Promise<Human>;
 
-export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type KeyModifier, type KeyName, type KeyOrChord, type MouseTarget, type PressResult, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, createHuman, installMouseHelper };
+export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type KeyModifier, type KeyName, type KeyOrChord, type MouseTarget, type PlaywrightTestOptions, type PressResult, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, createHuman, installMouseHelper };