@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/README.md +22 -0
- package/dist/chunk-3TXDODCO.js +1997 -0
- package/dist/chunk-3TXDODCO.js.map +1 -0
- package/dist/chunk-3X36PFTS.cjs +2082 -0
- package/dist/chunk-3X36PFTS.cjs.map +1 -0
- package/dist/index.cjs +45 -1785
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +161 -16
- package/dist/index.d.ts +161 -16
- package/dist/index.js +1 -1759
- package/dist/index.js.map +1 -1
- package/dist/test.cjs +29 -0
- package/dist/test.cjs.map +1 -0
- package/dist/test.d.cts +32 -0
- package/dist/test.d.ts +32 -0
- package/dist/test.js +24 -0
- package/dist/test.js.map +1 -0
- package/package.json +28 -4
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
|
-
/**
|
|
77
|
-
|
|
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
|
|
462
|
-
interface
|
|
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
|
-
*
|
|
469
|
-
*
|
|
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
|
-
|
|
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
|
-
/**
|
|
77
|
-
|
|
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
|
|
462
|
-
interface
|
|
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
|
-
*
|
|
469
|
-
*
|
|
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
|
-
|
|
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 };
|