> ## 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 要素の特定方法。

## 概要

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

## セレクタフィールド

| フィールド            | 型                       | 優先順位 | 説明                        |
| ---------------- | ----------------------- | :--: | ------------------------- |
| `id`             | string                  |   1  | 要素の `id` 属性（最も信頼性が高い）     |
| `ariaLabel`      | string                  |   2  | `aria-label` 属性           |
| `dataTestId`     | string                  |   3  | `data-testid` 属性          |
| `dataAttributes` | Record\<string, string> |   4  | その他の `data-*` 属性          |
| `cssSelector`    | string                  |   5  | CSS セレクタ                  |
| `xPath`          | string                  |   6  | XPath 式                   |
| `labelText`      | string                  |   7  | 関連する `<label>` のテキスト      |
| `innerText`      | string                  |   8  | 要素の innerText（最大200文字）    |
| `placeholder`    | string                  |   9  | `placeholder` 属性          |
| `name`           | string                  |  10  | `name` 属性                 |
| `rect`           | object                  |  11  | 位置ベースのフォールバック（最終手段）       |
| `tagName`        | string                  |   —  | HTML タグ名（常に存在、フィルタリングに使用） |
| `role`           | string                  |   —  | ARIA `role` 属性            |
| `inputType`      | string                  |   —  | `<input>` 要素の `type` 属性   |

## 解決パイプライン

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

<Steps>
  <Step title="決定論的解決">
    優先順位順にセレクタフィールドを試行（id → ariaLabel → ... → name）。AI 不要。
  </Step>

  <Step title="AI セレクタ解決">
    決定論的解決が失敗した場合、AI が現在のページスナップショットを分析して対象要素を特定。
  </Step>

  <Step title="スマートリトライ（3回）">
    タイムアウトを増やしながらリトライし、試行間で DOM の変化を待機。
  </Step>

  <Step title="スクロール回復">
    画面外の要素を見つけるためにページをスクロール。
  </Step>

  <Step title="Agent Fallback">
    AI エージェントが代替パスを探索して対象要素に到達。Pro+ プランが必要。
  </Step>

  <Step title="Vision Fallback">
    スクリーンショットを撮影し、Vision AI で要素を視覚的に特定。Pro+ プランが必要。
  </Step>
</Steps>

## 例

```yaml theme={null}
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`（位置フォールバック）

最終手段の決定論的戦略です。座標はビューポート相対です。

```yaml theme={null}
selector:
  tagName: button
  rect:
    x: 150
    y: 300
    width: 120
    height: 40
```

| フィールド    | 型      | 説明    |
| -------- | ------ | ----- |
| `x`      | number | X 座標  |
| `y`      | number | Y 座標  |
| `width`  | number | 要素の幅  |
| `height` | number | 要素の高さ |

<Note>
  位置ベースのセレクタはレイアウト変更で壊れやすいです。可能な限りセマンティックセレクタ（`id`、`ariaLabel`、`dataTestId`）を使用してください。
</Note>

## `dataAttributes`

カスタム `data-*` 属性で要素をマッチ：

```yaml theme={null}
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` で成功した解決結果を永続化。