メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://docs.therefrain.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
概要

セレクタは、どの DOM 要素を操作するかを指定します。複数のフィールドをフォールバック戦略として使用し、優先順位に従って順番にマッチを試みます。

​
セレクタフィールド

フィールド型優先順位説明
idstring1要素の id 属性（最も信頼性が高い）
ariaLabelstring2aria-label 属性
dataTestIdstring3data-testid 属性
dataAttributesRecord<string, string>4その他の data-* 属性
cssSelectorstring5CSS セレクタ
xPathstring6XPath 式
labelTextstring7関連する <label> のテキスト
innerTextstring8要素の innerText（最大200文字）
placeholderstring9placeholder 属性
namestring10name 属性
rectobject11位置ベースのフォールバック（最終手段）
tagNamestring—HTML タグ名（常に存在、フィルタリングに使用）
rolestring—ARIA role 属性
inputTypestring—<input> 要素の type 属性

​
解決パイプライン

セレクタは6段階のパイプラインで解決されます：
1

決定論的解決

優先順位順にセレクタフィールドを試行（id → ariaLabel → … → name）。AI 不要。
2

AI セレクタ解決

決定論的解決が失敗した場合、AI が現在のページスナップショットを分析して対象要素を特定。
3

スマートリトライ（3回）

タイムアウトを増やしながらリトライし、試行間で DOM の変化を待機。
4

スクロール回復

画面外の要素を見つけるためにページをスクロール。
5

Agent Fallback

AI エージェントが代替パスを探索して対象要素に到達。Pro+ プランが必要。
6

Vision Fallback

スクリーンショットを撮影し、Vision AI で要素を視覚的に特定。Pro+ プランが必要。

​
例

action:
  type: click
  selector:
    tagName: button
    id: "submit-btn"
    ariaLabel: "Submit form"
    innerText: "Submit"
    role: "button"
この例では、エグゼキュータは以下の順序で試行します：
  1. まず #submit-btn を試行
  2. id が見つからない場合 [aria-label="Submit form"] にフォールバック
  3. aria-label が失敗した場合 innerText のマッチにフォールバック
  4. role と tagName は全体を通じて追加フィルタとして使用

​
rect（位置フォールバック）

最終手段の決定論的戦略です。座標はビューポート相対です。 
selector:
  tagName: button
  rect:
    x: 150
    y: 300
    width: 120
    height: 40
フィールド型説明
xnumberX 座標
ynumberY 座標
widthnumber要素の幅
heightnumber要素の高さ
位置ベースのセレクタはレイアウト変更で壊れやすいです。可能な限りセマンティックセレクタ（id、ariaLabel、dataTestId）を使用してください。

​
dataAttributes

カスタム data-* 属性で要素をマッチ： 
selector:
  tagName: div
  dataAttributes:
    row-id: "42"
    status: "active"
これは <div data-row-id="42" data-status="active"> にマッチします。

​
ベストプラクティス

  1. 安定した識別子を優先 — id、dataTestId、ariaLabel は CSS セレクタや XPath よりも UI の再設計に強い。
  2. rect は避ける — 位置セレクタはレイアウト変更で壊れる。セマンティックセレクタがない場合のみ使用。
  3. innerText は短く — 長いテキストマッチは壊れやすい。フィールドは200文字に制限。
  4. セレクタキャッシュを有効化 — 繰り返し実行する場合、--enable-selector-cache で成功した解決結果を永続化。