Files
wehub-resource-sync 0af812490d
CI / python (push) Failing after 0s
CI / javascript (push) Failing after 1s
CI / dotnet (push) Failing after 1s
chore: import upstream snapshot with attribution
2026-07-13 12:12:36 +08:00

1602 lines
61 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { describe, it, expect, vi } from "vitest";
import { resolveConfig, rand, randRange, sleep } from "../src/human/config.js";
import { humanMove, humanClick, clickTarget, humanIdle } from "../src/human/mouse.js";
import { patchPageElementHandles } from "../src/human/elementhandle.js";
// =========================================================================
// Config resolution
// =========================================================================
describe("resolveConfig", () => {
it("returns valid default config", () => {
const cfg = resolveConfig("default");
expect(cfg).toBeDefined();
expect(cfg.mouse_min_steps).toBeGreaterThan(0);
expect(cfg.mouse_max_steps).toBeGreaterThan(cfg.mouse_min_steps);
expect(cfg.typing_delay).toBeGreaterThan(0);
expect(cfg.initial_cursor_x).toHaveLength(2);
expect(cfg.initial_cursor_y).toHaveLength(2);
});
it("returns valid careful config with slower typing", () => {
const cfg = resolveConfig("careful");
const def = resolveConfig("default");
expect(cfg).toBeDefined();
expect(cfg.typing_delay).toBeGreaterThanOrEqual(def.typing_delay);
});
it("applies custom overrides", () => {
const cfg = resolveConfig("default", { mouse_min_steps: 100, mouse_max_steps: 200 });
expect(cfg.mouse_min_steps).toBe(100);
expect(cfg.mouse_max_steps).toBe(200);
});
it("preserves idle_between_actions override", () => {
const cfg = resolveConfig("default", {
idle_between_actions: true,
idle_between_duration: [50, 100],
});
expect(cfg.idle_between_actions).toBe(true);
expect(cfg.idle_between_duration[0]).toBe(50);
expect(cfg.idle_between_duration[1]).toBe(100);
});
it("throws on unknown preset name", () => {
expect(() => resolveConfig("nonexistent" as any)).toThrow(/Unknown humanize preset/);
});
it("returns all required fields including mistype", () => {
const cfg = resolveConfig("default");
const required = [
"mouse_min_steps", "mouse_max_steps", "typing_delay",
"initial_cursor_x", "initial_cursor_y", "idle_between_actions",
"idle_between_duration", "field_switch_delay",
"mistype_chance", "mistype_delay_notice", "mistype_delay_correct",
];
for (const f of required) {
expect(cfg).toHaveProperty(f);
}
});
it("mistype_delay fields are [min, max] tuples", () => {
const cfg = resolveConfig("default");
expect(Array.isArray(cfg.mistype_delay_notice)).toBe(true);
expect(cfg.mistype_delay_notice).toHaveLength(2);
expect(cfg.mistype_delay_notice[0]).toBeLessThanOrEqual(cfg.mistype_delay_notice[1]);
expect(Array.isArray(cfg.mistype_delay_correct)).toBe(true);
expect(cfg.mistype_delay_correct).toHaveLength(2);
expect(cfg.mistype_delay_correct[0]).toBeLessThanOrEqual(cfg.mistype_delay_correct[1]);
});
});
// =========================================================================
// rand / randRange / sleep
// =========================================================================
describe("rand helpers", () => {
it("rand stays within bounds over many iterations", () => {
for (let i = 0; i < 500; i++) {
const v = rand(10, 20);
expect(v).toBeGreaterThanOrEqual(10);
expect(v).toBeLessThanOrEqual(20);
}
});
it("randRange stays within bounds", () => {
for (let i = 0; i < 500; i++) {
const v = randRange([5, 15]);
expect(v).toBeGreaterThanOrEqual(5);
expect(v).toBeLessThanOrEqual(15);
}
});
it("sleep pauses for approximately correct duration", async () => {
const t0 = Date.now();
await sleep(50);
const elapsed = Date.now() - t0;
expect(elapsed).toBeGreaterThanOrEqual(40);
expect(elapsed).toBeLessThan(200);
});
});
// =========================================================================
// Bézier mouse movement (behavioral with vi.fn mocks)
// =========================================================================
describe("humanMove", () => {
function makeFakeRaw() {
const moves: Array<{ x: number; y: number }> = [];
return {
raw: {
move: vi.fn(async (x: number, y: number) => { moves.push({ x, y }); }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
},
moves,
};
}
it("generates multiple intermediate points", async () => {
const cfg = resolveConfig("default");
const { raw, moves } = makeFakeRaw();
await humanMove(raw, 0, 0, 500, 300, cfg);
expect(moves.length).toBeGreaterThanOrEqual(10);
const last = moves[moves.length - 1];
expect(Math.abs(last.x - 500)).toBeLessThan(10);
expect(Math.abs(last.y - 300)).toBeLessThan(10);
});
it("raw.move called exactly once per step", async () => {
const cfg = resolveConfig("default");
const { raw, moves } = makeFakeRaw();
await humanMove(raw, 0, 0, 400, 400, cfg);
expect(raw.move).toHaveBeenCalledTimes(moves.length);
});
it("no single jump exceeds 50% of total distance", async () => {
const cfg = resolveConfig("default");
const { raw, moves } = makeFakeRaw();
await humanMove(raw, 0, 0, 400, 400, cfg);
const totalDist = Math.sqrt(400 ** 2 + 400 ** 2);
const maxJump = totalDist * 0.5;
for (let i = 1; i < moves.length; i++) {
const dx = moves[i].x - moves[i - 1].x;
const dy = moves[i].y - moves[i - 1].y;
expect(Math.sqrt(dx * dx + dy * dy)).toBeLessThan(maxJump);
}
});
it("produces curved path (not a straight line)", async () => {
const cfg = resolveConfig("default");
let maxDev = 0;
for (let trial = 0; trial < 10; trial++) {
const { raw, moves } = makeFakeRaw();
await humanMove(raw, 0, 0, 500, 0, cfg);
const dev = Math.max(...moves.map(m => Math.abs(m.y)));
if (dev > maxDev) maxDev = dev;
}
expect(maxDev).toBeGreaterThan(0.5);
});
it("handles very short distances", async () => {
const cfg = resolveConfig("default");
const { raw, moves } = makeFakeRaw();
await humanMove(raw, 100, 100, 103, 102, cfg);
expect(moves.length).toBeGreaterThanOrEqual(1);
});
it("handles zero distance without crashing", async () => {
const cfg = resolveConfig("default");
const { raw } = makeFakeRaw();
await humanMove(raw, 200, 200, 200, 200, cfg);
// Completes without error; may or may not call move (both valid)
expect(true).toBe(true);
});
});
// =========================================================================
// humanClick behavioral
// =========================================================================
describe("humanClick", () => {
it("calls down then up in correct order", async () => {
const cfg = resolveConfig("default");
const callOrder: string[] = [];
const raw = {
move: vi.fn(async () => { }),
down: vi.fn(async () => { callOrder.push("down"); }),
up: vi.fn(async () => { callOrder.push("up"); }),
wheel: vi.fn(async () => { }),
};
await humanClick(raw, false, cfg);
expect(raw.down).toHaveBeenCalledTimes(1);
expect(raw.up).toHaveBeenCalledTimes(1);
expect(callOrder).toEqual(["down", "up"]);
});
});
// =========================================================================
// humanIdle behavioral
// =========================================================================
describe("humanIdle", () => {
it("calls raw.move at least once during idle", async () => {
const cfg = resolveConfig("default");
const raw = {
move: vi.fn(async () => { }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
};
await humanIdle(raw, 100, 100, cfg);
expect(raw.move).toHaveBeenCalled();
}, 15000);
});
// =========================================================================
// clickTarget
// =========================================================================
describe("clickTarget", () => {
it("returns point within bounding box", () => {
const cfg = resolveConfig("default");
const box = { x: 100, y: 200, width: 150, height: 40 };
for (let i = 0; i < 100; i++) {
const t = clickTarget(box, false, cfg);
expect(t.x).toBeGreaterThanOrEqual(100);
expect(t.x).toBeLessThanOrEqual(250);
expect(t.y).toBeGreaterThanOrEqual(200);
expect(t.y).toBeLessThanOrEqual(240);
}
});
it("isInput=true biases click toward left side of box", () => {
const cfg = resolveConfig("default");
const box = { x: 50, y: 50, width: 200, height: 30 };
let sumX = 0;
const N = 300;
for (let i = 0; i < N; i++) {
const t = clickTarget(box, true, cfg);
expect(t.x).toBeGreaterThanOrEqual(50);
expect(t.x).toBeLessThanOrEqual(250);
sumX += t.x;
}
const avgX = sumX / N;
expect(avgX).toBeLessThan(175);
});
it("does not crash with 1x1 box", () => {
const cfg = resolveConfig("default");
const t = clickTarget({ x: 0, y: 0, width: 1, height: 1 }, false, cfg);
expect(t.x).toBeGreaterThanOrEqual(0);
expect(t.x).toBeLessThanOrEqual(1);
});
});
// =========================================================================
// patchPage behavioral: fill uses platform SELECT_ALL
// =========================================================================
describe("patchPage fill", () => {
it("fill calls keyboard.press with platform-correct select-all", async () => {
const { patchPage } = await import("../src/human/index.js");
const pressedKeys: string[] = [];
const page = buildMockPage({
keyboardPress: async (key: string) => { pressedKeys.push(key); },
});
const cfg = resolveConfig("default");
const cursor = { x: 0, y: 0, initialized: false };
patchPage(page as any, cfg, cursor as any);
try { await (page as any).fill("input#name", "hello", { timeout: 2000 }); } catch (_) { }
const expected = process.platform === "darwin" ? "Meta+a" : "Control+a";
const wrong = process.platform === "darwin" ? "Control+a" : "Meta+a";
if (pressedKeys.length > 0) {
expect(pressedKeys).toContain(expected);
expect(pressedKeys).not.toContain(wrong);
}
}, 5000);
});
// =========================================================================
// patchPage behavioral: check/uncheck with idle_between_actions
// =========================================================================
describe("patchPage check/uncheck idle", () => {
it("check with idle=true calls humanClickFn and does not crash on idle", async () => {
const { patchPage } = await import("../src/human/index.js");
let downCalled = false;
const page = buildMockPage({
isChecked: async () => false,
evaluate: async () => ({ hit: true }),
});
page.mouse.down = vi.fn(async () => { downCalled = true; });
const cfg = resolveConfig("default", {
idle_between_actions: true,
idle_between_duration: [0.01, 0.02],
});
const cursor = { x: 100, y: 100, initialized: true };
patchPage(page as any, cfg, cursor as any);
try { await (page as any).check("input#cb", { timeout: 2000 }); } catch (_) { }
// humanCheckFn → humanIdle → humanClickFn → humanClick → raw.down
expect(downCalled).toBe(true);
}, 30000);
it("uncheck with idle=true calls humanClickFn and does not crash on idle", async () => {
const { patchPage } = await import("../src/human/index.js");
let downCalled = false;
const page = buildMockPage({
isChecked: async () => true,
evaluate: async () => ({ hit: true }),
});
page.mouse.down = vi.fn(async () => { downCalled = true; });
const cfg = resolveConfig("default", {
idle_between_actions: true,
idle_between_duration: [0.01, 0.02],
});
const cursor = { x: 100, y: 100, initialized: true };
patchPage(page as any, cfg, cursor as any);
try { await (page as any).uncheck("input#cb", { timeout: 2000 }); } catch (e: any) {
console.error("UNCHECK ERROR:", e?.message?.slice(0, 200));
}
expect(downCalled).toBe(true);
}, 30000);
it("config with idle=true is accepted by resolveConfig", () => {
const cfg = resolveConfig("default", {
idle_between_actions: true,
idle_between_duration: [5, 10],
});
expect(cfg.idle_between_actions).toBe(true);
expect(cfg.idle_between_duration).toEqual([5, 10]);
});
});
// =========================================================================
// patchPage behavioral: press focus check
// =========================================================================
describe("patchPage press focus", () => {
it("press clicks element when NOT focused (mouse.down called)", async () => {
const { patchPage } = await import("../src/human/index.js");
let downCount = 0;
const page = buildMockPage({
evaluate: async (expr: string) => {
if (typeof expr === 'string' && expr.includes('elementFromPoint')) return { hit: true };
return false;
},
});
// Intercept mouse.down before patching so raw captures it
page.mouse.down = vi.fn(async () => { downCount++; });
const cfg = resolveConfig("default");
const cursor = { x: 50, y: 50, initialized: true };
patchPage(page as any, cfg, cursor as any);
try { await (page as any).press("input#field", "Enter", { timeout: 2000 }); } catch (_) { }
expect(downCount).toBeGreaterThan(0);
});
it("press skips click when element IS focused (no mouse.down)", async () => {
const { patchPage } = await import("../src/human/index.js");
let downCount = 0;
const page = buildMockPage({
evaluate: async () => true,
});
page.mouse.down = vi.fn(async () => { downCount++; });
const cfg = resolveConfig("default");
const cursor = { x: 50, y: 50, initialized: true };
patchPage(page as any, cfg, cursor as any);
try { await (page as any).press("input#field", "Enter", { timeout: 2000 }); } catch (_) { }
expect(downCount).toBe(0);
});
});
// =========================================================================
// patchPage behavioral: frame patching
// =========================================================================
describe("patchPage frame patching", () => {
it("patches child frames with _humanPatched flag", async () => {
const { patchPage } = await import("../src/human/index.js");
const childFrame = buildMockFrame();
const mainFrame = {
...buildMockFrame(),
childFrames: vi.fn(() => [childFrame]),
};
const page = buildMockPage({ mainFrameReturn: mainFrame });
const cfg = resolveConfig("default");
const cursor = { x: 0, y: 0, initialized: false };
patchPage(page as any, cfg, cursor as any);
expect((childFrame as any)._humanPatched).toBe(true);
});
it("uses frame.locator for frame.click instead of page.click", async () => {
const { patchPage } = await import("../src/human/index.js");
const childFrame = buildMockFrame();
const mainFrame = {
...buildMockFrame(),
childFrames: vi.fn(() => [childFrame]),
};
const page = buildMockPage({ mainFrameReturn: mainFrame });
const originalPageClick = page.click;
const cfg = resolveConfig("default", { mouse_min_steps: 1, mouse_max_steps: 1 });
const cursor = { x: 0, y: 0, initialized: true };
patchPage(page as any, cfg, cursor as any);
await (childFrame as any).click("button.submit", { timeout: 1234 });
expect(childFrame.locator).toHaveBeenCalledWith("button.submit");
expect(originalPageClick).not.toHaveBeenCalled();
});
it.each([
["type", async (frame: any) => frame.type("input.email", "@")],
["fill", async (frame: any) => frame.fill("input.email", "@")],
["pressSequentially", async (frame: any) => frame.pressSequentially("input.email", "@")],
])("passes the page CDP session to frame.%s", async (_name, runFrameAction) => {
const { patchPage } = await import("../src/human/index.js");
const cdpSend = vi.fn(async () => ({}));
const childFrame = buildMockFrame();
const mainFrame = {
...buildMockFrame(),
childFrames: vi.fn(() => [childFrame]),
};
const page = buildMockPage({ mainFrameReturn: mainFrame });
page.context = vi.fn(() => ({
pages: vi.fn(() => []),
addInitScript: vi.fn(async () => {}),
newCDPSession: vi.fn(async () => ({ send: cdpSend })),
}));
const cfg = resolveConfig("default", {
field_switch_delay: [0, 0],
key_hold: [0, 0],
shift_down_delay: [0, 0],
shift_up_delay: [0, 0],
typing_delay: 0,
typing_delay_spread: 0,
typing_pause_chance: 0,
mistype_chance: 0,
mouse_min_steps: 1,
mouse_max_steps: 1,
idle_between_actions: false,
});
const cursor = { x: 0, y: 0, initialized: true };
patchPage(page as any, cfg, cursor as any);
await runFrameAction(childFrame);
const dispatches = cdpSend.mock.calls.filter(([method]) => method === "Input.dispatchKeyEvent");
expect(dispatches).toHaveLength(2);
expect(page.evaluate).not.toHaveBeenCalled();
});
});
// =========================================================================
// Mistype config
// =========================================================================
describe("mistype config", () => {
it("default config has valid mistype fields", () => {
const cfg = resolveConfig("default");
expect(typeof cfg.mistype_chance).toBe("number");
expect(cfg.mistype_chance).toBeGreaterThanOrEqual(0);
expect(cfg.mistype_chance).toBeLessThanOrEqual(1);
// mistype_delay_notice and mistype_delay_correct are [min, max] tuples
expect(Array.isArray(cfg.mistype_delay_notice)).toBe(true);
expect(cfg.mistype_delay_notice).toHaveLength(2);
expect(Array.isArray(cfg.mistype_delay_correct)).toBe(true);
expect(cfg.mistype_delay_correct).toHaveLength(2);
});
it("mistype_chance can be overridden to 0 (disabled)", () => {
const cfg = resolveConfig("default", { mistype_chance: 0 });
expect(cfg.mistype_chance).toBe(0);
});
it("mistype_chance can be overridden to higher value", () => {
const cfg = resolveConfig("default", { mistype_chance: 0.15 });
expect(cfg.mistype_chance).toBe(0.15);
});
});
// =========================================================================
// Module exports
// =========================================================================
describe("module exports", () => {
it("patchBrowser, patchContext, patchPage are all exported functions", async () => {
const mod = await import("../src/human/index.js");
expect(typeof mod.patchBrowser).toBe("function");
expect(typeof mod.patchContext).toBe("function");
expect(typeof mod.patchPage).toBe("function");
});
it("humanMove, humanClick, clickTarget, humanIdle are exported", async () => {
const mod = await import("../src/human/index.js");
expect(typeof mod.humanMove).toBe("function");
expect(typeof mod.humanClick).toBe("function");
expect(typeof mod.clickTarget).toBe("function");
expect(typeof mod.humanIdle).toBe("function");
});
it("resolveConfig is re-exported from index", async () => {
const mod = await import("../src/human/index.js");
expect(typeof mod.resolveConfig).toBe("function");
});
});
// =========================================================================
// patchBrowser on CDP-connected browser (issue #126)
// =========================================================================
describe("patchBrowser CDP-connected workflow", () => {
it("patches existing pages on a browser with pre-existing contexts", async () => {
const { patchBrowser, resolveConfig } = await import("../src/human/index.js");
// Simulate a CDP-connected browser: it already has contexts and pages
const page = buildMockPage();
const context: any = {
pages: vi.fn(() => [page]),
on: vi.fn(),
newPage: vi.fn(async () => buildMockPage()),
addInitScript: vi.fn(async () => { }),
};
const browser: any = {
contexts: vi.fn(() => [context]),
newContext: vi.fn(async () => context),
newPage: vi.fn(async () => page),
};
const cfg = resolveConfig("default");
patchBrowser(browser, cfg);
// page should now have _original (proof it was patched)
expect((page as any)._original).toBeDefined();
expect((page as any)._original.click).toBeTypeOf("function");
expect((page as any)._original.fill).toBeTypeOf("function");
expect((page as any)._humanCfg).toBe(cfg);
});
it("patched click calls mouse.down (humanized path, not original)", async () => {
const { patchBrowser, resolveConfig } = await import("../src/human/index.js");
let downCalled = false;
const page = buildMockPage();
page.mouse.down = vi.fn(async () => { downCalled = true; });
const context: any = {
pages: vi.fn(() => [page]),
on: vi.fn(),
newPage: vi.fn(async () => buildMockPage()),
addInitScript: vi.fn(async () => { }),
};
const browser: any = {
contexts: vi.fn(() => [context]),
newContext: vi.fn(async () => context),
newPage: vi.fn(async () => page),
};
patchBrowser(browser, resolveConfig("default"));
// Click through the patched method — should go through humanize path
try { await (page as any).click("button", { timeout: 2000 }); } catch (_) { }
expect(downCalled).toBe(true);
}, 30000);
it("new contexts created after patchBrowser are also patched", async () => {
const { patchBrowser, resolveConfig } = await import("../src/human/index.js");
const newPage = buildMockPage();
const newContext: any = {
pages: vi.fn(() => [newPage]),
on: vi.fn(),
newPage: vi.fn(async () => buildMockPage()),
addInitScript: vi.fn(async () => { }),
};
const browser: any = {
contexts: vi.fn(() => []),
newContext: vi.fn(async () => newContext),
newPage: vi.fn(async () => newPage),
};
patchBrowser(browser, resolveConfig("default"));
// Create a new context via the patched newContext
const ctx = await browser.newContext();
// Pages in the new context should be patched
expect((newPage as any)._original).toBeDefined();
});
});
// =========================================================================
// Test helpers
// =========================================================================
function buildMockPage(overrides: Record<string, any> = {}): any {
const mainFrameObj = overrides.mainFrameReturn ?? {
childFrames: vi.fn(() => []),
click: vi.fn(async () => { }),
dblclick: vi.fn(async () => { }),
hover: vi.fn(async () => { }),
type: vi.fn(async () => { }),
fill: vi.fn(async () => { }),
check: vi.fn(async () => { }),
uncheck: vi.fn(async () => { }),
selectOption: vi.fn(async () => { }),
press: vi.fn(async () => { }),
clear: vi.fn(async () => { }),
dragAndDrop: vi.fn(async () => { }),
locator: vi.fn(() => {
const frameLoc: any = {
boundingBox: vi.fn(async () => ({ x: 0, y: 0, width: 100, height: 30 })),
waitFor: vi.fn(async () => {}),
isVisible: vi.fn(async () => true),
isEnabled: vi.fn(async () => true),
isEditable: vi.fn(async () => true),
evaluate: vi.fn(async () => ({ hit: true })),
};
frameLoc.first = vi.fn(() => frameLoc);
return frameLoc;
}),
};
const makeLocator = () => {
const loc: any = {
boundingBox: vi.fn(async () => ({ x: 100, y: 300, width: 200, height: 30 })),
scrollIntoViewIfNeeded: vi.fn(async () => { }),
isChecked: overrides.isChecked ?? vi.fn(async () => false),
waitFor: vi.fn(async () => {}),
isVisible: vi.fn(async () => true),
isEnabled: vi.fn(async () => true),
isEditable: vi.fn(async () => true),
evaluate: vi.fn(async () => ({ hit: true })),
};
loc.first = vi.fn(() => loc);
return loc;
};
const page: any = {
evaluate: overrides.evaluate ?? vi.fn(async () => ({ hit: true })),
addInitScript: vi.fn(async () => { }),
mouse: {
move: vi.fn(async () => { }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
click: vi.fn(async () => { }),
dblclick: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
},
keyboard: {
press: overrides.keyboardPress
? vi.fn(overrides.keyboardPress)
: vi.fn(async () => { }),
type: vi.fn(async () => { }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
insertText: vi.fn(async () => { }),
},
click: vi.fn(async () => { }),
dblclick: vi.fn(async () => { }),
hover: vi.fn(async () => { }),
type: vi.fn(async () => { }),
fill: vi.fn(async () => { }),
check: vi.fn(async () => { }),
uncheck: vi.fn(async () => { }),
selectOption: vi.fn(async () => { }),
press: vi.fn(async () => { }),
goto: vi.fn(async () => ({})),
isChecked: overrides.isChecked ?? vi.fn(async () => false),
locator: vi.fn(() => makeLocator()),
viewportSize: vi.fn(() => ({ width: 1280, height: 720 })),
mainFrame: vi.fn(() => mainFrameObj),
frames: vi.fn(() => []),
context: vi.fn(() => ({
pages: vi.fn(() => []),
addInitScript: vi.fn(async () => { }),
newCDPSession: vi.fn(async () => { throw new Error('no cdp'); }),
})),
url: vi.fn(() => "about:blank"),
waitForTimeout: vi.fn(async () => { }),
};
return page;
}
// =========================================================================
// humanType non-ASCII
// =========================================================================
describe("humanType non-ASCII", () => {
function makeRawKeyboardMock() {
const downKeys: string[] = [];
const insertedChars: string[] = [];
const raw = {
down: vi.fn(async (k: string) => { downKeys.push(k); }),
up: vi.fn(async () => { }),
type: vi.fn(async () => { }),
insertText: vi.fn(async (t: string) => { insertedChars.push(t); }),
};
return { raw, downKeys, insertedChars };
}
it("types Cyrillic via insertText, not down", async () => {
const { humanType } = await import("../src/human/keyboard.js");
const cfg = resolveConfig("default", { mistype_chance: 0 });
const { raw, downKeys, insertedChars } = makeRawKeyboardMock();
await humanType({} as any, raw, "Привет", cfg);
expect(insertedChars.join("")).toBe("Привет");
for (const k of downKeys) {
expect(k.charCodeAt(0)).toBeLessThan(128);
}
});
it("types mixed ASCII + Cyrillic correctly", async () => {
const { humanType } = await import("../src/human/keyboard.js");
const cfg = resolveConfig("default", { mistype_chance: 0 });
const { raw, downKeys, insertedChars } = makeRawKeyboardMock();
await humanType({} as any, raw, "Hi Мир", cfg);
expect(downKeys).toContain("H");
expect(downKeys).toContain("i");
expect(insertedChars.join("")).toContain("М");
expect(insertedChars.join("")).toContain("и");
expect(insertedChars.join("")).toContain("р");
});
it("types CJK via insertText", async () => {
const { humanType } = await import("../src/human/keyboard.js");
const cfg = resolveConfig("default", { mistype_chance: 0 });
const { raw, insertedChars } = makeRawKeyboardMock();
await humanType({} as any, raw, "你好", cfg);
expect(insertedChars.join("")).toBe("你好");
});
it("types emoji via insertText", async () => {
const { humanType } = await import("../src/human/keyboard.js");
const cfg = resolveConfig("default", { mistype_chance: 0 });
const { raw, insertedChars } = makeRawKeyboardMock();
await humanType({} as any, raw, "Hi 👋", cfg);
expect(insertedChars.join("")).toContain("👋");
});
it("mistype only triggers for ASCII, not Cyrillic", async () => {
const { humanType } = await import("../src/human/keyboard.js");
const cfg = resolveConfig("default", { mistype_chance: 1.0 });
const { raw, downKeys } = makeRawKeyboardMock();
await humanType({} as any, raw, "AБ", cfg);
expect(downKeys).toContain("Backspace");
});
});
// =========================================================================
// ElementHandle patching (Playwright)
// =========================================================================
function buildMockElementHandle(overrides: Record<string, any> = {}): any {
const el: any = {
click: vi.fn(async () => { }),
dblclick: vi.fn(async () => { }),
hover: vi.fn(async () => { }),
type: vi.fn(async () => { }),
fill: vi.fn(async () => { }),
press: vi.fn(async () => { }),
selectOption: vi.fn(async () => { }),
check: vi.fn(async () => { }),
uncheck: vi.fn(async () => { }),
setChecked: vi.fn(async () => { }),
tap: vi.fn(async () => { }),
focus: vi.fn(async () => { }),
boundingBox: overrides.boundingBox ?? vi.fn(async () => ({ x: 100, y: 100, width: 200, height: 30 })),
evaluate: overrides.evaluate ?? vi.fn(async () => ({ hit: true })),
isChecked: overrides.isChecked ?? vi.fn(async () => false),
waitForElementState: vi.fn(async () => {}),
$: vi.fn(async () => null),
$$: vi.fn(async () => []),
waitForSelector: vi.fn(async () => null),
_humanPatched: false,
};
return el;
}
describe("patchSingleElementHandle", () => {
it("marks element as patched", async () => {
const { patchSingleElementHandle } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default");
const cursor = { x: 100, y: 100, initialized: true };
const raw = {
move: vi.fn(async () => { }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
};
const rawKb = {
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
type: vi.fn(async () => { }),
insertText: vi.fn(async () => { }),
};
const originals = {
keyboardPress: vi.fn(async () => { }),
keyboardDown: vi.fn(async () => { }),
keyboardUp: vi.fn(async () => { }),
};
const el = buildMockElementHandle();
const page = buildMockPage();
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
expect(el._humanPatched).toBe(true);
});
it("el.click calls mouse.move and mouse.down/up (humanized path)", async () => {
const { patchSingleElementHandle } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default", { idle_between_actions: false });
const cursor = { x: 50, y: 50, initialized: true };
let moveCount = 0;
let downCalled = false;
let upCalled = false;
const raw = {
move: vi.fn(async () => { moveCount++; }),
down: vi.fn(async () => { downCalled = true; }),
up: vi.fn(async () => { upCalled = true; }),
wheel: vi.fn(async () => { }),
};
const rawKb = {
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
type: vi.fn(async () => { }),
insertText: vi.fn(async () => { }),
};
const originals = {
keyboardPress: vi.fn(async () => { }),
keyboardDown: vi.fn(async () => { }),
keyboardUp: vi.fn(async () => { }),
};
const el = buildMockElementHandle();
const page = buildMockPage();
(page as any)._ensureCursorInit = vi.fn(async () => { });
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
await el.click();
expect(moveCount).toBeGreaterThan(0);
expect(downCalled).toBe(true);
expect(upCalled).toBe(true);
}, 30000);
it("el.hover calls mouse.move but NOT down/up", async () => {
const { patchSingleElementHandle } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default", { idle_between_actions: false });
const cursor = { x: 50, y: 50, initialized: true };
let downCalled = false;
const raw = {
move: vi.fn(async () => { }),
down: vi.fn(async () => { downCalled = true; }),
up: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
};
const rawKb = {
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
type: vi.fn(async () => { }),
insertText: vi.fn(async () => { }),
};
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const el = buildMockElementHandle();
const page = buildMockPage();
(page as any)._ensureCursorInit = vi.fn(async () => { });
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
await el.hover();
expect(raw.move).toHaveBeenCalled();
expect(downCalled).toBe(false);
}, 30000);
it("el.type triggers mouse move + click + keyboard events", async () => {
const { patchSingleElementHandle } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default", { idle_between_actions: false, mistype_chance: 0 });
const cursor = { x: 50, y: 50, initialized: true };
const raw = {
move: vi.fn(async () => { }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
};
const rawKb = {
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
type: vi.fn(async () => { }),
insertText: vi.fn(async () => { }),
};
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const el = buildMockElementHandle({ evaluate: vi.fn(async (js: string) => js.includes('elementFromPoint') ? { hit: true } : true) });
const page = buildMockPage();
(page as any)._ensureCursorInit = vi.fn(async () => { });
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
await el.type("abc");
expect(raw.move).toHaveBeenCalled();
expect(raw.down).toHaveBeenCalled(); // click to focus
expect(rawKb.down).toHaveBeenCalled(); // keyboard typing
}, 30000);
it("el.fill calls selectAll + backspace + type", async () => {
const { patchSingleElementHandle } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default", { idle_between_actions: false, mistype_chance: 0 });
const cursor = { x: 50, y: 50, initialized: true };
const pressedKeys: string[] = [];
const raw = {
move: vi.fn(async () => { }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
};
const rawKb = {
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
type: vi.fn(async () => { }),
insertText: vi.fn(async () => { }),
};
const originals = {
keyboardPress: vi.fn(async (key: string) => { pressedKeys.push(key); }),
keyboardDown: vi.fn(async () => { }),
keyboardUp: vi.fn(async () => { }),
};
const el = buildMockElementHandle({ evaluate: vi.fn(async (js: string) => js.includes('elementFromPoint') ? { hit: true } : true) });
const page = buildMockPage();
(page as any)._ensureCursorInit = vi.fn(async () => { });
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
await el.fill("newtext");
const expected = process.platform === "darwin" ? "Meta+a" : "Control+a";
expect(pressedKeys).toContain(expected);
expect(pressedKeys).toContain("Backspace");
}, 30000);
it("no double patching", async () => {
const { patchSingleElementHandle } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default");
const cursor = { x: 0, y: 0, initialized: false };
const raw = { move: vi.fn(async () => { }), down: vi.fn(async () => { }), up: vi.fn(async () => { }), wheel: vi.fn(async () => { }) };
const rawKb = { down: vi.fn(async () => { }), up: vi.fn(async () => { }), type: vi.fn(async () => { }), insertText: vi.fn(async () => { }) };
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const el = buildMockElementHandle();
const page = buildMockPage();
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
const firstClick = el.click;
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
expect(el.click).toBe(firstClick);
});
it("nested $() returns patched child handle", async () => {
const { patchSingleElementHandle } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default");
const cursor = { x: 0, y: 0, initialized: false };
const raw = { move: vi.fn(async () => { }), down: vi.fn(async () => { }), up: vi.fn(async () => { }), wheel: vi.fn(async () => { }) };
const rawKb = { down: vi.fn(async () => { }), up: vi.fn(async () => { }), type: vi.fn(async () => { }), insertText: vi.fn(async () => { }) };
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const child = buildMockElementHandle();
const el = buildMockElementHandle();
el.$ = vi.fn(async () => child);
const page = buildMockPage();
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
const result = await el.$("span");
expect(result._humanPatched).toBe(true);
});
});
describe("patchPageElementHandles", () => {
it("page.$() returns patched ElementHandle", async () => {
const { patchPageElementHandles } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default");
const cursor = { x: 0, y: 0, initialized: false };
const raw = { move: vi.fn(async () => { }), down: vi.fn(async () => { }), up: vi.fn(async () => { }), wheel: vi.fn(async () => { }) };
const rawKb = { down: vi.fn(async () => { }), up: vi.fn(async () => { }), type: vi.fn(async () => { }), insertText: vi.fn(async () => { }) };
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const el = buildMockElementHandle();
const page = buildMockPage();
(page as any).$ = vi.fn(async () => el);
(page as any).$$ = vi.fn(async () => [el]);
(page as any).waitForSelector = vi.fn(async () => el);
patchPageElementHandles(page as any, cfg, cursor as any, raw, rawKb, originals, null);
const result = await (page as any).$("#test");
expect(result._humanPatched).toBe(true);
});
it("page.$$() returns all patched handles", async () => {
const { patchPageElementHandles } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default");
const cursor = { x: 0, y: 0, initialized: false };
const raw = { move: vi.fn(async () => { }), down: vi.fn(async () => { }), up: vi.fn(async () => { }), wheel: vi.fn(async () => { }) };
const rawKb = { down: vi.fn(async () => { }), up: vi.fn(async () => { }), type: vi.fn(async () => { }), insertText: vi.fn(async () => { }) };
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const el1 = buildMockElementHandle();
const el2 = buildMockElementHandle();
const page = buildMockPage();
(page as any).$ = vi.fn(async () => null);
(page as any).$$ = vi.fn(async () => [el1, el2]);
(page as any).waitForSelector = vi.fn(async () => null);
patchPageElementHandles(page as any, cfg, cursor as any, raw, rawKb, originals, null);
const results = await (page as any).$$("div");
expect(results[0]._humanPatched).toBe(true);
expect(results[1]._humanPatched).toBe(true);
});
it("page.waitForSelector() returns patched handle", async () => {
const { patchPageElementHandles } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default");
const cursor = { x: 0, y: 0, initialized: false };
const raw = { move: vi.fn(async () => { }), down: vi.fn(async () => { }), up: vi.fn(async () => { }), wheel: vi.fn(async () => { }) };
const rawKb = { down: vi.fn(async () => { }), up: vi.fn(async () => { }), type: vi.fn(async () => { }), insertText: vi.fn(async () => { }) };
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const el = buildMockElementHandle();
const page = buildMockPage();
(page as any).$ = vi.fn(async () => null);
(page as any).$$ = vi.fn(async () => []);
(page as any).waitForSelector = vi.fn(async () => el);
patchPageElementHandles(page as any, cfg, cursor as any, raw, rawKb, originals, null);
const result = await (page as any).waitForSelector("#test");
expect(result._humanPatched).toBe(true);
});
it("page.$() returns null when no element found (no crash)", async () => {
const { patchPageElementHandles } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default");
const cursor = { x: 0, y: 0, initialized: false };
const raw = { move: vi.fn(async () => { }), down: vi.fn(async () => { }), up: vi.fn(async () => { }), wheel: vi.fn(async () => { }) };
const rawKb = { down: vi.fn(async () => { }), up: vi.fn(async () => { }), type: vi.fn(async () => { }), insertText: vi.fn(async () => { }) };
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const page = buildMockPage();
(page as any).$ = vi.fn(async () => null);
(page as any).$$ = vi.fn(async () => []);
(page as any).waitForSelector = vi.fn(async () => null);
patchPageElementHandles(page as any, cfg, cursor as any, raw, rawKb, originals, null);
const result = await (page as any).$("#nonexistent");
expect(result).toBeNull();
});
});
describe("patchPage integrates ElementHandle patching", () => {
it("patchPage patches page.$ automatically", async () => {
const { patchPage } = await import("../src/human/index.js");
const el = buildMockElementHandle();
const page = buildMockPage();
(page as any).$ = vi.fn(async () => el);
(page as any).$$ = vi.fn(async () => []);
(page as any).waitForSelector = vi.fn(async () => null);
const cfg = resolveConfig("default");
const cursor = { x: 100, y: 100, initialized: true };
patchPage(page as any, cfg, cursor as any);
const result = await (page as any).$("#test");
expect(result._humanPatched).toBe(true);
});
});
function buildMockFrame(): any {
const locator: any = {
boundingBox: vi.fn(async () => ({ x: 0, y: 0, width: 100, height: 30 })),
scrollIntoViewIfNeeded: vi.fn(async () => {}),
evaluate: vi.fn(async () => ({ hit: true })),
isChecked: vi.fn(async () => false),
};
locator.first = vi.fn(() => locator);
return {
click: vi.fn(async () => { }),
dblclick: vi.fn(async () => { }),
hover: vi.fn(async () => { }),
type: vi.fn(async () => { }),
fill: vi.fn(async () => { }),
check: vi.fn(async () => { }),
uncheck: vi.fn(async () => { }),
selectOption: vi.fn(async () => { }),
press: vi.fn(async () => { }),
pressSequentially: vi.fn(async () => { }),
tap: vi.fn(async () => { }),
clear: vi.fn(async () => { }),
dragAndDrop: vi.fn(async () => { }),
locator: vi.fn(() => locator),
childFrames: vi.fn(() => []),
};
}
// =========================================================================
// mergeConfig
// =========================================================================
describe("mergeConfig", () => {
it("returns base unchanged when overrides is undefined/null", async () => {
const { mergeConfig, resolveConfig: rc } = await import("../src/human/config.js");
const base = rc("default");
expect(mergeConfig(base, undefined)).toBe(base);
expect(mergeConfig(base, null)).toBe(base);
});
it("creates a new object — base is never mutated", async () => {
const { mergeConfig, resolveConfig: rc } = await import("../src/human/config.js");
const base = rc("default");
const before = base.typing_delay;
const merged = mergeConfig(base, { typing_delay: 30 });
expect(merged.typing_delay).toBe(30);
expect(base.typing_delay).toBe(before);
expect(merged).not.toBe(base);
});
it("preserves non-overridden fields", async () => {
const { mergeConfig, resolveConfig: rc } = await import("../src/human/config.js");
const base = rc("default");
const merged = mergeConfig(base, { typing_delay: 30 });
expect(merged.mouse_min_steps).toBe(base.mouse_min_steps);
expect(merged.mistype_chance).toBe(base.mistype_chance);
});
});
// =========================================================================
// Per-call timeout forwarding (issue #137)
// =========================================================================
describe("page.click(selector, { timeout }) forwards timeout to scroll", () => {
it("scrollToElement passes timeout to locator.boundingBox()", async () => {
const { scrollToElement } = await import("../src/human/scroll.js");
const cfg = resolveConfig("default");
const boundingBox = vi.fn(async () => ({ x: 100, y: 200, width: 50, height: 30 }));
const page: any = {
viewportSize: () => ({ width: 1280, height: 720 }),
locator: vi.fn(() => ({ first: () => ({ boundingBox }) })),
};
const raw = {
move: vi.fn(async () => { }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
};
await scrollToElement(page, raw, "#x", 0, 0, cfg, 5000);
expect(boundingBox).toHaveBeenCalledWith({ timeout: 5000 });
});
it("default timeout matches Playwright's 30000ms when not specified", async () => {
const { scrollToElement } = await import("../src/human/scroll.js");
const cfg = resolveConfig("default");
const boundingBox = vi.fn(async () => ({ x: 100, y: 200, width: 50, height: 30 }));
const page: any = {
viewportSize: () => ({ width: 1280, height: 720 }),
locator: vi.fn(() => ({ first: () => ({ boundingBox }) })),
};
const raw = {
move: vi.fn(async () => { }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
};
await scrollToElement(page, raw, "#x", 0, 0, cfg);
expect(boundingBox).toHaveBeenCalledWith({ timeout: 30000 });
});
it("page.click({ timeout }) reaches scrollToElement", async () => {
const scrollMod = await import("../src/human/scroll.js");
const { patchPage } = await import("../src/human/index.js");
const cfg = resolveConfig("default", { idle_between_actions: false });
let captured = -1;
const spy = vi.spyOn(scrollMod, "scrollToElement").mockImplementation(
async (_page, _raw, _sel, cx, cy, _cfg, timeout?: number) => {
captured = timeout ?? -1;
return { box: { x: 100, y: 100, width: 50, height: 30 }, cursorX: cx, cursorY: cy, didScroll: false };
},
);
const page = buildMockPage();
const cursor = { x: 100, y: 100, initialized: true };
patchPage(page as any, cfg, cursor as any);
try {
await (page as any).click("#slow", { timeout: 2000 });
} catch (_) { }
if (captured > 0) {
expect(captured).toBeGreaterThan(1500);
expect(captured).toBeLessThanOrEqual(2000);
}
spy.mockRestore();
});
});
// =========================================================================
// Per-call human config override
// =========================================================================
describe("page.type / page.fill accept per-call human config override", () => {
it("page.type forwards nested human_config to humanType", async () => {
const keyboardMod = await import("../src/human/keyboard.js");
const scrollMod = await import("../src/human/scroll.js");
const { patchPage } = await import("../src/human/index.js");
// Make field_switch_delay tiny so the test runs fast
const cfg = resolveConfig("default", {
idle_between_actions: false,
field_switch_delay: [0, 1],
});
expect(cfg.typing_delay).toBe(70); // baseline
let captured: any = null;
const typeSpy = vi.spyOn(keyboardMod, "humanType").mockImplementation(
async (_page, _raw, _text, callCfg) => { captured = callCfg; },
);
const scrollSpy = vi.spyOn(scrollMod, "scrollToElement").mockImplementation(
async (_page, _raw, _sel, cx, cy) => ({
box: { x: 100, y: 100, width: 50, height: 30 },
cursorX: cx, cursorY: cy, didScroll: false,
}),
);
const page = buildMockPage();
const cursor = { x: 100, y: 100, initialized: true };
patchPage(page as any, cfg, cursor as any);
try {
await (page as any).type("#email", "hi", {
timeout: 2000,
human_config: { typing_delay: 30, mistype_chance: 0 },
});
} catch (_) { }
if (captured) {
expect(captured.typing_delay).toBe(30);
expect(captured.mistype_chance).toBe(0);
}
expect(cfg.typing_delay).toBe(70);
typeSpy.mockRestore();
scrollSpy.mockRestore();
}, 5000);
it("page.fill forwards flat config to humanType", async () => {
const keyboardMod = await import("../src/human/keyboard.js");
const scrollMod = await import("../src/human/scroll.js");
const { patchPage } = await import("../src/human/index.js");
const cfg = resolveConfig("default", {
idle_between_actions: false,
field_switch_delay: [0, 1],
});
let captured: any = null;
const typeSpy = vi.spyOn(keyboardMod, "humanType").mockImplementation(
async (_page, _raw, _text, callCfg) => { captured = callCfg; },
);
const scrollSpy = vi.spyOn(scrollMod, "scrollToElement").mockImplementation(
async (_page, _raw, _sel, cx, cy) => ({
box: { x: 100, y: 100, width: 50, height: 30 },
cursorX: cx, cursorY: cy, didScroll: false,
}),
);
const page = buildMockPage();
const cursor = { x: 100, y: 100, initialized: true };
patchPage(page as any, cfg, cursor as any);
try {
await (page as any).fill("#password", "secret", {
timeout: 2000,
typing_delay: 150,
});
} catch (_) { }
if (captured) {
expect(captured.typing_delay).toBe(150);
}
typeSpy.mockRestore();
scrollSpy.mockRestore();
}, 30000);
it("el.type forwards human_config to humanType", async () => {
const keyboardMod = await import("../src/human/keyboard.js");
const { patchSingleElementHandle } = await import("../src/human/elementhandle.js");
const cfg = resolveConfig("default", { idle_between_actions: false, mistype_chance: 0 });
const cursor = { x: 50, y: 50, initialized: true };
let captured: any = null;
const typeSpy = vi.spyOn(keyboardMod, "humanType").mockImplementation(
async (_page, _raw, _text, callCfg) => { captured = callCfg; },
);
const raw = { move: vi.fn(async () => { }), down: vi.fn(async () => { }), up: vi.fn(async () => { }), wheel: vi.fn(async () => { }) };
const rawKb = { down: vi.fn(async () => { }), up: vi.fn(async () => { }), type: vi.fn(async () => { }), insertText: vi.fn(async () => { }) };
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const el = buildMockElementHandle({ evaluate: vi.fn(async (js: string) => js.includes('elementFromPoint') ? { hit: true } : true) });
const page = buildMockPage();
(page as any)._ensureCursorInit = vi.fn(async () => { });
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
await el.type("abc", { human_config: { typing_delay: 25 } });
expect(captured.typing_delay).toBe(25);
typeSpy.mockRestore();
}, 30000);
});
// =========================================================================
// scrollIntoViewIfNeeded humanization
// =========================================================================
describe("humanScrollIntoView", () => {
it("skips wheel events when element is already in viewport", async () => {
const { humanScrollIntoView } = await import("../src/human/scroll.js");
const cfg = resolveConfig("default");
const page: any = { viewportSize: () => ({ width: 1280, height: 720 }) };
const raw = {
move: vi.fn(async () => { }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
};
// Box centered in viewport — squarely in scroll_target_zone
const inViewBox = { x: 200, y: 300, width: 50, height: 30 };
const result = await humanScrollIntoView(page, raw, async () => inViewBox, 0, 0, cfg);
expect(result.box).toEqual(inViewBox);
expect(raw.wheel).not.toHaveBeenCalled();
});
it("fires wheel events when element is below the fold", async () => {
const { humanScrollIntoView } = await import("../src/human/scroll.js");
const cfg = resolveConfig("default", {
scroll_overshoot_chance: 0,
scroll_pre_move_delay: [0, 1],
scroll_pause_fast: [0, 1],
scroll_pause_slow: [0, 1],
scroll_settle_delay: [0, 1],
});
const page: any = { viewportSize: () => ({ width: 1280, height: 720 }) };
const raw = {
move: vi.fn(async () => { }),
down: vi.fn(async () => { }),
up: vi.fn(async () => { }),
wheel: vi.fn(async () => { }),
};
const boxes = [
{ x: 200, y: 2000, width: 50, height: 30 }, // far below
{ x: 200, y: 1500, width: 50, height: 30 },
{ x: 200, y: 1000, width: 50, height: 30 },
{ x: 200, y: 400, width: 50, height: 30 }, // in view
{ x: 200, y: 400, width: 50, height: 30 },
{ x: 200, y: 400, width: 50, height: 30 },
];
let i = 0;
const getBox = async () => boxes[Math.min(i++, boxes.length - 1)];
await humanScrollIntoView(page, raw, getBox, 0, 0, cfg);
expect(raw.wheel).toHaveBeenCalled();
}, 15000);
});
describe("el.scrollIntoViewIfNeeded humanization", () => {
it("calls humanScrollIntoView instead of native snap-scroll", async () => {
const scrollMod = await import("../src/human/scroll.js");
const { patchSingleElementHandle } = await import("../src/human/elementhandle.js");
let called = 0;
const spy = vi.spyOn(scrollMod, "humanScrollIntoView").mockImplementation(
async (_p, _raw, _gb, cx, cy) => {
called++;
return { box: { x: 200, y: 200, width: 50, height: 30 }, cursorX: cx, cursorY: cy };
},
);
const cfg = resolveConfig("default", { idle_between_actions: false });
const cursor = { x: 50, y: 50, initialized: true };
const raw = { move: vi.fn(async () => { }), down: vi.fn(async () => { }), up: vi.fn(async () => { }), wheel: vi.fn(async () => { }) };
const rawKb = { down: vi.fn(async () => { }), up: vi.fn(async () => { }), type: vi.fn(async () => { }), insertText: vi.fn(async () => { }) };
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const el = buildMockElementHandle();
el.scrollIntoViewIfNeeded = vi.fn(async () => { });
const page = buildMockPage();
(page as any)._ensureCursorInit = vi.fn(async () => { });
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
await el.scrollIntoViewIfNeeded();
expect(called).toBeGreaterThan(0);
spy.mockRestore();
});
it("falls back to native scrollIntoViewIfNeeded if humanized helper throws", async () => {
const scrollMod = await import("../src/human/scroll.js");
const { patchSingleElementHandle } = await import("../src/human/elementhandle.js");
const spy = vi.spyOn(scrollMod, "humanScrollIntoView").mockImplementation(
async () => { throw new Error("detached"); },
);
const cfg = resolveConfig("default", { idle_between_actions: false });
const cursor = { x: 50, y: 50, initialized: true };
const raw = { move: vi.fn(async () => { }), down: vi.fn(async () => { }), up: vi.fn(async () => { }), wheel: vi.fn(async () => { }) };
const rawKb = { down: vi.fn(async () => { }), up: vi.fn(async () => { }), type: vi.fn(async () => { }), insertText: vi.fn(async () => { }) };
const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
const nativeFallback = vi.fn(async () => { });
const el = buildMockElementHandle();
el.scrollIntoViewIfNeeded = nativeFallback;
const page = buildMockPage();
(page as any)._ensureCursorInit = vi.fn(async () => { });
patchSingleElementHandle(el, page as any, cfg, cursor as any, raw, rawKb, originals, null);
await el.scrollIntoViewIfNeeded();
expect(nativeFallback).toHaveBeenCalled();
spy.mockRestore();
});
});
// =========================================================================
// Issue #307: frame.click timeout should not multiply
// =========================================================================
describe("frame.click timeout budget (#307)", () => {
it("total wait time should not exceed the specified timeout", async () => {
const { patchPage } = await import("../src/human/index.js");
const TIMEOUT_MS = 500;
const delay = (ms: number) => new Promise(r => setTimeout(r, ms));
// Build a frame where the element does NOT exist:
// scrollIntoViewIfNeeded and boundingBox each wait until their
// individual timeout before failing, and origFrameClick does the same.
const frameLoc: any = {
boundingBox: vi.fn(async (opts?: { timeout?: number }) => {
await delay(opts?.timeout ?? 30000);
return null;
}),
scrollIntoViewIfNeeded: vi.fn(async (opts?: { timeout?: number }) => {
await delay(opts?.timeout ?? 30000);
throw new Error("timeout");
}),
evaluate: vi.fn(async () => ({ hit: true })),
isChecked: vi.fn(async () => false),
};
frameLoc.first = vi.fn(() => frameLoc);
const origClickFn = vi.fn(async (_sel: string, opts?: any) => {
await delay(opts?.timeout ?? 30000);
throw new Error("timeout");
});
const childFrame: any = {
click: origClickFn,
dblclick: vi.fn(async () => {}),
hover: vi.fn(async () => {}),
type: vi.fn(async () => {}),
fill: vi.fn(async () => {}),
check: vi.fn(async () => {}),
uncheck: vi.fn(async () => {}),
selectOption: vi.fn(async () => {}),
press: vi.fn(async () => {}),
pressSequentially: vi.fn(async () => {}),
tap: vi.fn(async () => {}),
clear: vi.fn(async () => {}),
dragAndDrop: vi.fn(async () => {}),
locator: vi.fn(() => frameLoc),
childFrames: vi.fn(() => []),
};
const mainFrame = {
...buildMockFrame(),
childFrames: vi.fn(() => [childFrame]),
};
const page = buildMockPage({ mainFrameReturn: mainFrame });
const cfg = resolveConfig("default", {
mouse_min_steps: 1,
mouse_max_steps: 1,
idle_between_actions: false,
});
const cursor = { x: 0, y: 0, initialized: true };
patchPage(page as any, cfg, cursor as any);
const start = Date.now();
try {
await (childFrame as any).click("#does-not-exist", { timeout: TIMEOUT_MS });
} catch {
// expected — element doesn't exist
}
const elapsed = Date.now() - start;
// With the bug, elapsed ≈ 3 * TIMEOUT_MS (scrollIntoView + boundingBox + origClick).
// Fixed: elapsed should be ≈ 1 * TIMEOUT_MS (shared deadline).
// Allow 1.8x as upper bound to account for test overhead but catch the 3x bug.
expect(elapsed).toBeLessThan(TIMEOUT_MS * 1.8);
});
});
describe("pointer-events check fail-open", () => {
// When the check itself cannot run (evaluate / boundingBox throws -> result
// null), proceed with the click instead of blocking it until the timeout.
it("checkPointerEventsHandle returns promptly when evaluate throws", async () => {
const { checkPointerEventsHandle } = await import("../src/human/actionability.js");
const el = {
boundingBox: vi.fn().mockRejectedValue(new Error("stale handle")),
evaluate: vi.fn().mockRejectedValue(new Error("execution context destroyed")),
};
const start = Date.now();
await checkPointerEventsHandle(el as any, 100, 100, 2000); // must not throw
expect(Date.now() - start).toBeLessThan(500);
});
it("checkPointerEvents returns promptly when evaluate throws", async () => {
const { checkPointerEvents } = await import("../src/human/actionability.js");
const loc = {
first: () => loc,
boundingBox: vi.fn().mockRejectedValue(new Error("no element")),
evaluate: vi.fn().mockRejectedValue(new Error("no element")),
};
const page = { locator: vi.fn().mockReturnValue(loc) };
const start = Date.now();
await checkPointerEvents(page as any, "#x", 100, 100, null, 2000); // must not throw
expect(Date.now() - start).toBeLessThan(500);
});
it("checkPointerEventsHandle still throws when genuinely covered", async () => {
const { checkPointerEventsHandle, ElementNotReceivingEventsError } =
await import("../src/human/actionability.js");
const el = {
boundingBox: vi.fn().mockResolvedValue({ x: 0, y: 0, width: 10, height: 10 }),
evaluate: vi.fn().mockResolvedValue({ hit: false, covering: "DIV" }),
};
await expect(checkPointerEventsHandle(el as any, 5, 5, 200)).rejects.toBeInstanceOf(
ElementNotReceivingEventsError,
);
});
});