# Paxter Agent Guide

**Canonical machine-readable reference for generating Paxter YAML browser workflows.**

Use this document as the contract for scripts you generate. It is published unchanged at
`https://paxter.booolean.com/agent-guide.md` with every documentation deployment.

## Operating rules

- Generate YAML only; do not generate Playwright source code unless it will be passed to `convert` first.
- Prefer role and label actions over CSS locators. Use locator and force actions only when an accessible role or label is unavailable.
- Use accessible names exactly as exposed by the target page. `Nth` indexes are zero-based.
- Do not include credentials, tokens, or production data in a workflow. Use an approved test account and target only an environment you are authorised to test.
- A failed action stops the remaining actions in that workflow. Paxter captures a screenshot after each successful action and writes a report.

## Command access

Paxter commands have three access levels. Free commands (`version`, `help`, `init`, `setup`, `update`, and `register`) are available without a subscription. `paxter init` creates non-overwriting local starter files: `paxter.yaml`, `workflow.yaml`, and relevant `.gitignore` entries. Run `paxter setup` to install the Playwright-managed Chromium browser before a browser workflow; leave `ChromiumPath` empty in `paxter.yaml` unless a specific browser executable is required. Registered access permits `run` workflows with up to 10 actions and requires a valid `Registration` section in local `paxter.yaml`. A workflow with more than 10 actions requires a current subscription. The paid `convert` and `runparallel` commands also require a current subscription. Use `paxter register` to verify local registration before generating or running workflows.

## Account and registration

Registration details are issued by an organisation's Paxter administrator or through [Booolean support](https://www.booolean.com/paxter); Paxter and an AI agent cannot generate them. The only user-facing registration values are `LicensedEmail` and `RegistrationCode` in local `paxter.yaml`. If they are missing or validation is unavailable, direct the user to their Paxter administrator or Booolean support. Never ask a user to share either value in a chat, ticket, workflow, report, screenshot, source repository, or generated YAML.

## Workflow format

```yaml
Headless: true
NeedVideo: false
Actions:
  - Do: Page_GotoAsync
    Data1: https://test.example.com
  - Do: GetByRoleTextbox_Fill
    Data1: Email
    Data2: test.user@example.com
  - Do: GetByRoleButton_ByName_Click
    Data1: Sign in
```

| Field | Required | Meaning |
| --- | --- | --- |
| `Headless` | No | `true` runs without a visible browser; default is `false`. |
| `NeedVideo` | No | Records a Playwright video when `true`; default is `true`. |
| `Actions` | Yes | Ordered list of actions. |
| `Do` | Yes | One of the supported action names below. Names are matched without spaces and case-insensitively. |
| `Data1` | Depends | Usually the accessible name, visible text, URL, CSS selector, or element id. |
| `Data2` | Depends | Usually a value, key, option, index, or second selector. |
| `Data3` | Depends | Used by `SelectTextForOption` for the zero-based option index. |
| `Pipe` | No | A text transformation pipeline supported by the specific action. |

`Group` is metadata only: `Do: Group` with `Data1: name` changes the report group for following actions and is not executed in the browser. `Action:` is accepted only as a legacy input alias; generate `Do:` in all new workflows.

## Variables and transformations

`DefineVariable` reserves a name beginning with `__`. `ReadInnerText` stores an element's text under that name. In data fields that resolve values, a value beginning with `__` is replaced by the stored value; an undefined variable resolves to an empty string.

```yaml
- Do: DefineVariable
  Data1: __confirmationCode
- Do: ReadInnerText
  Data1: .confirmation-code
  Data2: __confirmationCode
  Pipe: trim
- Do: GetByRoleTextbox_Fill
  Data1: Confirmation code
  Data2: __confirmationCode
```

Supported pipe stages are `trim`, `upper`, `lower`, `reverse`, `capitalize`, `randomName`, and `substr:start,length`. Join stages with `|`, for example `trim|upper|substr:0,6`. Pipes run for `ReadInnerText`, `Locator_Fill`, and `GetLocator_Click_Fill`.

## Supported actions

### Navigation and waits

| Do | Data fields | Behaviour |
| --- | --- | --- |
| `Page_GotoAsync` | `Data1`: URL | Navigates to the URL. Preferred navigation action. |
| `Goto` | `Data1`: URL | Legacy alias; navigates to the URL. |
| `WaitForUrl` | `Data1`: URL or Playwright URL pattern | Waits until the page URL matches. |
| `WaitFor5Seconds` | — | Waits 5,000 ms. Avoid when a targeted wait is possible. |
| `WaitForSeconds` | — | Waits for `Number1` milliseconds. Workflow YAML does not currently populate `Number1`; do not generate this action. |

### Links, buttons, and text

| Do | Data fields | Behaviour |
| --- | --- | --- |
| `GetByRoleLink_ByName_Click` | `Data1`: link name | Clicks a link by accessible name. Preferred link action. |
| `GetByRoleLink_Click` | `Data1`: link name | Legacy alias for `GetByRoleLink_ByName_Click`. |
| `GetByRoleLink_Exact_Click` | `Data1`: exact link name | Clicks a link with exact name matching. |
| `GetByRoleLink_Nth_Click` | `Data1`: link name; `Data2`: zero-based index | Clicks the indexed matching link. |
| `GetByRoleButton_ByName_Click` | `Data1`: button name | Clicks a button by accessible name. Preferred button action. |
| `GetByRoleButton_Click` | `Data1`: button name | Legacy alias for `GetByRoleButton_ByName_Click`. |
| `GetByRoleButton_First_Click` | `Data1`: button name | Clicks the first matching button. |
| `GetByRoleButton_Nth_Click` | `Data1`: button name; `Data2`: zero-based index | Clicks the indexed matching button. |
| `GetByText_Generic_Click` | `Data1`: visible text | Clicks an element containing the text. |
| `GetByText_Click` | `Data1`: visible text | Legacy alias for `GetByText_Generic_Click`. |
| `GetByText_Exact_Click` | `Data1`: exact visible text | Clicks an element with exact text matching. |
| `GetByText_ExactTrue_Click` | `Data1`: exact visible text | Alias for `GetByText_Exact_Click`. |

### Inputs, selection, and uploads

| Do | Data fields | Behaviour |
| --- | --- | --- |
| `GetByLabel_Fill` | `Data1`: label; `Data2`: value | Fills the input associated with the label. |
| `GetByLabel_Press` | `Data1`: label; `Data2`: key | Presses a key on the labelled input. |
| `GetByLabel_SelectOption` | `Data1`: label; `Data2`: option value | Selects an option on the labelled control by value. |
| `GetByRoleTextbox_Click` | `Data1`: textbox name | Focuses a textbox. |
| `GetByRoleTextbox_Fill` | `Data1`: textbox name; `Data2`: value | Fills a textbox. |
| `GetByRoleTextbox_Press` | `Data1`: textbox name; `Data2`: key | Presses a key on a textbox. |
| `GetByRoleSpinbutton_Click` | `Data1`: spinbutton name | Focuses a numeric input. |
| `GetByRoleSpinbutton_Fill` | `Data1`: spinbutton name; `Data2`: value | Fills a numeric input. |
| `GetByRoleSearchbox_Fill` | `Data1`: searchbox name; `Data2`: value | Fills a search box. |
| `GetByRoleCombobox_Click` | `Data1`: combobox name | Clicks a combobox. |
| `GetByRoleCombobox_Press` | `Data1`: combobox name; `Data2`: key | Presses a key on a combobox. |
| `GetByRoleCombobox_LocatorSpanNth_Click` | `Data1`: combobox name; `Data2`: zero-based index | Clicks the indexed `span` within a combobox. |
| `GetByRoleCombobox_LocatorId_Click` | `Data1`: combobox name; `Data2`: selector | Clicks `Data2` within a combobox. Include `#` yourself for an id selector. |
| `GetByRoleOption_Click` | `Data1`: option name | Clicks an option by accessible name. |
| `SelectLabelOption` | `Data1`: element id; `Data2`: option label | Selects a native select by label; for Select2 controls, searches and clicks matching text. |
| `SelectByValue` | `Data1`: element id; `Data2`: option value | Selects a native select or Select2 control by value. |
| `SelectByOption` | `Data1`: element id; `Data2`: option value | Alias-like helper that selects by value for native selects or Select2 controls. |
| `SelectTextForOption` | `Data1`: textbox name; `Data2`: option name; `Data3`: zero-based index | Focuses a textbox, then clicks the indexed matching option. |
| `Checkbox_Click` | `Data1`: checkbox id | Clicks the label whose `for` attribute matches the id. |
| `UploadFile` | `Data1`: file input id; `Data2`: file path | Sets files on `#Data1`. |
| `GetByRoleButton_SetInputFiles` | `Data1`: button name; `Data2`: comma-separated file paths | Sets files on a button locator. |

### Locators and specialised actions

| Do | Data fields | Behaviour |
| --- | --- | --- |
| `GetLocator_Click` | `Data1`: element id without `#` | Clicks `#Data1`. Do not pass a full CSS selector. |
| `GetLocator_Click_Fill` | `Data1`: element id without `#`; `Data2`: value | Clicks then fills `#Data1`; applies `Pipe` to the value. |
| `GetLocator_LinkByRole_Click` | `Data1`: container selector; `Data2`: link name | Clicks a named link inside the container. |
| `Locator_Press` | `Data1`: CSS selector; `Data2`: key | Presses a key on the locator. |
| `Locator_Fill` | `Data1`: CSS selector; `Data2`: value | Fills the locator; applies `Pipe` to the value. |
| `Locator_First_Click` | `Data1`: CSS selector | Clicks the first matching locator. |
| `GetByRoleGroup_LocatorI_First_Click` | `Data1`: group name | Clicks the first `i` element in the named group. |
| `GetByRoleListitem_FilterHasText_Click` | `Data1`: text | Clicks the list item filtered by containing text. |
| `ForceButtonClick` | `Data1`: button id without `#` | Force-clicks `button#Data1`, bypassing normal actionability checks. Use only when necessary. |

### Data capture

| Do | Data fields | Behaviour |
| --- | --- | --- |
| `DefineVariable` | `Data1`: variable name beginning with `__` | Creates or clears the variable. |
| `ReadInnerText` | `Data1`: CSS selector; `Data2`: variable name beginning with `__` | Reads the element's inner text, applies `Pipe`, and stores it. |

## Generation checklist

1. Start with `Page_GotoAsync` and a permitted test URL.
2. Identify targets by accessible role, label, and name before using text or CSS selectors.
3. Use `Nth` only after confirming the page has repeated matching elements.
4. Use a URL wait after actions that navigate or redirect when the next step depends on the destination.
5. Keep file paths available to the machine that runs Paxter.
6. Return only valid YAML matching the structure above.

## Keeping this guide current

The documentation build checks that every executable `PaxAction` in the runner is named in this file. When adding or changing action behaviour, update the corresponding row and an example if needed before merging. The site deployment copies this file directly, so the published URL changes with the documentation deployment.