@humanjs/playwright 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -3,6 +3,14 @@ export { ActionResult, ActionType, BezierPathOptions, ComputeReadingDwellOptions
3
3
  import { Locator, BrowserContext, Page } from 'playwright';
4
4
  export { Browser, BrowserContext, BrowserContextOptions, ElementHandle, LaunchOptions, Locator, Page, chromium, firefox, webkit } from 'playwright';
5
5
 
6
+ /** Anything that can resolve to a click/move point. */
7
+ type MouseTarget = Locator | string | Point;
8
+
9
+ /** Values accepted by {@link executeSelectOption} — the Playwright `selectOption` shape. */
10
+ type SelectOptionValues = Parameters<Locator['selectOption']>[0];
11
+ /** Files accepted by {@link executeUpload} — the Playwright `setInputFiles` shape. */
12
+ type UploadFiles = Parameters<Locator['setInputFiles']>[0];
13
+
6
14
  /**
7
15
  * Modifier tokens accepted in a `human.press()` chord. `Mod` and `CmdOrCtrl` /
8
16
  * `CommandOrControl` are the magic auto-mapping tokens (Meta on Mac,
@@ -73,8 +81,21 @@ interface PressResult {
73
81
  readonly dispatched: string;
74
82
  }
75
83
 
76
- /** Anything that can resolve to a click/move point. */
77
- type MouseTarget = Locator | string | Point;
84
+ /** Options for {@link installMouseHelper}. */
85
+ interface InstallMouseHelperOptions {
86
+ /** Cursor fill color. Defaults to the HumanJS amber `#f5a55c`. */
87
+ readonly color?: string;
88
+ /** Cursor visual size in pixels. Defaults to 22. */
89
+ readonly size?: number;
90
+ /**
91
+ * Render a ripple at each `mousedown` position so clicks read on video.
92
+ * Defaults to `true`.
93
+ */
94
+ readonly showClicks?: boolean;
95
+ /** Halo opacity behind the cursor. Defaults to `0.18`. */
96
+ readonly haloOpacity?: number;
97
+ }
98
+ declare function installMouseHelper(target: BrowserContext | Page, options?: InstallMouseHelperOptions): Promise<void>;
78
99
 
79
100
  /**
80
101
  * What to read:
@@ -163,6 +184,12 @@ interface CaptureResult {
163
184
  cleanup(): Promise<void>;
164
185
  }
165
186
 
187
+ /**
188
+ * Generates a standalone, runnable HumanJS script that replays the recorded
189
+ * session. String selectors round-trip verbatim; raw coordinates and
190
+ * un-captured inputs are emitted with a flag so they're easy to fix up.
191
+ */
192
+ declare function generateHumanJS(timeline: Timeline): string;
166
193
  /** Options for {@link generatePlaywrightTest} / `Recording.toPlaywright`. */
167
194
  interface PlaywrightTestOptions {
168
195
  /**
@@ -184,6 +211,15 @@ interface PlaywrightTestOptions {
184
211
  */
185
212
  readonly baseUrl?: boolean;
186
213
  }
214
+ /**
215
+ * Generates a `@playwright/test` spec that replays the session through
216
+ * HumanJS — a humanized test, not raw Playwright, since the humanization is
217
+ * the point. Uses the `@humanjs/playwright/test` fixture for the `human`
218
+ * (recorded personality / seed / speed applied via `test.use({ humanOptions })`),
219
+ * runs instant in CI / recorded speed locally, drops timing `sleep()`s by
220
+ * default, and derives the assertions it safely can.
221
+ */
222
+ declare function generatePlaywrightTest(timeline: Timeline, options?: PlaywrightTestOptions): string;
187
223
 
188
224
  /**
189
225
  * Encoding quality preset. Picks the per-frame capture quality + the
@@ -458,22 +494,15 @@ interface ScrollResult {
458
494
  readonly durationMs: number;
459
495
  }
460
496
 
461
- /** Options for {@link installMouseHelper}. */
462
- interface InstallMouseHelperOptions {
463
- /** Cursor fill color. Defaults to the HumanJS amber `#f5a55c`. */
464
- readonly color?: string;
465
- /** Cursor visual size in pixels. Defaults to 22. */
466
- readonly size?: number;
497
+ /** Options for {@link Human.selectText}. */
498
+ interface SelectTextOptions {
467
499
  /**
468
- * Render a ripple at each `mousedown` position so clicks read on video.
469
- * Defaults to `true`.
500
+ * Select only this substring of the element's text instead of all of it.
501
+ * Located inside the element whitespace-tolerantly (first match); falls back
502
+ * to selecting the whole element when not found.
470
503
  */
471
- readonly showClicks?: boolean;
472
- /** Halo opacity behind the cursor. Defaults to `0.18`. */
473
- readonly haloOpacity?: number;
504
+ text?: string;
474
505
  }
475
- declare function installMouseHelper(target: BrowserContext | Page, options?: InstallMouseHelperOptions): Promise<void>;
476
-
477
506
  /**
478
507
  * How fast the humanized session runs.
479
508
  * - `'human'` — full humanization (default)
@@ -491,6 +520,14 @@ interface CreateHumanOptions {
491
520
  readonly speed?: Speed;
492
521
  /** Plugins installed on this session, invoked in registration order. */
493
522
  readonly plugins?: readonly HumanPlugin[];
523
+ /**
524
+ * Visual cursor overlay ({@link installMouseHelper}) so humanized motion is
525
+ * visible in headed runs and recordings. **On by default.** Pass `false` to
526
+ * opt out — do this for `speed: 'instant'` / CI, where there's no motion to
527
+ * show and the injected cursor would land in test DOM and screenshots. Pass
528
+ * an options object to style it (color, size, …).
529
+ */
530
+ readonly cursor?: boolean | InstallMouseHelperOptions;
494
531
  /**
495
532
  * Starting cursor position used as the origin of the first humanized path.
496
533
  * Defaults to `{ x: 0, y: 0 }`. Set this if you've already moved the cursor
@@ -536,6 +573,17 @@ interface Human {
536
573
  * `mouse.click({ button: 'right' })` at the coordinates.
537
574
  */
538
575
  rightClick(target: MouseTarget): Promise<void>;
576
+ /**
577
+ * Double-click `target`. Identical humanized approach to `click()` — same
578
+ * Bezier path, hover dwell, and occasional near-miss — but the final
579
+ * dispatch is a double-click (two presses within the OS double-click
580
+ * window). Accepts the same selector / `Locator` / `Point` targets.
581
+ *
582
+ * In `speed: 'instant'`, element targets fall back to
583
+ * `locator.click({ clickCount: 2 })`; a `Point` dispatches
584
+ * `mouse.click(x, y, { clickCount: 2 })`.
585
+ */
586
+ doubleClick(target: MouseTarget): Promise<void>;
539
587
  /**
540
588
  * Move the cursor to `target` along a humanized Bezier path and settle
541
589
  * on it — no click is dispatched. Useful for hover-triggered UI
@@ -602,6 +650,87 @@ interface Human {
602
650
  * by nature.
603
651
  */
604
652
  paste(target: Locator | string, value: string): Promise<void>;
653
+ /**
654
+ * Clear a text field `target` (input, textarea, or contenteditable) with a
655
+ * humanized gesture: click to focus, **select-all**, a beat, then **delete**
656
+ * — the real keyboard motion a person uses to wipe a field before retyping,
657
+ * not a silent value reset. Fires the keydown/up + `input` events the page
658
+ * expects.
659
+ *
660
+ * Pair with `type()` to edit an existing value:
661
+ * `await human.clear('#name'); await human.type('#name', 'New');`
662
+ *
663
+ * In `speed: 'instant'`, delegates to Playwright's native `locator.clear()`.
664
+ */
665
+ clear(target: Locator | string): Promise<void>;
666
+ /**
667
+ * Tick a checkbox or radio `target`. Moves the cursor to the control and
668
+ * clicks it with the same humanized motion as `click()` — but only when
669
+ * needed: if it already reports checked, no click fires (a real user
670
+ * doesn't re-click a box that's already ticked). The resulting state is
671
+ * verified; trying to `check` something that won't toggle throws.
672
+ *
673
+ * `target` is element-bound (selector or `Locator`). In `speed: 'instant'`,
674
+ * delegates to Playwright's native `locator.check()`.
675
+ */
676
+ check(target: Locator | string): Promise<void>;
677
+ /**
678
+ * Untick a checkbox `target`. Mirror of `check()` — humanized click only if
679
+ * currently checked, with state verification afterward. Radios can't be
680
+ * unchecked by clicking (select a different option instead); attempting it
681
+ * throws a clear error.
682
+ *
683
+ * In `speed: 'instant'`, delegates to `locator.uncheck()`.
684
+ */
685
+ uncheck(target: Locator | string): Promise<void>;
686
+ /**
687
+ * Choose option(s) in a native `<select>` `target`. The cursor moves to the
688
+ * dropdown and settles on it (humanized), then the value is set — native
689
+ * selects open an OS menu automation can't drive visually, so the *approach*
690
+ * is humanized while the choice itself is set programmatically (firing
691
+ * `input`/`change`), exactly as Playwright does. For custom DOM dropdowns,
692
+ * drive the rendered options with `click` instead.
693
+ *
694
+ * `values` takes the Playwright `selectOption` shape — a value string, an
695
+ * array of values, or `{ value | label | index }`. Returns the option
696
+ * values that ended up selected.
697
+ *
698
+ * In `speed: 'instant'`, sets the value with no cursor motion.
699
+ */
700
+ selectOption(target: Locator | string, values: SelectOptionValues): Promise<string[]>;
701
+ /**
702
+ * Select text inside `target` (a paragraph, heading, input, …). The cursor
703
+ * moves to the element (humanized), then the text is highlighted — the
704
+ * "select this" gesture before copying, replacing, or triggering a highlight
705
+ * menu.
706
+ *
707
+ * By default the element's whole text is selected. Pass `{ text }` to select
708
+ * just that substring: HumanJS finds it inside the element (whitespace-
709
+ * tolerant, mapped to exact offsets, first match) and selects only that
710
+ * range — so a recorded partial highlight reproduces as itself, not the whole
711
+ * element. If the text can't be located, it falls back to selecting all of
712
+ * the element.
713
+ *
714
+ * `target` is element-bound (selector or `Locator`). In `speed: 'instant'`
715
+ * the cursor motion is skipped; the selection is still applied.
716
+ */
717
+ selectText(target: Locator | string, options?: SelectTextOptions): Promise<void>;
718
+ /**
719
+ * Attach file(s) to a file-input `target`. The cursor moves to the control
720
+ * (visible in recordings / the overlay), then the files are attached via
721
+ * `setInputFiles`. Unlike a real click this never opens the OS file dialog
722
+ * (which would hang) — files are set directly, the way Playwright models
723
+ * uploads.
724
+ *
725
+ * `target` should be the `<input type="file">`. For the common hidden-input-
726
+ * behind-a-styled-button pattern there's no visible control to approach, so
727
+ * the motion is skipped and the files are attached directly. `files` takes
728
+ * the Playwright `setInputFiles` shape (a path, an array of paths, or
729
+ * in-memory `{ name, mimeType, buffer }` payloads).
730
+ *
731
+ * In `speed: 'instant'`, attaches the files with no cursor motion.
732
+ */
733
+ upload(target: Locator | string, files: UploadFiles): Promise<void>;
605
734
  /**
606
735
  * Press a single key (`'Tab'`, `'Enter'`, `'Escape'`, `'ArrowDown'`, …)
607
736
  * or a keyboard chord (`'Mod+S'`, `'Cmd+Shift+P'`, `'Ctrl+C'`, …).
@@ -759,6 +888,22 @@ interface Human {
759
888
  * Not a humanized action: no plugin events fire.
760
889
  */
761
890
  content(): Promise<string>;
891
+ /**
892
+ * Accessibility-tree **outline** of the page (or a region) — every
893
+ * interactive element and landmark by its ARIA role + accessible name,
894
+ * rendered as compact YAML (Playwright's `ariaSnapshot`). The most
895
+ * token-efficient way for an AI agent to see what's actionable and pick a
896
+ * selector: the names map directly to `getByRole` / accessible-name
897
+ * selectors, which HumanJS already favors.
898
+ *
899
+ * Prefer this over {@link Human.content} when the question is "what can I
900
+ * click / fill"; reach for {@link Human.screenshot} when you need the
901
+ * visual layout. Pass `target` to scope the outline to a region.
902
+ *
903
+ * Not a humanized action: no plugin events fire. Requires Playwright ≥ 1.49
904
+ * (when `ariaSnapshot` landed).
905
+ */
906
+ outline(target?: Locator | string): Promise<string>;
762
907
  /**
763
908
  * Current URL of the page. Forwards to `page.url()`. Synchronous return
764
909
  * because Playwright's underlying API is sync.
@@ -886,4 +1031,4 @@ interface HumanRecordOptions {
886
1031
  */
887
1032
  declare function createHuman(page: Page, options?: CreateHumanOptions): Promise<Human>;
888
1033
 
889
- 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 };
1034
+ 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 SelectOptionValues, type SelectTextOptions, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, type UploadFiles, createHuman, generateHumanJS, generatePlaywrightTest, installMouseHelper };
package/dist/index.d.ts CHANGED
@@ -3,6 +3,14 @@ export { ActionResult, ActionType, BezierPathOptions, ComputeReadingDwellOptions
3
3
  import { Locator, BrowserContext, Page } from 'playwright';
4
4
  export { Browser, BrowserContext, BrowserContextOptions, ElementHandle, LaunchOptions, Locator, Page, chromium, firefox, webkit } from 'playwright';
5
5
 
6
+ /** Anything that can resolve to a click/move point. */
7
+ type MouseTarget = Locator | string | Point;
8
+
9
+ /** Values accepted by {@link executeSelectOption} — the Playwright `selectOption` shape. */
10
+ type SelectOptionValues = Parameters<Locator['selectOption']>[0];
11
+ /** Files accepted by {@link executeUpload} — the Playwright `setInputFiles` shape. */
12
+ type UploadFiles = Parameters<Locator['setInputFiles']>[0];
13
+
6
14
  /**
7
15
  * Modifier tokens accepted in a `human.press()` chord. `Mod` and `CmdOrCtrl` /
8
16
  * `CommandOrControl` are the magic auto-mapping tokens (Meta on Mac,
@@ -73,8 +81,21 @@ interface PressResult {
73
81
  readonly dispatched: string;
74
82
  }
75
83
 
76
- /** Anything that can resolve to a click/move point. */
77
- type MouseTarget = Locator | string | Point;
84
+ /** Options for {@link installMouseHelper}. */
85
+ interface InstallMouseHelperOptions {
86
+ /** Cursor fill color. Defaults to the HumanJS amber `#f5a55c`. */
87
+ readonly color?: string;
88
+ /** Cursor visual size in pixels. Defaults to 22. */
89
+ readonly size?: number;
90
+ /**
91
+ * Render a ripple at each `mousedown` position so clicks read on video.
92
+ * Defaults to `true`.
93
+ */
94
+ readonly showClicks?: boolean;
95
+ /** Halo opacity behind the cursor. Defaults to `0.18`. */
96
+ readonly haloOpacity?: number;
97
+ }
98
+ declare function installMouseHelper(target: BrowserContext | Page, options?: InstallMouseHelperOptions): Promise<void>;
78
99
 
79
100
  /**
80
101
  * What to read:
@@ -163,6 +184,12 @@ interface CaptureResult {
163
184
  cleanup(): Promise<void>;
164
185
  }
165
186
 
187
+ /**
188
+ * Generates a standalone, runnable HumanJS script that replays the recorded
189
+ * session. String selectors round-trip verbatim; raw coordinates and
190
+ * un-captured inputs are emitted with a flag so they're easy to fix up.
191
+ */
192
+ declare function generateHumanJS(timeline: Timeline): string;
166
193
  /** Options for {@link generatePlaywrightTest} / `Recording.toPlaywright`. */
167
194
  interface PlaywrightTestOptions {
168
195
  /**
@@ -184,6 +211,15 @@ interface PlaywrightTestOptions {
184
211
  */
185
212
  readonly baseUrl?: boolean;
186
213
  }
214
+ /**
215
+ * Generates a `@playwright/test` spec that replays the session through
216
+ * HumanJS — a humanized test, not raw Playwright, since the humanization is
217
+ * the point. Uses the `@humanjs/playwright/test` fixture for the `human`
218
+ * (recorded personality / seed / speed applied via `test.use({ humanOptions })`),
219
+ * runs instant in CI / recorded speed locally, drops timing `sleep()`s by
220
+ * default, and derives the assertions it safely can.
221
+ */
222
+ declare function generatePlaywrightTest(timeline: Timeline, options?: PlaywrightTestOptions): string;
187
223
 
188
224
  /**
189
225
  * Encoding quality preset. Picks the per-frame capture quality + the
@@ -458,22 +494,15 @@ interface ScrollResult {
458
494
  readonly durationMs: number;
459
495
  }
460
496
 
461
- /** Options for {@link installMouseHelper}. */
462
- interface InstallMouseHelperOptions {
463
- /** Cursor fill color. Defaults to the HumanJS amber `#f5a55c`. */
464
- readonly color?: string;
465
- /** Cursor visual size in pixels. Defaults to 22. */
466
- readonly size?: number;
497
+ /** Options for {@link Human.selectText}. */
498
+ interface SelectTextOptions {
467
499
  /**
468
- * Render a ripple at each `mousedown` position so clicks read on video.
469
- * Defaults to `true`.
500
+ * Select only this substring of the element's text instead of all of it.
501
+ * Located inside the element whitespace-tolerantly (first match); falls back
502
+ * to selecting the whole element when not found.
470
503
  */
471
- readonly showClicks?: boolean;
472
- /** Halo opacity behind the cursor. Defaults to `0.18`. */
473
- readonly haloOpacity?: number;
504
+ text?: string;
474
505
  }
475
- declare function installMouseHelper(target: BrowserContext | Page, options?: InstallMouseHelperOptions): Promise<void>;
476
-
477
506
  /**
478
507
  * How fast the humanized session runs.
479
508
  * - `'human'` — full humanization (default)
@@ -491,6 +520,14 @@ interface CreateHumanOptions {
491
520
  readonly speed?: Speed;
492
521
  /** Plugins installed on this session, invoked in registration order. */
493
522
  readonly plugins?: readonly HumanPlugin[];
523
+ /**
524
+ * Visual cursor overlay ({@link installMouseHelper}) so humanized motion is
525
+ * visible in headed runs and recordings. **On by default.** Pass `false` to
526
+ * opt out — do this for `speed: 'instant'` / CI, where there's no motion to
527
+ * show and the injected cursor would land in test DOM and screenshots. Pass
528
+ * an options object to style it (color, size, …).
529
+ */
530
+ readonly cursor?: boolean | InstallMouseHelperOptions;
494
531
  /**
495
532
  * Starting cursor position used as the origin of the first humanized path.
496
533
  * Defaults to `{ x: 0, y: 0 }`. Set this if you've already moved the cursor
@@ -536,6 +573,17 @@ interface Human {
536
573
  * `mouse.click({ button: 'right' })` at the coordinates.
537
574
  */
538
575
  rightClick(target: MouseTarget): Promise<void>;
576
+ /**
577
+ * Double-click `target`. Identical humanized approach to `click()` — same
578
+ * Bezier path, hover dwell, and occasional near-miss — but the final
579
+ * dispatch is a double-click (two presses within the OS double-click
580
+ * window). Accepts the same selector / `Locator` / `Point` targets.
581
+ *
582
+ * In `speed: 'instant'`, element targets fall back to
583
+ * `locator.click({ clickCount: 2 })`; a `Point` dispatches
584
+ * `mouse.click(x, y, { clickCount: 2 })`.
585
+ */
586
+ doubleClick(target: MouseTarget): Promise<void>;
539
587
  /**
540
588
  * Move the cursor to `target` along a humanized Bezier path and settle
541
589
  * on it — no click is dispatched. Useful for hover-triggered UI
@@ -602,6 +650,87 @@ interface Human {
602
650
  * by nature.
603
651
  */
604
652
  paste(target: Locator | string, value: string): Promise<void>;
653
+ /**
654
+ * Clear a text field `target` (input, textarea, or contenteditable) with a
655
+ * humanized gesture: click to focus, **select-all**, a beat, then **delete**
656
+ * — the real keyboard motion a person uses to wipe a field before retyping,
657
+ * not a silent value reset. Fires the keydown/up + `input` events the page
658
+ * expects.
659
+ *
660
+ * Pair with `type()` to edit an existing value:
661
+ * `await human.clear('#name'); await human.type('#name', 'New');`
662
+ *
663
+ * In `speed: 'instant'`, delegates to Playwright's native `locator.clear()`.
664
+ */
665
+ clear(target: Locator | string): Promise<void>;
666
+ /**
667
+ * Tick a checkbox or radio `target`. Moves the cursor to the control and
668
+ * clicks it with the same humanized motion as `click()` — but only when
669
+ * needed: if it already reports checked, no click fires (a real user
670
+ * doesn't re-click a box that's already ticked). The resulting state is
671
+ * verified; trying to `check` something that won't toggle throws.
672
+ *
673
+ * `target` is element-bound (selector or `Locator`). In `speed: 'instant'`,
674
+ * delegates to Playwright's native `locator.check()`.
675
+ */
676
+ check(target: Locator | string): Promise<void>;
677
+ /**
678
+ * Untick a checkbox `target`. Mirror of `check()` — humanized click only if
679
+ * currently checked, with state verification afterward. Radios can't be
680
+ * unchecked by clicking (select a different option instead); attempting it
681
+ * throws a clear error.
682
+ *
683
+ * In `speed: 'instant'`, delegates to `locator.uncheck()`.
684
+ */
685
+ uncheck(target: Locator | string): Promise<void>;
686
+ /**
687
+ * Choose option(s) in a native `<select>` `target`. The cursor moves to the
688
+ * dropdown and settles on it (humanized), then the value is set — native
689
+ * selects open an OS menu automation can't drive visually, so the *approach*
690
+ * is humanized while the choice itself is set programmatically (firing
691
+ * `input`/`change`), exactly as Playwright does. For custom DOM dropdowns,
692
+ * drive the rendered options with `click` instead.
693
+ *
694
+ * `values` takes the Playwright `selectOption` shape — a value string, an
695
+ * array of values, or `{ value | label | index }`. Returns the option
696
+ * values that ended up selected.
697
+ *
698
+ * In `speed: 'instant'`, sets the value with no cursor motion.
699
+ */
700
+ selectOption(target: Locator | string, values: SelectOptionValues): Promise<string[]>;
701
+ /**
702
+ * Select text inside `target` (a paragraph, heading, input, …). The cursor
703
+ * moves to the element (humanized), then the text is highlighted — the
704
+ * "select this" gesture before copying, replacing, or triggering a highlight
705
+ * menu.
706
+ *
707
+ * By default the element's whole text is selected. Pass `{ text }` to select
708
+ * just that substring: HumanJS finds it inside the element (whitespace-
709
+ * tolerant, mapped to exact offsets, first match) and selects only that
710
+ * range — so a recorded partial highlight reproduces as itself, not the whole
711
+ * element. If the text can't be located, it falls back to selecting all of
712
+ * the element.
713
+ *
714
+ * `target` is element-bound (selector or `Locator`). In `speed: 'instant'`
715
+ * the cursor motion is skipped; the selection is still applied.
716
+ */
717
+ selectText(target: Locator | string, options?: SelectTextOptions): Promise<void>;
718
+ /**
719
+ * Attach file(s) to a file-input `target`. The cursor moves to the control
720
+ * (visible in recordings / the overlay), then the files are attached via
721
+ * `setInputFiles`. Unlike a real click this never opens the OS file dialog
722
+ * (which would hang) — files are set directly, the way Playwright models
723
+ * uploads.
724
+ *
725
+ * `target` should be the `<input type="file">`. For the common hidden-input-
726
+ * behind-a-styled-button pattern there's no visible control to approach, so
727
+ * the motion is skipped and the files are attached directly. `files` takes
728
+ * the Playwright `setInputFiles` shape (a path, an array of paths, or
729
+ * in-memory `{ name, mimeType, buffer }` payloads).
730
+ *
731
+ * In `speed: 'instant'`, attaches the files with no cursor motion.
732
+ */
733
+ upload(target: Locator | string, files: UploadFiles): Promise<void>;
605
734
  /**
606
735
  * Press a single key (`'Tab'`, `'Enter'`, `'Escape'`, `'ArrowDown'`, …)
607
736
  * or a keyboard chord (`'Mod+S'`, `'Cmd+Shift+P'`, `'Ctrl+C'`, …).
@@ -759,6 +888,22 @@ interface Human {
759
888
  * Not a humanized action: no plugin events fire.
760
889
  */
761
890
  content(): Promise<string>;
891
+ /**
892
+ * Accessibility-tree **outline** of the page (or a region) — every
893
+ * interactive element and landmark by its ARIA role + accessible name,
894
+ * rendered as compact YAML (Playwright's `ariaSnapshot`). The most
895
+ * token-efficient way for an AI agent to see what's actionable and pick a
896
+ * selector: the names map directly to `getByRole` / accessible-name
897
+ * selectors, which HumanJS already favors.
898
+ *
899
+ * Prefer this over {@link Human.content} when the question is "what can I
900
+ * click / fill"; reach for {@link Human.screenshot} when you need the
901
+ * visual layout. Pass `target` to scope the outline to a region.
902
+ *
903
+ * Not a humanized action: no plugin events fire. Requires Playwright ≥ 1.49
904
+ * (when `ariaSnapshot` landed).
905
+ */
906
+ outline(target?: Locator | string): Promise<string>;
762
907
  /**
763
908
  * Current URL of the page. Forwards to `page.url()`. Synchronous return
764
909
  * because Playwright's underlying API is sync.
@@ -886,4 +1031,4 @@ interface HumanRecordOptions {
886
1031
  */
887
1032
  declare function createHuman(page: Page, options?: CreateHumanOptions): Promise<Human>;
888
1033
 
889
- 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 };
1034
+ 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 SelectOptionValues, type SelectTextOptions, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, type UploadFiles, createHuman, generateHumanJS, generatePlaywrightTest, installMouseHelper };