本文へスキップ

人間らしい入力

humanize を指定すると、SDK がマウスの移動、クリック、スクロール、タイピングを人間らしい軌跡とタイミングで実行します。showCursorはポインターを描画するので、動きを目で確認できます。

人間らしい入力(humanize と showCursor)

humanize を渡すと、移動、クリック、ドラッグ、スクロール、タイピングといったすべての入力が、ページレベル(page.click / hover / type / fill / mouse.* / keyboard.type)でもロケーターレベル(locator.click / type / fill / pressSequentially / dragTo / …)でも、統一された人間らしい動作で実行されます。移動は、直前のカーソル位置から組み立てた、わずかに弧を描く 3 次ベジェ曲線に沿って進みます。その進み方は min-jerk のサブムーブメント合成です(弾道的な主運動 + 修正運動。左右対称なベル型 1 つではなく、実際に手を伸ばす動作に見られる複数ピークの速度プロファイルです)。すべての入力は本物の、信頼された(trusted)イベントとしてディスパッチされます(isTrusted === true で、navigator.webdriver も false のままです)。Pro では、座標指定のクリック(mouse.click(x, y))は実際の人間から記録した動きに従います。それ以外の操作、およびオープンビルドと「GitHub で無料」でのすべてのクリックは、生成した軌跡を使います。showCursor を追加すると、動きに追従するドットが描画され、動作を目で確認できます。

移動にはネイティブ入力を使うため、mouse.down() で押したボタンは移動中も押されたままです。つまり down → move → up は、ボタンを押したままの本物のドラッグになり(スライダーのように目的の位置までドラッグするコントロールでも、実際に押した状態でドラッグされます)、locator.dragTo も人間らしい動作になります。タイピングは 1 キーずつ行い、キー間隔はランダムで、単語の区切りでは間を置き、ときどき打ち間違いを修正します。さらにキーロールオーバーも起こります。速いキーの組み合わせの一部では、前のキーが上がる前に次のキーが押されます。その頻度はアイデンティティごとに固定です(SDK 0.41.1)。fill はフィールドをクリックしてから値を入力します(200 文字を超える値は、まずクリックしてから一度にまとめて挿入されるので、大量の入力でも遅くなりません)。

スクロールはマウスホイールのノッチ単位で、短いフリックを重ねて行い、ときどき読むための間を挟みます。ポインターがコンテンツの上にない場合は、まずそこへ移動させます。ブラウザはホイールイベントをすべて 1 ノッチ分として報告し、実際のノッチは Windows では 100 px、Linux では 120、macOS では 40 動きます。そのため、ノッチの大きさはページに報告されるプラットフォームに従い、要求した距離は最も近いノッチ数(最低 1 ノッチ)に丸められます。mouse.wheel(0, 800) は、Windows のアイデンティティでは 800 px、Linux のアイデンティティでは 840 スクロールします(SDK 0.41.1)。

フォーム(SDK 0.48.0)

fill はフィールドの種類に合わせて動作します。テキストは、フィールドに値があるときだけキーを押したままの操作で消去してから入力し、結果を確認します。range スライダーは正確な値までドラッグします。日付、時刻、月、週、日時のフィールドは、ブラウザが表示する順に区切りごとに入力します。フィールドに入らない値は、これまでどおり Playwright 自身のエラーになります。

selectOption はクリックでドロップダウンを開き、オプションのラベルの先頭(スペースを含む)を入力して Enter で確定するので、ページから見えるのは行ごとの変更ではなく信頼された変更 1 回です。入力でたどり着けない行には、矢印キーを押し続けて移動します。リストボックスはホイールでスクロールし、行をクリックして選び、複数選択の追加の行は Ctrl を押しながら選びます。check / uncheck は状態を変える必要があるときだけクリックします。

パスワード、メール、数値、電話番号、URL、ワンタイムコードの各フィールドや、フレーム内のフィールドでは打ち間違いをせず、実際に入力された分だけを修正します。CLEARCOTE_HUMANIZE_TYPO_RATE でキーごとの頻度を設定します(既定値 0.02、0 で打ち間違いを無効化)。クリックのオプションはすべて反映され(ボタン、クリック回数、押下時間、修飾キー、位置、force、trial)、Playwright のどのロケーターも使えます。クリック位置が覆われていないかの確認にはブラウザ自身のヒットテストを使うので、ポインターが軌跡より先に動くことも、早すぎる押下もありません。

タイミングと狙い(SDK 0.49.0)

マウスの軌跡、ドラッグ、ambient_motion / ambientMotion は、負荷の高いマシンでも計画どおりの所要時間を保ちます。一部の軌跡は目標を通り過ぎてから戻り、その頻度はアイデンティティごとに固定です。ボタンを押したままのドラッグはその線から数ピクセル以内に収まるので、スライダーのつまみは軌道から外れません。SDK 自身が行う押下は、ポインターが到着してから短い間を置いて行われます(40~250 ms、典型的な長さはアイデンティティごとに固定)。

クリックを透過するレイヤー(グラデーション、アイコン、浮いたラベル)の下にあるコントロールも、ほかと同じようにクリックされます。trial は Playwright のチェックを実行するだけで、入力は一切行いません。最大長や入力マスクのあるフィールド(有効期限、電話番号)は 1 回だけ入力され、消去して打ち直すことはありません。日付と時刻のフィールドはテキストと同じキータイミングで入力されます。エラーは Playwright 自身のもので、文言も同じです。

Python、Node、.NET(.NET は 0.58.0 以降)では、座標指定のクリック(mouse.click(x, y))をブラウザエンジン自身が移動・押下することがあります。154 r39 までのエンジンでは、その押下はポインター到着の約 10 ms 後に、間を置かずに行われます。CLEARCOTE_HUMANIZE_ENGINE_CLICKS=off はすべてのクリックを SDK の経路に保ち、=all(オプトイン)はセレクター指定のクリックもエンジンに送ります。

from clearcote import launch

browser = launch(fingerprint="seed-123", humanize=True, show_cursor=True)
page = browser.new_page()
page.goto("https://example.com")

page.click("text=Sign in")               # eased curve, then a trusted click
page.fill("#email", "you@example.com")   # focus + key-by-key human typing
page.locator("#password").type("s3cr3t") # locators are humanized too

# held-button drag (e.g. a slider): the press stays held across the move
x0, y0, x1 = 100, 300, 400               # the handle's start, and where to release it
page.mouse.move(x0, y0); page.mouse.down()
page.mouse.move(x1, y0); page.mouse.up()
browser.close()

長押し

ボタンを押している間だけ動作するコントロールがあります。長押しで確定するボタン、長押しで開くメニュー、ゲージが満ちてから受け付ける長押しボタンなどです。press_and_hold / pressAndHold / PressAndHoldAsync は、要素に対して人間らしい長押しを 1 回行います。humanize を指定すると、ページ(page.press_and_hold(selector))とすべてのロケーター(locator.press_and_hold()、フレームロケーターを含む)で使えます。モジュール関数 press_and_hold(locator) はどのページでも動作します。非同期 API(clearcote.async_api)にも同じ名前があり、await して使います。

要素が表示されるのを待ってから画面内に表示させ(人間らしいホイールスクロールで)、アイデンティティに応じた中心付近の点(または Playwright と同じく要素の左上を基準とした position)までポインターを滑らかに動かし、少し間を置いてから押します。ボタンは duration ミリ秒のあいだ押されたままになり、既定では毎回 2.8~3.8 秒の値が選ばれます。until を指定した場合は、それが true を返すまで押し続けます。この条件は 100 ms ごとに確認され、そのとき duration は長押しの上限になります(指定しなければ 15 秒)。ボタンは条件が変わった瞬間ではなく、160~350 ms の人間らしい反応時間の後に離されます。

ボタンを押している間も、静止した手は時々マウスを動かします。まばらな整数ピクセル単位のわずかな揺れで、押した点から 2 px 以上離れることはなく、どの移動もボタンが押されたままと報告される信頼された(trusted)移動です。tremor=False / tremor: false でポインターを静止させます。button で左・右・中央のボタンを選び、timeout は要素が表示されるまで待つ時間です。長押しが所定の時間を終えたか until が true になった場合は true を、until が一度も true にならなかった場合は false を返します。until が例外を投げた場合も含め、ボタンは必ず離されます。非同期 API では until に async 関数を渡せ、呼び出しをキャンセルした場合もボタンは離されます。

from clearcote import launch, press_and_hold

browser = launch(fingerprint="seed-123", humanize=True)
page = browser.new_page()
page.goto("https://example.com")

# hold until the button reports it is done (at most 15 s), then let go
done = page.press_and_hold(
    "#hold", until=lambda: page.locator("#hold[data-state=done]").count() > 0
)
print(done)                              # False if the state never changed

# a fixed 4-second hold, pressed 20 px in from the left edge
page.locator("#confirm").press_and_hold(4000, position={"x": 20, "y": 10})

# a control inside an iframe
frame = page.frame_locator("iframe#widget")
frame.locator("#hold").press_and_hold(
    until=lambda: frame.locator("#hold[data-state=done]").count() > 0
)

# the module function works on any Playwright page
press_and_hold(page.locator("#menu-item"), 1200)
browser.close()