@copado/agentia-cli 1.2.0 → 1.4.0

package/templates/skills/agentia-testing/references/browser-testing.md

@@ -0,0 +1,92 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CRT Browser Testing Reference
+
+Use `agentia testing browser` (and the matching `agentia_testing_browser_*` MCP tools) to drive an interactive Copado Robotic Testing browser session tied to a CRT Job and Project.
+
+## Mental Model
+
+- **One active session at a time**, stored in `.agentia/config.user.json` under `testingBrowserSession`. Always pass `--project <project-id>` (and optional `<job-id>` / `--session-id` guards).
+- **In-memory Session Cookies**: Agentia exchanges your CRT PAK for `FL`, `XSRF-TOKEN`, and `sessionsToken` cookies via `/user/access-keys/tokens?toSign=all`. Cookies stay in memory (cached with a 60s expiry buffer in long-lived processes like MCP and `recorder`) and are never written to disk.
+- **Browser Viewer**: Always pass `--no-open` to `testing browser view` by default (`agentia testing browser view --project <project-id> --no-open --json`) to print/return the interactive CRT browser session URL `https://<domain>/browser/session/<sessionId>?projectId=<projectId>&orgId=<orgId>` without launching a local browser window. Omit `--no-open` only when the user explicitly asks to open the browser. `testing browser stop` cleans up the session automatically.
+- **Replayable Keyword History**: Every `testing browser execute` and `testing browser recorder` event appends to `~/.agentia/testing-live/<projectId>/<jobId>.jsonl` with full Robot Framework keyword lines (`TypeSecret` values and auth tokens redacted). Closing a session does not clear history.
+
+## Canonical Workflow
+
+```sh
+# 1. Start the session (polls /api/status, loads QWeb/QForce/QMobile, sets QWeb config, opens Chrome)
+agentia testing browser start <job-id> --project <project-id> --json
+
+# 2. (Optional) Start the recorder in a background subagent before handing the viewer URL to a user
+agentia testing browser recorder --project <project-id> --output flow.robot
+
+# 3. Surface the viewer URL with --no-open by default (omit --no-open only if the user explicitly asks to open the browser)
+agentia testing browser view --project <project-id> --no-open --json
+
+# 4. Execute Robot Framework keywords (4+ spaces separate arguments)
+agentia testing browser execute --project <project-id> \
+  --line "GoTo    https://example.com" \
+  --line "VerifyText    Example Domain" --json
+
+# 5. Observe page state, DOM, and annotated screenshots
+agentia testing browser inspect --project <project-id> --json
+agentia testing browser inspect --project <project-id> --dom --json
+agentia testing browser screenshot --project <project-id> --output /tmp/page.png --json
+
+# 6. Export proven steps from Keyword History into a .robot script
+agentia testing browser history <job-id> --project <project-id> --lines-only > flow.robot
+
+# 7. Tear down the session (cleans up host, PACE, and local state)
+agentia testing browser stop --project <project-id> --yes --json
+```
+
+## Subcommands & Flags
+
+| Subcommand | Purpose & Key Flags |
+| --- | --- |
+| `testing browser start <job-id>` | Create and bootstrap a session. Flags: `--project` (required), `--library QWeb\|QForce\|QMobile` (default `QWeb`), `--no-bootstrap`, `--no-browser`, `--screen WIDTHxHEIGHTxDEPTH`, `--viewport WIDTHxHEIGHT`, `--file`, `--timeout`. |
+| `testing browser status [job-id]` | Check `env` (`isBrowserStarted`, `isWindowOpen`), `recorder` (`connected`), `server` (`ambleApiVersion`, `inShutdownState`, `inFatalErrorState`), and `session` (`currentIdleTime`, `sessionIdleTimeout`, `timeToExpire`, `isKeywordExecutionPending`). |
+| `testing browser execute [job-id]` | Run keywords using `--line "..."` (repeatable), `--keyword <name> --arg <val>`, `--file <path>`, or `--stdin`. Pass `--raw` to skip `.robot` section parsing. |
+| `testing browser inspect [job-id]` | Fetch `GET /api/system-state` (`url`, `timestamp`, `changeOrigin`, `systemState` interactive element annotations). Add `--dom` with `--output <file>` or `--json` to stream and reassemble `document.documentElement.outerHTML` over the terminal WebSocket. |
+| `testing browser screenshot [job-id]` | Save the current viewport PNG (including teal detection bounding boxes) to `--output <path>`. |
+| `testing browser set-options [job-id]` | Set the full recorder option block (`--[no-]enable`, `--[no-]scroll-text`, `--[no-]healing-context`, `--[no-]hover-text`, `--[no-]system-state`, `--[no-]verify-text`, `--[no-]table-keywords`). Unspecified options default to `false`. |
+| `testing browser view` | Print (`--no-open`, default for agents) or open the CRT browser session URL. Always use `--no-open` unless the user explicitly asks to open the browser. |
+| `testing browser recorder [job-id]` | Connect to the session WebSocket, enable backend recording, and stream captured interactions and executed keywords as Robot Framework lines (or JSON lines with `--json`). Flags: `--output <file.robot>`, `--no-enable`, `--force` (reclaim stale lock), `--debug`. |
+| `testing browser history [job-id]` | Read per-job keyword history. Flags: `--job <id>`, `--limit <n>`, `--keyword <name>` (case-insensitive first token), `--lines-only` (flatten to raw `.robot` lines), `--include-failed` (failed executions are omitted by default), `--status completed\|failed\|recorded`. MCP `linesOnly: true` returns `count`, `jobId`, `lines`, and `projectId` without `executions`. |
+| `testing browser stop [job-id]` | Stop the session on the session host and PACE, and clear local state. Requires `--yes` in `--json` / non-TTY mode (`confirm: true` in MCP). |
+
+## Parallel Recorder & Idle Keepalive Patterns
+
+### 1. Parallel Recorder via Background Subagent
+When driving or co-piloting a browser session with a human:
+1. Run `agentia testing browser start <job-id> --project <project-id> --json`.
+2. Before handing the viewer URL to the user, start `agentia testing browser recorder --project <project-id> --output captured.robot` in a background shell/subagent. The recorder captures both browser interactions (`status: "recorded"`) and `testing browser execute` commands (`status: "completed"`) in execution order so `--output` produces a complete `.robot` file.
+3. Run `agentia testing browser view --project <project-id> --no-open --json` (always pass `--no-open` by default unless the user explicitly asks to open the browser) and share the `url` with the user.
+4. **Verify capture after the user's first action**:
+   ```sh
+   agentia testing browser history --project <project-id> --status recorded --json
+   ```
+   `recorder.connected: true` in `status` only proves the WebSocket is open, not that events are firing. If `count` remains `0` after the user clicks, drive the steps via `testing browser execute` instead.
+5. **Clean shutdown**: Send `SIGINT` (`kill -INT <pid>`) to the recorder process before running `testing browser stop` so it cleanly posts `setoptions {recorder: {enabled: false}}`. Then export the unified script from history with `agentia testing browser history --project <project-id> --lines-only > captured.robot`.
+
+### 2. Keeping Idle Sessions Warm (600s Timeout)
+- `session.sessionIdleTimeout` defaults to **600 seconds (10 minutes)** and is reset **only by executed keywords**.
+- The recorder's 3-second WebSocket heartbeat keeps the socket open but **does not reset the session idle timer**.
+- When waiting on a human to log in (e.g., MFA/SSO) or inspect the viewer, run a lightweight keepalive loop that fires `GetTitle` every 4 minutes:
+  ```sh
+  while true; do sleep 240; agentia testing browser execute --project <project-id> --line "GetTitle" --json || break; done &
+  ```
+  Stop the keepalive loop before `testing browser stop`.
+
+## Troubleshooting
+
+- **`No active CRT browser session`**: Start a session with `agentia testing browser start <job-id> --project <project-id>`. If a session died from the 600s idle timeout (`404` / `410`), Agentia clears the stale local state automatically on `status` or `stop`.
+- **`A CRT browser recorder is already running for session <id>`**: Another recorder holds the owner-scoped lock at `~/.agentia/testing-live/locks/<sessionId>.lock`. Stop the other process or pass `--force` if the prior process crashed.
+- **Keyword fails (`CRT browser keyword execution failed`)**:
+  1. Do not retry blindly. Run `agentia testing browser inspect --project <project-id> --json`.
+  2. Check if the target element has `isCovered: true` (modal/sticky header blocking it) or different `readableTexts`.
+  3. Check `agentia testing browser status --project <project-id> --json` to confirm `env.isWindowOpen: true` and `server.inFatalErrorState: false`.
+- **Browser window closed (`isWindowOpen: false`)**: Re-open Chrome with:
+  ```sh
+  agentia testing browser execute --project <project-id> --line "Open Browser    about:blank    chrome" --json
+  ```

package/templates/skills/agentia-testing/references/flow-automation.md

@@ -0,0 +1,112 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# Goal-Driven Flow Automation in CRT Browser Testing
+
+Use this methodology when turning a natural-language goal ("create a lead", "add a product to the cart and verify checkout") into a verified sequence of Robot Framework keywords against an active `agentia testing browser` session.
+
+Applies to `QWeb` (default), `--library QForce` (see [qforce.md](qforce.md) for Lightning-specific rules layered on top), and `--library QMobile`.
+
+## The Core Loop
+
+```text
+Observe -> Act (one logical step) -> Verify expected state -> Recover if needed -> Continue
+```
+
+Do **not** write an entire multi-page `.robot` script up front and fire it in one `testing browser execute --file` call. Every page transition is a hypothesis until confirmed against the browser session. Execute one logical step at a time, verify the transition, and then choose the next keyword. Batching is only appropriate for coupled inputs on the same verified view (such as `TypeText    Username    ...` + `TypeSecret    Password    ...`).
+
+```sh
+# 1. Act
+agentia testing browser execute --project <project-id> --line "GoTo    https://example.com" --json
+
+# 2. Verify
+agentia testing browser execute --project <project-id> --line "VerifyText    Example Domain" --json
+
+# 3. Observe interactive elements before the next decision
+agentia testing browser inspect --project <project-id> --json
+```
+
+## Choosing Locators (Priority Order)
+
+Always prefer semantic locators over structural XPaths:
+
+1. **Visible text** (`ClickText`, `TypeText`, `TypeSecret`, `VerifyText`, `DropDown`, `ClickCheckbox`). Disambiguate repeated text with `anchor=<nearby text>` before reaching for `index=<N>`.
+2. **Unique attribute** (`alt`, `title`, `tooltip`, `data-icon`) when there is no visible text — use `ClickItem` / `VerifyItem`.
+3. **XPath as a last resort** (`ClickElement`, `VerifyElement`) only when text and attribute locators cannot reach the element.
+
+While exploring unfamiliar pages, pass a short bounded timeout (`timeout=3`) so a wrong locator fails in 3 seconds instead of 10 seconds:
+
+```sh
+agentia testing browser execute --project <project-id> --line "ClickText    Sign In    timeout=3" --json
+```
+
+Drop the tight `timeout=3` override when curating the final exported `.robot` suite.
+
+## Why "Completed" Execution Still Needs Verification
+
+`testing browser execute` returning `status: "completed"` only proves the keyword ran without throwing an error—it does **not** prove that navigation succeeded, a form submitted, or a modal opened.
+
+After any state-changing keyword (`GoTo`, `Click*`, `Type*`, `DropDown`, `PickList`, `ComboBox`, `PressKey`), run a `Verify*` keyword targeting content **unique to the new state**:
+- After login -> verify dashboard heading or app navigation.
+- After opening a modal -> verify a field label inside the modal before typing.
+- After saving a record -> verify the saved state or record detail field.
+
+Watch for missing workflow transitions:
+- **Typed into a search box**: Append `\n` to the `TypeText` value to submit on Enter, or click the search button.
+- **Filled form fields**: Click `Save` / `Submit` before asserting the outcome.
+
+## Observing Page State: `inspect` + `screenshot` Overlay
+
+| Question | Command |
+| --- | --- |
+| Which interactive elements are visible? | `agentia testing browser inspect --project <project-id> --json` |
+| What does the viewport look like with detection boxes? | `agentia testing browser screenshot --project <project-id> --output /tmp/page.png --json` |
+| What is the raw HTML (`outerHTML`)? | `agentia testing browser inspect --project <project-id> --dom --json` |
+
+### Reading `inspect` and `screenshot` Together
+The PNG saved by `testing browser screenshot` is not a plain screenshot: the CRT inspection engine draws colored bounding rectangles (teal by default from `SetConfig    HighlightColor    teal`) around every detected UI element. Each rectangle corresponds to an entry in the `systemState` array from `testing browser inspect`:
+- `annotationIndex` — matches the numbered/boxed element in the detection pass.
+- `readableTexts` (`ownText`, `ariaLabel`, `nearbyTexts`) — exact strings to pass to `ClickText` / `TypeText` and `anchor=`.
+- `elementType` and `role` — distinguishes inputs, buttons, links, and `role="combobox"` lookups.
+- `isVisible`, `isInteractive`, `isEnabled`, `isCovered` — if `isCovered: true`, a modal, toast, or sticky header is covering the element and must be closed or scrolled past first.
+
+## Recovery Protocol
+
+When an action or verification fails:
+1. **Stop immediately.** Do not execute the next planned step.
+2. **Inspect first** (`testing browser inspect` and `testing browser screenshot`) — never retry blindly.
+3. **Compare expected vs. actual state**:
+   - *Still on the previous view?* A workflow transition (submit, save, menu click) didn't fire. Complete the transition rather than swapping locators.
+   - *On the expected view?* The locator was wrong. Pick up to 3 semantic alternatives directly from `systemState[].readableTexts` (`anchor=`, `ClickItem`, etc.).
+4. **Wrong-but-successful action** (e.g., clicked the wrong `New` button):
+   - Inspect where you landed, restore the prior view (`Back` or re-navigate), verify restoration, and retry with `anchor=<nearby text>` or `SetConfig    PartialMatch    False`.
+   - Remember that successful wrong clicks land in `testing browser history` (`status: "completed"`) — strip them when curating the final `.robot` file.
+
+## Tuning the Session for Agent-Driven Flows
+
+- **Exact text matching**: Bootstrap sets `PartialMatch    True`. On text-dense pages (especially Salesforce Lightning), switch to exact matching since you have exact `readableTexts` from `inspect`:
+  ```sh
+  agentia testing browser execute --project <project-id> --line "SetConfig    PartialMatch    False" --json
+  ```
+- **XHR-heavy pages**: Raise timeouts with `SetConfig    DefaultTimeout    20s` and `SetConfig    XHRTimeout    30s` instead of adding `Sleep`.
+
+## Exporting and Promoting the Proven Flow
+
+Failed probes (`status: "failed"`) are automatically excluded by `testing browser history`:
+
+```sh
+agentia testing browser history <job-id> --project <project-id> --lines-only > flow.robot
+```
+
+Curate `flow.robot` by removing exploratory detours, temporary `timeout=3` overrides, and duplicate steps, then wrap it in a standard Robot Framework suite for `agentia testing job files upload` and `agentia testing job run`:
+
+```robotframework
+*** Settings ***
+Library           QWeb
+Suite Setup       Open Browser    about:blank    chrome
+Suite Teardown    Close All Browsers
+
+*** Test Cases ***
+Verified Flow
+    GoTo          https://example.com
+    VerifyText    Example Domain
+```

package/templates/skills/agentia-testing/references/qforce.md

@@ -0,0 +1,88 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# QForce & Salesforce Lightning Reference for CRT
+
+QForce is Copado Robotic Testing's Salesforce keyword library. It is a superset of [QWeb](qweb.md): all QWeb keywords (`ClickText`, `TypeText`, `VerifyText`, `UseTable`, etc.) work unchanged, and QForce adds Salesforce Lightning-aware locators and keywords on top.
+
+To start a Salesforce browser session:
+
+```sh
+agentia testing browser start <job-id> --project <project-id> --library QForce --json
+agentia testing browser execute --project <project-id> --line "SetConfig    PartialMatch    False" --json
+```
+
+When these Salesforce-specific rules conflict with generic QWeb text-first guidance, **the Salesforce rule wins**.
+
+## Mandatory Salesforce Rules
+
+1. **Always normalize app state with `LaunchApp`**:
+   Immediately after login—and before any app-specific click, tab navigation, or assertion—run:
+   ```robotframework
+   LaunchApp    Sales
+   ```
+   `LaunchApp` is idempotent: it checks the active Lightning app and only opens the App Launcher when needed. Never skip it just because the right app appears open, and do not replace it with manual clicks on the App Launcher waffle icon.
+2. **Verify Record Details with `VerifyField`, never `VerifyText`**:
+   Lightning record pages contain repeated labels in headers, related lists, and activity timelines, causing `VerifyText` to pass for the wrong reason.
+3. **Three dropdown families require three distinct keywords**:
+   - Native HTML `<select>` -> `DropDown    <label>    <value>`
+   - Lightning custom picklist (button/div/listbox widget) -> `PickList    <label>    <value>`
+   - Lookup / searchable combobox (`input` with `role="combobox"`) -> `ComboBox    <locator>    <value>    timeout=10`
+4. **Lookups (`ComboBox`) only select existing records**:
+   Never finish a lookup field with `TypeText` (typed text is not a selected record). If the target record does not exist, use the nested `New <Object>` creation flow.
+5. **Never hard-code org-specific Lightning URLs or record IDs**:
+   Navigate via `LaunchApp` and object tabs so tests survive sandbox refreshes. Store credentials in CRT Variables (`testing variable`) or User Parameters (`testing user-parameter`) and type secrets with `TypeSecret`.
+
+## QForce Keyword Catalog
+
+In `.robot` files and `testing browser execute`, always use `KeywordCase` (`LaunchApp`, `VerifyField`, `PickList`, `ComboBox`). Separate arguments with 4+ spaces.
+
+| Keyword | Form | When to Use |
+| --- | --- | --- |
+| `LaunchApp` | `LaunchApp    <Exact App Name>` | Open a Salesforce Lightning app via the App Launcher by exact name (`Sales`, `Service`). |
+| `VerifyField` | `VerifyField    <label>    <expected>` | Assert a plain-text field value on a Record Details page (`VerifyField    Phone    123456789`). |
+| `VerifyField` (link) | `VerifyField    <label>    <expected>    tag=a` | Assert a linked field value (lookup, owner, related record: `VerifyField    Account Name    Acme    tag=a`). |
+| `VerifyField` (indexed) | `VerifyField    <label>    <expected>    <index>    [tag=a]` | Disambiguate when the same field label appears multiple times on the Details page. Discover `<index>` with `GetFieldValue` first. |
+| `GetFieldValue` | `GetFieldValue    <label>    [index]` | Read the value of the Nth field with `<label>` to discover which index to pass to `VerifyField`. |
+| `PickList` | `PickList    <label>    <value>    [index=1]    [timeout=0]` | Select an option from a Lightning custom picklist (`PickList    Stage    Closed Won`). |
+| `ComboBox` | `ComboBox    <locator>    <value>    timeout=10` | Search and select an **existing** record in a Lightning lookup/combobox (`ComboBox    Account Name    Acme    timeout=10` or `ComboBox    Search Accounts...    Acme    timeout=10`). |
+
+## Record Details Verification Ladder
+
+On a Salesforce record's **Details** tab, follow this order:
+
+1. **Plain field**: `VerifyField    <label>    <expected>`
+2. **Linked field (lookup/owner)**: `VerifyField    <label>    <expected>    tag=a`
+3. **Duplicate field label on page**: Probe indexes with `GetFieldValue`, then assert with indexed `VerifyField`:
+   ```robotframework
+   GetFieldValue    Account Name    1
+   GetFieldValue    Account Name    2
+   VerifyField      Account Name    Acme Corp    2    tag=a
+   ```
+4. **Never use `VerifyText` as the primary Details assertion**, and do not assert on ephemeral toast messages (toasts vanish quickly; verify the saved record's Details instead).
+
+## Lookup Fields & Nested Record Creation
+
+When filling a lookup field (such as `Account Name` on a Contact or Opportunity):
+
+- **If the target record exists**:
+  ```robotframework
+  ComboBox       Account Name    Acme Corp    timeout=10
+  ClickText      Save
+  ClickText      Details
+  VerifyField    Account Name    Acme Corp    tag=a
+  ```
+- **If `ComboBox` fails (`Could not find combobox ... with value ...`) or the record does not exist**:
+  Do not retry `ComboBox` in a loop and do not leave raw `TypeText` in the input. Trigger the nested `New <Object>` modal from the lookup instead:
+  ```robotframework
+  ClickText      Account Name
+  ClickText      New Account
+  TypeText       Account Name    Acme Corp
+  ClickText      Save
+  ```
+
+## Recognising Dropdown Types via `testing browser inspect`
+
+When unsure whether a field uses `DropDown`, `PickList`, or `ComboBox`, run `agentia testing browser inspect --project <project-id> --json` and check the element in `systemState`:
+- `elementType: "select"` -> `DropDown`
+- Clickable button/div showing the current picklist value (not an `input`) -> `PickList`
+- `elementType: "input"` with `role: "combobox"` or placeholder `Search ...` -> `ComboBox`

package/templates/skills/agentia-testing/references/qweb.md

@@ -0,0 +1,103 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# QWeb Keyword Reference for CRT
+
+QWeb is the web-automation Robot Framework library used by Copado Robotic Testing in `.robot` suites (`agentia testing job run`) and browser sessions (`agentia testing browser start <job-id> --project <project-id>`).
+
+For goal-driven exploration in a browser session, pair this reference with [flow-automation.md](flow-automation.md). For Salesforce Lightning, also load [qforce.md](qforce.md).
+
+## Syntax & Formatting Rules
+
+- **4+ space separator**: Separate the keyword name, positional arguments, and `key=value` named arguments with **at least 4 spaces** (`KeywordName    arg1    arg2    anchor=Header`). Never use a single space—Robot Framework treats `ClickText Login` as a single nonexistent keyword name.
+- **Prefer visible text over XPath**: `PartialMatch` is `True` by default in browser sessions (`SetConfig    PartialMatch    False` forces exact matches).
+- **`anchor=<text>` for disambiguation**: When the same text appears multiple times, pass `anchor=<nearby text>` (`ClickText    Edit    anchor=Profile`). Use 1-based `index=<N>` only as a last resort.
+- **Booleans**: Capitalize `True` and `False` (`clear=False`, `partial_match=False`).
+- **Submitting on Enter**: Append `\n` to `TypeText` (`TypeText    Search    laptop\n`) or run `PressKey    ${EMPTY}    {ENTER}`.
+- **XPath `=` escaping**: In browser testing (`testing browser execute`), Agentia automatically escapes `=` inside `//...` XPath tokens so Robot Framework does not misread `@id="x"` as a named parameter.
+
+## Keyword Catalog
+
+### Navigation
+
+| Keyword | Form | Notes |
+| --- | --- | --- |
+| `GoTo` | `GoTo    https://example.com` | Navigate to a full URL (`https://...`). |
+| `Back` / `Forward` | `Back` | Browser history navigation. |
+| `RefreshPage` | `RefreshPage` | Reload the current page. |
+| `Open Browser` | `Open Browser    about:blank    chrome` | Suite setup; already executed during `testing browser start` unless `--no-browser` is passed. |
+| `Close All Browsers` | `Close All Browsers` | Suite teardown. Do not call during an active browser session; use `testing browser stop` instead. |
+
+### Clicking
+
+| Keyword | Form | When to Use |
+| --- | --- | --- |
+| `ClickText` | `ClickText    <text>    [anchor=<text>]` | Default choice for any button, link, or tab with visible text. |
+| `ClickItem` | `ClickItem    <alt_or_title>    [anchor=<text>]` | Click by `alt`, `title`, `tooltip`, `data-tooltip`, or `data-icon` (ideal for icon-only buttons). |
+| `ClickElement` | `ClickElement    <xpath>` | Last resort when neither `ClickText` nor `ClickItem` can target the element. |
+| `ClickCheckbox` | `ClickCheckbox    <label>    on\|off` | Idempotently set a checkbox to `on` or `off`. |
+| `ClickList` | `ClickList    <list_locator>    <item_text>` | Click an item inside a list widget. |
+| `ClickCell` | `ClickCell    <row>    <col>` | Click a cell inside the active table (requires `UseTable` first). |
+
+### Typing & Form Inputs
+
+| Keyword | Form | Notes |
+| --- | --- | --- |
+| `TypeText` | `TypeText    <label>    <value>    [clear=False]` | Clears the field and types `<value>`. Append `\n` to submit. |
+| `TypeSecret` | `TypeSecret    <label>    <value>` | Same as `TypeText`, but masks the value in logs and Agentia browser history. |
+| `DropDown` | `DropDown    <label>    <option>` | Select an option from a native HTML `<select>` element. |
+| `GetInputValue` | `GetInputValue    <label>` | Read the current value of an input field. |
+
+### Verification & Reading
+
+| Keyword | Form | Notes |
+| --- | --- | --- |
+| `VerifyText` | `VerifyText    <text>    [timeout=30]` | Assert visible text appears on the page (preferred over `Sleep` for waiting). |
+| `VerifyNoText` | `VerifyNoText    <text>    [timeout=10]` | Assert text does not appear (or disappears). |
+| `VerifyItem` | `VerifyItem    <alt_or_title>` | Assert an element with the given `alt`/`title`/`tooltip` exists. |
+| `VerifyElement` | `VerifyElement    <xpath>    [timeout=30]` | Assert an XPath exists in the DOM. |
+| `VerifyValue` | `VerifyValue    <label>    <expected>` | Assert an input field holds `<expected>`. |
+| `VerifyCheckboxValue` | `VerifyCheckboxValue    <label>    on\|off` | Assert a checkbox state. |
+| `GetText` | `GetText    <locator>` | Read visible text of an element. |
+| `GetAttribute` | `GetAttribute    <locator>    <attribute>` | Read an attribute (e.g., `href`, `aria-expanded`, `outerHTML`). |
+| `GetTitle` | `GetTitle` | Read the document title (also useful as a harmless keepalive keyword in browser sessions). |
+
+### Hover, Scroll, Drag & Keyboard
+
+| Keyword | Form | Notes |
+| --- | --- | --- |
+| `HoverText` / `HoverElement` | `HoverText    <text>` | Hover over an element to reveal menus or tooltips. |
+| `Scroll` | `Scroll    <locator>    page_down\|page_up\|<px>` | Scroll an element or `//html` for the full page. |
+| `ScrollTo` | `ScrollTo    <text_locator>` | Scroll until `<text_locator>` is in view. |
+| `DragDrop` | `DragDrop    <source>    <target>` | Drag one element onto another. |
+| `PressKey` | `PressKey    <locator>    <key>` | Use `${EMPTY}` for global key press (`{ENTER}`, `{ESC}`, `{TAB}`). |
+
+### Stateful Tables
+
+Call `UseTable` once to bind the active table, then address cells by 1-based row/column (`r1`, `c2`) or header/row text:
+
+```robotframework
+UseTable       Users
+ClickCell      r1    Email
+VerifyTable    r1    Status    Active
+```
+
+### Configuration (`SetConfig`)
+
+| Setting | Example | Purpose |
+| --- | --- | --- |
+| `DefaultTimeout` | `SetConfig    DefaultTimeout    20s` | Global auto-wait timeout for locators (default `10s`). |
+| `XHRTimeout` | `SetConfig    XHRTimeout    30s` | Wait for pending XHR/network activity before acting. |
+| `PartialMatch` | `SetConfig    PartialMatch    False` | Require exact text matches instead of substring matches. |
+| `CaseInsensitive` | `SetConfig    CaseInsensitive    True` | Enable case-insensitive text matching. |
+| `ClickToFocus` | `SetConfig    ClickToFocus    True` | Click inputs before typing (enabled by default in browser sessions). |
+
+## Decision Tree
+
+1. **Open a URL** -> `GoTo    https://...`
+2. **Click readable text** -> `ClickText    <text>` (add `anchor=<nearby>` if repeated)
+3. **Click an icon/image with no text** -> `ClickItem    <alt_or_title>`, else `ClickElement    <xpath>`
+4. **Type into a field** -> `TypeText    <label>    <value>` (or `TypeSecret` for passwords/tokens)
+5. **Select from a native `<select>`** -> `DropDown    <label>    <option>`
+6. **Toggle a checkbox** -> `ClickCheckbox    <label>    on`
+7. **Wait for page readiness** -> `VerifyText    <landmark>    timeout=30` (avoid `Sleep`)
+8. **Work with a table** -> `UseTable    <table_name>` -> `VerifyTable` / `ClickCell`

package/templates/skills/agentia-testing/references/tests.md

@@ -46,7 +46,7 @@ agentia testing job runs logs <build-id> --project <project-id> --job <job-id> -
 | Variables | `testing variable list|get|create|update|delete` |
 | User parameters | `testing user-parameter list|get|create|update|delete` |
 | Data tables | `testing data-table list|get|create|update|delete|export` |
-| Live testing | `testing live start|stop|status|execute|continue|interrupt|inspect|screenshot|reports|set-options|history|view|recorder` |
+| Browser testing | `testing browser start|stop|status|execute|inspect|screenshot|set-options|history|view|recorder` |
 
 `testing job` is the single namespace for test definitions and their runs. Commands directly under `job` take a job ID; `job runs get|logs|abort` take a build/run ID plus `--job`. On `testing job create` and `testing job update`, `--[no-]show-video-params` (`showVideoParams` in the API/MCP) enables or disables Video Streaming and Recording capabilities when running the test job. The older `testing create|update|status|logs|run`, `testing test ...`, `testing build ...`, and `testing job files|upload|download` forms are deprecated aliases that still execute but warn when used: `create` maps to `job create`, `update` to `job files upload` (file operations, not `job update`), `status`, `build list`, and `build latest` to `job runs list`, `build get` to `job runs get`, and `build search|logs|abort` to `job runs search|logs|abort`.
 
@@ -65,19 +65,27 @@ Schedules support get, set with cron/timezone/record policy, and remove. Data ta
 
 Data-table create/update/delete and existing-file overwrite are protected operations. Never overwrite or delete without user intent.
 
-## Live Testing
+## Browser Testing
 
 Use a regression-owned job:
 
 ```sh
-agentia testing live start <job-id> --project <project-id> --json
-agentia testing live status --project <project-id> --json
-agentia testing live execute --project <project-id> --line "GoTo  https://example.com" --json
-agentia testing live inspect --project <project-id> --json
-agentia testing live stop --project <project-id> --yes --json
+agentia testing browser start <job-id> --project <project-id> --json
+agentia testing browser status --project <project-id> --json
+agentia testing browser view --project <project-id> --no-open --json
+agentia testing browser execute --project <project-id> --line "GoTo    https://example.com" --json
+agentia testing browser inspect --project <project-id> --json
+agentia testing browser history <job-id> --project <project-id> --lines-only
+agentia testing browser stop --project <project-id> --yes --json
 ```
 
-Live viewer secrets remain in the keychain. Session cookies and XSRF values are in-memory only. `view` opens an authenticated page without putting secrets in the URL. `recorder` is long-running and uses an owner-scoped local lock; neither `view` nor `recorder` is exposed through MCP.
+Always pass `--no-open` to `testing browser view` by default to print/return the interactive CRT browser session URL without launching a browser; omit `--no-open` only when the user explicitly asks to open the browser. Session cookies and XSRF values remain in-memory only. `recorder` is long-running and uses an owner-scoped local lock (`--force` reclaims a stale lock); neither `view` nor `recorder` is exposed through MCP. The older `testing live ...` commands remain available as deprecated aliases, except `continue` and `interrupt`, which were removed.
+
+For deep browser-testing guidance, load:
+- [browser-testing.md](browser-testing.md) — subcommands, flags, parallel recorder subagent pattern, 600s idle keepalive, and troubleshooting
+- [flow-automation.md](flow-automation.md) — Observe -> Act -> Verify -> Recover loop and reading `screenshot` detection overlays with `inspect` `systemState`
+- [qweb.md](qweb.md) — QWeb keyword catalog, 4+ space separator rule, and locator priority
+- [qforce.md](qforce.md) — Salesforce Lightning rules (`--library QForce`, `LaunchApp`, `VerifyField`, `PickList`, `ComboBox`)
 
 ## Secret Inputs And Redaction
 
@@ -90,7 +98,7 @@ Live viewer secrets remain in the keychain. Session cookies and XSRF values are
 
 Destructive or protected CLI actions prompt in an interactive TTY. JSON and non-TTY calls require `--yes`. Matching MCP tools require `confirm: true`, not a `yes` field.
 
-This applies to resource deletion, build abort, schedule removal, live stop, protected data-table imports/deletion, and output overwrite.
+This applies to resource deletion, build abort, schedule removal, browser stop, protected data-table imports/deletion, and output overwrite.
 
 ## Gotchas
 

package/dist/commands/testing/live/continue.js

@@ -1,16 +0,0 @@
-import { AgentiaCommand } from '../../../lib/agentia-command.js';
-import { runTestingLiveControlCommand, testingLiveCommonFlags, testingLiveOptionalJobArg, } from '../../../lib/testing-live-command.js';
-export default class TestingLiveContinue extends AgentiaCommand {
-    static args = testingLiveOptionalJobArg;
-    static description = 'Continue paused Robot execution in the active CRT live session';
-    static examples = ['<%= config.bin %> <%= command.id %> --project <project-id>'];
-    static flags = testingLiveCommonFlags;
-    async run() {
-        const { args, flags } = await this.parse(TestingLiveContinue);
-        return runTestingLiveControlCommand('continue', args, flags, {
-            display: (fn) => this.display(fn),
-            log: (msg) => this.log(msg),
-        });
-    }
-}
-//# sourceMappingURL=continue.js.map

package/dist/commands/testing/live/execute.js

@@ -1,43 +0,0 @@
-import { Flags } from '@oclif/core';
-import { AgentiaCommand } from '../../../lib/agentia-command.js';
-import { testingLiveCommonFlags, testingLiveOptionalJobArg } from '../../../lib/testing-live-command.js';
-import { executeTestingLive } from '../../../lib/testing-live-operations.js';
-export default class TestingLiveExecute extends AgentiaCommand {
-    static args = testingLiveOptionalJobArg;
-    static description = 'Execute bounded Robot Framework keywords in an active CRT live session';
-    static examples = [
-        '<%= config.bin %> <%= command.id %> --project <project-id> --keyword GoTo --arg https://example.com',
-        '<%= config.bin %> <%= command.id %> <job-id> --project <project-id> --file smoke.robot --section Login',
-    ];
-    static flags = {
-        ...testingLiveCommonFlags,
-        arg: Flags.string({ description: 'Keyword argument. Repeat to preserve argument boundaries.', multiple: true }),
-        file: Flags.string({ description: 'Robot Framework input file.' }),
-        keyword: Flags.string({ description: 'Robot Framework keyword name.' }),
-        line: Flags.string({ description: 'Raw Robot Framework keyword line. Repeat for multiple lines.', multiple: true }),
-        raw: Flags.boolean({ default: false, description: 'Treat file input as raw keyword lines.' }),
-        section: Flags.string({ description: 'Robot test/task name to execute.' }),
-        'section-index': Flags.integer({ description: 'One-based Robot test/task index to execute.', min: 1 }),
-    };
-    async run() {
-        const { args, flags } = await this.parse(TestingLiveExecute);
-        const supplied = [flags.keyword !== undefined, flags.file !== undefined, (flags.line?.length ?? 0) > 0].filter(Boolean);
-        if (supplied.length !== 1)
-            throw new Error('Use exactly one of --keyword, --line, or --file.');
-        const result = await this.withSpinner('Executing CRT live keyword', () => executeTestingLive({
-            args: flags.arg,
-            file: flags.file,
-            jobId: args['job-id'],
-            keyword: flags.keyword,
-            lines: flags.line,
-            projectId: flags.project,
-            raw: flags.raw,
-            section: flags.section,
-            sectionIndex: flags['section-index'],
-            sessionId: flags['session-id'],
-        }));
-        this.display(() => this.log(`Execution ${result.executionId}: ${result.status}`));
-        return result;
-    }
-}
-//# sourceMappingURL=execute.js.map

package/dist/commands/testing/live/history.js

@@ -1,40 +0,0 @@
-import { Args, Flags } from '@oclif/core';
-import { AgentiaCommand } from '../../../lib/agentia-command.js';
-import { testingLiveCommonFlags } from '../../../lib/testing-live-command.js';
-import { getTestingLiveHistory } from '../../../lib/testing-live-operations.js';
-import { readTestingLiveState } from '../../../lib/testing-live-state.js';
-export default class TestingLiveHistory extends AgentiaCommand {
-    static args = {
-        'job-id': Args.integer({ description: 'CRT job ID; defaults to the active session.', required: false }),
-    };
-    static description = 'Read bounded sanitized local CRT live execution history';
-    static examples = ['<%= config.bin %> <%= command.id %> <job-id> --project <project-id> --limit 20 --json'];
-    static flags = {
-        ...testingLiveCommonFlags,
-        limit: Flags.integer({ default: 10, description: 'Maximum records to return.', max: 500, min: 1 }),
-        status: Flags.option({
-            description: 'Execution status filter.',
-            options: ['completed', 'failed', 'recorded'],
-        })(),
-    };
-    async run() {
-        const { args, flags } = await this.parse(TestingLiveHistory);
-        const active = args['job-id'] === undefined ? await readTestingLiveState() : undefined;
-        const jobId = args['job-id'] ?? active?.jobId;
-        if (jobId === undefined || (active !== undefined && active.projectId !== flags.project)) {
-            throw new Error('Provide a job ID or start a live session for this project.');
-        }
-        const result = getTestingLiveHistory({
-            jobId,
-            limit: flags.limit,
-            projectId: flags.project,
-            status: flags.status,
-        });
-        this.display(() => {
-            for (const execution of result.executions)
-                this.log(`${execution.startedAt} [${execution.status}] ${execution.lines.join(' | ')}`);
-        });
-        return result;
-    }
-}
-//# sourceMappingURL=history.js.map

package/dist/commands/testing/live/inspect.js

@@ -1,31 +0,0 @@
-import { Flags } from '@oclif/core';
-import { AgentiaCommand } from '../../../lib/agentia-command.js';
-import { testingLiveCommonFlags, testingLiveOptionalJobArg } from '../../../lib/testing-live-command.js';
-import { inspectTestingLive } from '../../../lib/testing-live-operations.js';
-import { formatTestingRecord } from '../../../lib/testing-types.js';
-export default class TestingLiveInspect extends AgentiaCommand {
-    static args = testingLiveOptionalJobArg;
-    static description = 'Inspect bounded, sanitized page state from an active CRT live session';
-    static examples = [
-        '<%= config.bin %> <%= command.id %> --project <project-id> --json',
-        '<%= config.bin %> <%= command.id %> --project <project-id> --dom --output page.html',
-    ];
-    static flags = {
-        ...testingLiveCommonFlags,
-        dom: Flags.boolean({ default: false, description: 'Fetch raw page DOM; requires --output.' }),
-        output: Flags.string({ dependsOn: ['dom'], description: 'Explicit file path for raw DOM.' }),
-    };
-    async run() {
-        const { args, flags } = await this.parse(TestingLiveInspect);
-        const result = await this.withSpinner('Inspecting CRT live session', () => inspectTestingLive({
-            dom: flags.dom,
-            jobId: args['job-id'],
-            output: flags.output,
-            projectId: flags.project,
-            sessionId: flags['session-id'],
-        }));
-        this.display(() => this.log(flags.dom ? `DOM written to ${String(result.path)}.` : formatTestingRecord(result)));
-        return result;
-    }
-}
-//# sourceMappingURL=inspect.js.map

package/dist/commands/testing/live/interrupt.js

@@ -1,16 +0,0 @@
-import { AgentiaCommand } from '../../../lib/agentia-command.js';
-import { runTestingLiveControlCommand, testingLiveCommonFlags, testingLiveOptionalJobArg, } from '../../../lib/testing-live-command.js';
-export default class TestingLiveInterrupt extends AgentiaCommand {
-    static args = testingLiveOptionalJobArg;
-    static description = 'Interrupt Robot execution in the active CRT live session';
-    static examples = ['<%= config.bin %> <%= command.id %> --project <project-id>'];
-    static flags = testingLiveCommonFlags;
-    async run() {
-        const { args, flags } = await this.parse(TestingLiveInterrupt);
-        return runTestingLiveControlCommand('interrupt', args, flags, {
-            display: (fn) => this.display(fn),
-            log: (msg) => this.log(msg),
-        });
-    }
-}
-//# sourceMappingURL=interrupt.js.map