---
name: kane-ai
description: Author, run, and evolve end-to-end tests in natural language with KaneAI - TestMu AI's GenAI-native testing agent for web and mobile. Use to author no-code automated UI/API tests, phrase reliable natural-language test steps, use variables/parameters/secrets, add conditionals and While loops, run on the cloud grid, and trigger test runs from CI/CD.
---

# KaneAI - GenAI-Native Test Authoring Skill

Use **KaneAI** to author, run, and maintain **durable, versioned end-to-end tests** for web and mobile apps by describing them in **plain English** - no code. KaneAI converts your natural-language instructions into executable automation steps, runs them on TestMu AI's cloud grid (**HyperExecute**), saves every run to **Test Manager**, and **auto-heals** locators at runtime when the UI changes.

**When to use KaneAI vs. `kane-cli`:**

| Use **KaneAI** when... | Use **`kane-cli`** when... |
|---|---|
| You want a **saved, replayable, versioned** test in Test Manager | You want a **one-shot** browser task from the terminal |
| Authoring desktop web, mobile web, **or** mobile-app tests | Local Chrome browser automation only |
| The test is part of a suite / CI pipeline / regression run | Ad-hoc "navigate, click, verify" from an agent or CI script |
| You need auto-heal, cross-browser matrix, API+UI+DB in one flow | You need NDJSON output parsed by a coding agent |

KaneAI is a **web platform** (part of Test Manager), not a CLI. A coding agent cannot "click through" the authoring UI, but it **can**:
1. Emit the **exact natural-language grammar** KaneAI expects (Sections 5-8), so a human or agent authors reliable steps the first time.
2. **Trigger KaneAI test runs programmatically** from CI/CD via the HyperExecute API (Section 12).
3. Comment **`@KaneAI Validate this PR`** on a GitHub pull request once the GitHub App is set up (Section 13).

---

## 1. Decision Tree

**Do you have a TestMu AI account with KaneAI access?**
- No -> Register at https://www.testmuai.com/register/ (Section 3)
- Yes -> continue below

**What does the user want?**
- Author a **desktop web** UI test -> Section 4a + grammar (Section 5)
- Author a **mobile web** (browser-on-device) test -> Section 4a, choose the mobile browser platform
- Author a **mobile app** (Android/iOS) test -> Section 4b
- Repeat steps / poll / iterate -> **While Loops** (Section 6b - slash command only, never natural language)
- Branch on page state -> **If/Else** conditionals (Section 6a)
- Test an **API** inside a test -> Section 9
- Reuse values / credentials / dynamic data -> Section 8 (Variables, Parameters, Secrets, Smart Variables)
- **Run / schedule** an existing test on the cloud -> Section 10
- **Trigger** a saved test run from CI/CD -> Section 12 (HyperExecute API)
- Validate a **GitHub PR** automatically -> Section 13 (GitHub App)
- A test is failing / blocked -> Section 14 (Troubleshooting & FAQs)

**When writing instructions for KaneAI, always:**
1. Use imperative, specific phrasing ("click the 'Add to Cart' button", not "add the item").
2. Break complex tasks into small steps connected with `then` / `after that`; never chain unrelated actions in one instruction.
3. Add **assertions** to validate outcomes (Section 7).
4. Parameterize credentials and environment URLs with variables/secrets (Section 8), never hardcode them.
5. If a step misfires, **refine the prompt and reissue it** - iterative refinement is the documented workflow.

---

## 2. What KaneAI Is (and how it fits)

> "KaneAI is a GenAI-native end-to-end AI testing agent for autonomous test automation. Author, run, and evolve tests in plain English, no code, on web and mobile."

- **Author in natural language.** Describe steps like a to-do list; KaneAI translates them into executable test steps automatically. Keep adding steps in plain English as you go - KaneAI queues them for execution, so you don't wait for one to finish before writing the next.
- **Or record.** **Manual Interaction** mode captures actions you perform directly in the instance window and converts them into natural-language test steps (Section 4c - with important limitations).
- **From ideas to tests.** Drop in a Jira ticket, PRD, PDF, screenshot, or spreadsheet and get structured test cases back.
- **Runs on the cloud.** Tests execute on **HyperExecute** across **3000+ combinations of browsers, real devices & OS**.
- **Auto-heals at runtime.** Every element gets multiple locators at code-generation time; failed locators fall back sequentially, and if all fail KaneAI rebuilds the locator on the fly from the original natural-language instruction (Section 11).
- **Human-in-the-loop.** KaneAI drafts reviewable steps; you can pause mid-run, correct a step, and configure per-step failure behavior. Your input always overrides the agent.
- **Layers in one flow.** Web, mobile, UI, API, database, network, and accessibility coverage, then **export** code so you are never locked in.
- **Multilingual authoring** - write instructions in any language; KaneAI translates to English to understand context, then acts.

**Terminology note:** the product is written **KaneAI** (one word). The brand is **TestMu AI** (formerly LambdaTest). Several product URLs and API hosts still use `lambdatest.com` domains - those are correct, do not "fix" them.

---

## 3. Setup & Prerequisites

- A **TestMu AI account** with KaneAI access (register at https://www.testmuai.com/register/).
- **KaneAI homepage** (authoring entry point): https://www.testmuai.com/login/?redirectTo=https://kaneai.lambdatest.com/objective
- A **Test Manager project** (and optionally a folder) to save test cases into.
- For CI/CD triggering (Section 12): your **TestMu AI username** and **access key**, and a project with KaneAI-generated test cases.

---

## 4. Authoring a Test (the core workflow)

### 4a. Web Test (desktop or mobile browser)

1. From the **KaneAI homepage**, click **Create a Web Test** (select the **Desktop Browser** or mobile browser platform).
2. (Optional) Configure **Advanced Settings** before starting - see Section 4d for Chrome Options and Custom Headers.
3. Click **Start Testing** to launch the session.
4. **Tell KaneAI what to author in natural language** (Section 5). Keep adding steps in plain English - KaneAI queues them automatically.
5. (Optional) Use **Manual Interaction** to perform steps directly in the instance window (Section 4c).
6. Click **Finish Test** to finalize the test case.
7. Save the test case: **Project**/folder, **Test Name** and **Description** (auto-generated, editable), **Type**, **Status**, tags.
8. To execute, click the **HyperExecute** button -> you're redirected to the HyperExecute dashboard (https://hyperexecute.lambdatest.com/hyperexecute/jobs).

### 4b. Mobile App Test (Android / iOS)

1. From the **KaneAI homepage**, click **Create an App Test**.
2. Select your **operating system** (Android or iOS), then **upload your application**.
3. (Optional) Configure **Advanced Settings** (Section 4d).
4. Click **Start Testing**.
5. Author steps in natural language (Section 5 - including app-specific commands) and/or use **Manual Interaction** (Section 4c).
6. Click **Finish Test**, save the test case (Project/folder, Name, Description, Type, Status, tags).
7. Click the **HyperExecute** button to execute.

> **Verify before saving:** use the **re-run** option to confirm every step executes cleanly before saving. While editing an existing test, let the run validate the flow and click **Resume** only after all steps complete.

### 4c. Manual Interaction (record-mode) - capabilities & limits

Enable via the **Manual Interaction** button in an authoring session; exit with **Turn off Manual Interaction**. Actions you perform are captured and converted into natural-language test steps.

**Not supported in Manual Interaction - add these via written instructions instead:**
- **Assertions** - verify/confirm/assert steps can't be recorded.
- **If-Else logic** and **While loops**.
- **Modules** and reusable blocks.
- **Variables, Parameters, and Secrets** - not detected during manual steps (you can convert hardcoded Click/Type values afterwards - see Section 8).
- **Datasets / dynamic data.**

**Recording limitations by platform:**
- Web: drag-and-drop on canvas elements and mouse **hover** are not recorded. (Double click, right click, and long press **are** supported.)
- Mobile: two-finger scroll, copy/paste, recent-apps actions, keyboard actions like backspace, and system-level popups (permission dialogs) are not captured.
- Text input: **all characters you attempt to type are recorded**, even ones the field rejects (e.g. letters typed into a numeric field appear in the instruction).
- Editing: recorded steps allow **only the locator name** to be edited - to change anything else, delete and re-record or rewrite as natural language.

**Pause Recording:** click **Pause Recording** in the Manual Interaction toolbar to interact freely (login, cookie banners, navigation) without adding steps - the session shows **Draft** state. Click **Start recording** to resume capture. If steps stop being recorded mid-session, check whether you're paused in Draft state.

### 4d. Advanced Settings (Chrome Options, Custom Headers, and more)

**Chrome Options** *(Desktop Web only)* - command-line switches applied when launching the browser:
- Up to **10 options** per session; each takes a **String or File** argument type.
- Examples: `--headless`, `--disable-gpu`, `--use-file-for-fake-audio-capture=/path/to/file`.
- KaneAI validates options - unsupported ones are rejected with an error.
- Options needing a file path get the **Downloads folder path auto-injected** - don't hand-write absolute paths.

**Custom Headers** *(Desktop Web and Mobile Web)* - inject additional HTTP headers (tokens, session IDs, content-type overrides, custom metadata) into **every request** in the session, including navigation and API calls:
- Up to **10 headers** per session, added as Header Name + Header Value rows.
- Each header value has a **Type**: **String** (plain text) or **Secret** - reference an org-level secret with `{{secrets.org.<secret_name>}}` to keep tokens out of plain text.
- Providing a default header (e.g. `Accept`) **overrides** the browser's default value.
- View them during a session via **Advanced Settings** in the top nav, or afterwards on the **Test Summary** page.

**Platform matrix highlights:** Android app sessions add Auto-login through Google, GPS location mocking, biometric authentication (Android 11+), image/video injection, network throttling, timezone/language. iOS adds Auto-Accept/Dismiss Alerts. Mobile **web** sessions get Custom Headers but **not** biometric/image/video injection.

**Editing settings after authoring:** on the **Test Summary** page, click **Edit Test Steps** to open the advanced-settings panel. **Apply Settings** saves them and **generates a new version of the test case with regenerated code** (no in-place update); choose **Edit Test Steps** instead if the changed settings require adjusting steps. Only advanced settings can be changed here - steps, OS, browser, or device changes need the playground.

---

## 5. Writing Instructions: the Natural-Language Command Grammar

The grammar below applies across **Web, Mobile Web, and App (Android/iOS)** unless a platform limit is noted.

> **Best practices (from the official writing guidelines):** be clear and specific - never "click that" or "do this", give element context ("the 'Submit' button on the top right of the form"), break tasks into small steps joined by `then` / `after that`, don't overload one instruction with unrelated actions, use numbers for positions and quantities ("click on the second product in the list"), avoid jargon, if a step misfires, refine the prompt and reissue it.

### Navigation & Page Interaction

| Action | Example instruction |
|---|---|
| Open URL | `go to https://example.com`, `open https://example.com` |
| Click | `click on login button` |
| Multi-click | `double click the title`, `click the button 5 times` |
| Right click *(web only)* | `right click on the file row` |
| Long press | `long press the menu icon for 3 seconds` |
| Type text | `enter "user@example.com"`, `type "password123"`, `Type "2" in "username" input field` |
| Clear field | `clear email input field` |
| Select date | `select 21st september date` |
| Hover | `hover on shop by category option` |
| Search | `search for "laptop"` |
| Refresh | `refresh the page` |
| Navigate | `go back`, `navigate back`, `go forward`, `navigate forward` |

**Click variants - limits & disambiguation:**
- **Long press**: default **1 second**; range **0.5-30 seconds**, **seconds only** (minutes/hours rejected). Trigger phrases: `long press`, `press and hold`, `tap and hold`, `hold down`. `press the login button` is a normal click; `press Enter` is a key press.
- **Multi-click**: maximum **20 clicks per instruction** (higher values rejected as `INVALID_PARAMETER`). Use `click X N times` for N >= 3 - the phrase `triple click X` is **not supported**. `tap twice`/`tap thrice` = 2/3 taps; on mobile, click and tap are interchangeable.
- **Right click**: aliases `right-click`, `context click`, `secondary click`. The word *right* must modify the verb - `click the right panel` / `click the button on the right` are normal clicks. **Web only** - returns `UNSUPPORTED_OPERATION` on mobile; use long press for mobile context menus.
- **Mutually exclusive**: long press + multi-click, right click + long press, right click + multi-click each return `INVALID_PARAMETER` (e.g. `long press the button 3 times` fails).
- Parameterization works - `long press the button for ${hold_duration} seconds`, `click the button ${click_count} times` - but **secret values can't be used as numeric durations**.

**Disambiguation tip:** name the element type in quotes to improve accuracy - `Click on abc 'button'`, `Click on continue 'text'`.

### App-Specific Commands (Android / iOS)

| Situation | Instruction |
|---|---|
| OTP/PIN split across boxes | `Enter OTP "1234"` (use the keyword **OTP**) |
| Partially clickable text | `Click on spannable text: "Terms and Conditions" in bottom info modal` |
| Popup without a close button | `dismiss dialog` |
| Hide keyboard (Android) | `hide keyboard` |
| Dismiss keyboard (iOS) | `Type abcd and press enter` (iOS keyboards are persistent; `press enter` after typing) |
| Delete characters | `press Del` |
| Picker wheels / sliders / date pickers | `Enter "2" in first column` |

Picker support covers `android.widget.NumberPicker`, `android.widget.SeekBar`, `XCUIElementTypePickerWheel`, `XCUIElementTypePicker`, `XCUIElementTypeDatePicker`, `XCUIElementTypeSlider`. If a picker step fails, verify the element class with the App Live UI Inspector.

### Waits & Timeouts

- **Every element interaction automatically includes a default maximum wait of 10 seconds** for the element to become interactable.
- **Add explicit waits after actions that trigger slow loads** - the official guideline: `Click on Submit button` -> `Wait for 3 seconds` -> `Assert confirmation text is visible`. After scrolling, add a short wait (`Scroll down 2 times` -> `Wait for 2 seconds`).
- Explicit wait: `wait for 5 seconds`
- **Step Timeout** (custom ceiling): step three-dot (...) menu -> **Step Timeout** -> 1-300 seconds. It's a *dynamic ceiling* - the step proceeds as soon as the element is ready. Applies **only to element-based interactions** (Click/Tap, Type, Search, Clear); it has no effect on fixed waits, assertions, or API steps. Supported on Web, Mobile Web, and App (Android and iOS real devices).

### Tab Management

- Open a new tab: `Open amazon.com in a new tab` - **then explicitly switch context** before interacting with it.
- Switch: `Switch to 2nd tab`, `Switch to Lambdatest tab` - tabs are **1-indexed in the order opened**; switching to a closed or nonexistent tab **fails**.
- Close: `Close Lambdatest tab`, `Close 2nd tab`

### Scrolling

| Action | Example |
|---|---|
| Scroll until element visible *(web only)* | `scroll until the Submit button is visible` - works for whole pages **and scrollable subsections** |
| Scroll by amount | `Scroll by 100px`, `Scroll by 20 percent` |
| Scroll to position | `Scroll to the bottom`, `Scroll to the top` |
| Repeat scroll | `Scroll 3 times` |

### Query Information

Extract information from the page:
- `query the current URL`
- `query the time mentioned in the poster`

---

## 6. Control Flow: Conditionals & While Loops

### 6a. If / Else conditionals

Insert a conditional block from the **/** slash command menu (**Add If-Else**) during authoring, or from **+ Add step** while paused. Simple one-line conditions also work as natural-language steps:

```
if pop up is present in the viewport then click on it
if price < 200 then click add to cart else select second product
```

- Conditions are defined in **natural language** (default) or **operand & operator** mode (toggle via the switcher icon). Operators: `==, !=, >, <, >=, <=, contains, not_contains, starts_with, ends_with`.
- Combine multiple conditions with **AND/OR** (click **+ Add condition**, toggle the logical operator, confirm with the green checkmark).
- Up to **5 Else-If branches** per block. Each branch (If / Else-If / Else) supports regular steps, modules, JavaScript, API, DB steps, and manual interaction. Close the block with **End If**.
- Authoring vs run: while authoring, only the matching branch executes (other branches queue); at run time KaneAI evaluates conditions **top-to-bottom** and executes the first matching branch.
- **Nested conditionals are not supported** - split logic across test cases or use Else-If branches.

### 6b. While Loops

> **Warning: Natural language cannot create a loop.** Steps like *"repeat this 10 times"* or *"while the spinner is visible, do X"* fail with `WHILE_NOT_SUPPORTED_VIA_NL`. A While Loop is added **only** via the slash command: press **/** -> **Add While Loop**. (Feature is rolling out gradually - if it's missing from your slash menu, contact support.)

**Authoring workflow:**
1. Press **/** -> **Add While Loop** - an empty block is inserted.
2. Define the **condition** - natural language (default) or operand & operator mode:
   - NL examples: `while the loading spinner is visible`, `while the Next button is present`, `while {{count}} is greater than 0`, `while {{job_status}} is not "complete"`
   - Operators: `==, !=, >, <, >=, <=, contains, not_contains, starts_with, ends_with, is_visible, is_not_visible`. Operands may be variables `{{x}}`, dataset parameters `${x}`, extracted text, or literals.
3. Confirm the condition - the loop body opens. Add any step types: natural-language steps, modules, JavaScript, API, DB, manual interaction, and **If/Else blocks**.
4. Click **End While** to finalize - **execution starts immediately**. (End While activates only after the condition is confirmed **and** at least one body step exists.)

**Execution semantics:** the condition is re-evaluated **before every iteration**; false -> clean exit to the next step. If the condition is false on the first check, **zero iterations** run. For UI conditions (spinner visible, etc.) KaneAI auto-inserts the underlying visual/DOM query each iteration - no manual query step needed. Use **Pause While** to interrupt and inspect.

**`{{loop_counter}}`** - built-in, **1-indexed**, available to every step type in the body including element selectors:
```
Click the row at position {{loop_counter}} in the bookings table
```
(A selector like `tr:nth-of-type({{loop_counter}})` targets row 1, then 2, ...). Not available outside the loop body.

**Dynamic iteration count pattern:**
1. JS step reads the count into `{{total}}`.
2. While Loop with condition `{{loop_counter}} <= {{total}}`.
3. Repeatable steps in the body.

**Hard limits & rules:**

| Rule | Detail |
|---|---|
| **Max 30 iterations** per execution | Fixed, not configurable. Exceeding it fails the step with `LOOP_MAX_LIMIT_REACHED`. |
| No Break / Continue | Structure the condition to terminate naturally. |
| No For-Each construct | Iterate collections with a While Loop + JS steps for index management. |
| Nesting | A While Loop **can** contain If/Else blocks (max depth: 2 levels). **Not allowed:** While inside While; While inside an If/Else branch. |
| Operands | Both operands cannot be parameters (`BOTH_OPERANDS_AS_PARAMETERS`) - at least one side must be runtime-updated. Valid: `{{counter}} < ${max_retries}`. |
| Local variables | Must be defined **inside** the block if referenced there - otherwise End While errors. |
| `INFINITE_LOOP_DETECTED` | Raised when the condition can't change (e.g. `1 == 1`, or nothing in the body updates it). |

**Canonical patterns:** drain a queue (`while {{active_count}} > 0`), poll a status (`while {{job_status}} != "complete"` with a short wait inside), wait out a spinner (`while the loading spinner is visible`), validate paginated rows (`while the Next button is enabled`), walk table rows with `{{loop_counter}}`.

---

## 7. Assertions & Failure Conditions

Assertions validate that expectations match actual outcomes.

**8 supported assertion types:**

| Type | What it validates | Example |
|---|---|---|
| Driver | Browser state (current URL, window dimensions) | `Assert if current URL is https://example.com` |
| Text | Presence/absence of text | `Assert "Welcome Back!" is visible` |
| Visual | Image/logo visibility | `Assert company logo appears in header` |
| Relative | Element relationships | `Assert login button is in same column as username` |
| Mathematical | Arithmetic | `Assert 3 + 4 = 7` |
| Element State | enabled, disabled, visible, hidden, checked, clickable | `Assert the "Submit" button is enabled` |
| DOM Attribute | HTML / ARIA / data attributes | `Assert the aria-expanded of the "Menu" equals "true"` |
| CSS Property | Computed CSS values | `Assert the font-size of the "Heading" equals "24px"` |

**Not yet available via natural language** (use JS-snippet workarounds where applicable): **spatial** assertions; **action-based** assertions - split into separate steps (hover -> wait -> assert); **nested** assertions - split into separate assertions.

**Dos and don'ts (from the command guide):**

| Do | Don't |
|---|---|
| `Assert search results appear` (after a separate wait step) | `Wait for search results and then assert they are visible` - never mix actions into assertions |
| `Assert the divider looks red` | `Assert divider color is #ff5733` - exact visual details are fragile |
| `Assert textbox contains the exact value 'heading1'` | `Assert the textbox has heading` - vague |
| One clear outcome per assertion | Several checks packed into one assertion |

### Failure conditions (what happens when a step fails)

Every step (not just assertions) has a configurable failure condition, set via the step's three-dot menu in Authoring mode:

| Option | Behavior |
|---|---|
| **Fail test immediately** *(default)* | Halt execution; overall status **Failed**. (equivalent to a hard assertion) |
| **Fail but continue execution** | Run remaining steps; overall status still **Failed** - captures all failures in one run. |
| **Warn but continue execution** | Run remaining steps; overall result **unaffected** - for non-critical validations. (equivalent to a soft assertion) |

- Failure conditions apply **only during Test Runs** - authoring flow and generated code are unaffected.
- **Since July 20, 2025, all assertions fail tests immediately by default** - but tests authored earlier keep warn-and-continue until edited, and org admins can change the default for new tests in **Org Product Preferences**.

---

## 8. Variables, Parameters, Secrets & Smart Variables

Four distinct mechanisms, four distinct syntaxes:

| Mechanism | Syntax | Scope | Use for |
|---|---|---|---|
| **Variable** | `{{variable_name}}` | Local / Global / Environment | Reusable values, extracted data |
| **Parameter** | `${parameter_name}` | Test-level (bound via Data Sets) | Data-driven runs |
| **Secret** | `{{secrets.user.<key>}}` / `{{secrets.org.<key>}}` | User- or org-level vault | Credentials, tokens |
| **Smart Variable** | `{{smart.<name>}}` | Built-in, read-only | Dynamic dates, random data, device info |

Typing `{{` in the step input lists all available variables (regular, secret, and smart).

### Variables

**Types:** **String** (simple text; created via KaneAI or manual entry) and **JSON** (structured data auto-generated from API calls and DB queries - **cannot be created manually**). JSON variables expose the **response status code, body, and headers**; navigate with dot notation: `{{api_variable.response.email}}`.

**Scopes:**

| Scope | Visibility |
|---|---|
| **Local** | Only within its test case. Defined via natural language only (e.g. `Set username as John` -> `{{username}}` = "John"). |
| **Global** | Across all test cases in the organisation. |
| **Environment** | Per-environment values (staging, production...) for URLs/credentials. |

**Creating:** `/` slash command -> **Add a variable** (global/environment), natural language (`Set username as John` - local), the Variables page https://kaneai.lambdatest.com/variables -> **Create new**, or convert hardcoded text in recorded Click/Type steps via the **Convert as** popover (Parameter / Variable / Secret - recording itself can't detect them, conversion happens after).

**Using:**
```
Enter {{username}} in user input field
assert {{username}} contains 'John'
assert {{api_variable.response.email}} is 'john.doe@example.com'
```

- A local variable can be converted to **global or environment** scope during the authoring session. **Persist Value** (available only on local->global conversion) retains the value across executions.
- Editing a variable's value (variables listing icon, top right, or the Variables page) applies to **all new** executions and sessions.
- At run/schedule time you choose **one environment per test run** (all test cases in the run execute on it); a test runs in any environment where its variables exist. For API-triggered runs, set the environment in the request (Section 12).

### Parameters (data-driven testing)

- Create: type **/** and select **Parameter**, or click the **+** icon -> Parameter -> **Create Parameter**.
- Reference with **dollar-curly syntax**: `${phone_number}`.
- Values are bound via **Data Sets** attached when creating a test run: Test Run section -> **Create New Test Run** -> add KaneAI test cases -> attach data sets -> **Apply** -> save. Each data set row generates test instances. Used parameters are shown on the Test Summary page.

### Secrets (HashiCorp Vault-backed)

- Reference in steps: `use the value of {{secrets.user.email}} in the email text field`. Header values in Custom Headers use `{{secrets.org.<name>}}` (Section 4d).
- Create via **Test Manager -> settings icon -> Secrets -> Create new secret**, or in an authoring session: type **/** (or click **+**) -> Secret -> key + value -> **Create Secret**.
- Permissions: users create/delete **user-level** secrets; only admins create/delete **org-level** secrets. Update/delete via Test Manager -> Secrets (pencil / delete icons).
- Secrets are usable in test steps, modules, and test cases. In the **Convert as** popover, existing secrets can't be reused - only **+ Create Secret** (enforced for security).

### Smart Variables (built-in dynamic values)

Predefined, read-only, labeled "Smart" in the `{{` overlay. Syntax `{{smart.<name>}}`, resolved at run time:

```
Enter the value of {{smart.current_date}} in the date field
```

| Category | Variables |
|---|---|
| Date & time | `current_date` (YYYY-MM-DD), `current_day`, `current_month`, `current_month_number`, `current_year`, `current_hour`, `current_minute`, `current_timestamp`, `current_timezone`, `next_day`, `previous_day`, `start_of_week`, `end_of_week`, `start_of_month`, `end_of_month` |
| Randomized | `random_int` (3-digit), `random_float`, `random_string_8`, `random_string_56`, `random_email`, `random_phone` |
| System | `os_type`, `os_version`, `browser_name`, `browser_version`, `user_name` |
| Device (app tests) | `device_name`, `device_model`, `device_os`, `device_os_version`, `device_orientation`, `app_version`, `app_package_name` |

Use `{{smart.random_email}}` / `{{smart.random_phone}}` for signup flows instead of hardcoding.

---

## 9. API Testing inside a Test

Add and validate REST API calls as steps inside a KaneAI web test:

1. **Add an API** through the **slash command** and go to the **API module**.
2. **Paste a curl command** - KaneAI populates all the details. You can then **validate** the response **or add the API directly to the test steps without validating** (useful for intentional error-path calls).
3. On **validate**: a **200** status auto-adds the API to the test steps. Non-success responses (e.g. **400 Bad Request**) are **not** added automatically - review and add manually.
4. **Add multiple APIs** via the **+** icon or by pasting multiple curl commands.
5. HTTP methods: **GET, POST, PUT, DELETE**.
6. **Execute all** added APIs in one go and review response details for performance insights.

Every executed API auto-generates a **JSON variable** (Section 8) containing the response **status code, body, and headers** - so you can assert the status (`Expected status: 200`) and chain response values into UI steps via `{{api_variable.response.<key>}}`.

---

## 10. Running & Scheduling Tests

- Every KaneAI test runs on **real browsers in the cloud on HyperExecute**. Every run is saved to **Test Manager** with a shareable **Test Summary link**.
- Coverage matrix: **3000+ browser/device/OS combinations**.

### Creating a Test Run

In your project's **Test Run** section: create a test run with **Name**, Description, Tags, and **Type: KaneAI Generated Test Cases**; select and add test cases; then **Run with HyperExecute**, set concurrency, optionally open **Advanced Configurations**, and click **Execute**.

> **Eligibility:** only test cases whose **code generation is complete** can be added. Test cases where generation hasn't started or is in progress won't be selectable.

### Scheduling a Test Run

> **Prerequisite: the Test Run must already exist** before you can schedule it.

1. **Test Manager** -> your project -> **Test Runs**.
2. Click the **three dots** next to a test run -> **Create Schedule** (or go to **Scheduled runs** -> **Create a Scheduled Run**).
3. Provide a **Schedule Name**, select the test run, configure date/time.
4. Click **Next** to review; set concurrency in **Build Parameters**; optionally open **Advanced Configurations** (network throttling, URL replacement, visual regression, accessibility, report generation).
5. Click **Schedule Test Run**.

---

## 11. Auto-Heal, Versioning & Modules

### Auto-heal (how it actually works)

- At code-generation time, every element gets **multiple locators** (XPath, CSS, ID, ...).
- At run time on HyperExecute, if the primary locator fails, fallback locators are tried **sequentially**.
- If **all** locators fail, KaneAI **re-evaluates the original natural-language instruction** and rebuilds the locator on the fly from its intent - the step continues without manual intervention. When DOM alone is insufficient, KaneAI uses **visual queries** (appearance + relative position).
- Scope: any command that uses an element locator (Click, Type, Hover, ...).
- Healing **reports** and auto-updating healed locators into a new test version are **roadmap items** - do not rely on them today.

### Versioning

Every saved change to a test creates a new version; compare and roll back from the **Version History** tab. Applying advanced-settings changes also creates a new version with regenerated code (Section 4d).

### Reusable Modules

- **Platform-specific:** a module authored on one platform may misbehave on another - create separate copies per platform and prefix names: `[Web] Login Flow`, `[Android-App] Login Flow`, `[Android-Browser]`, `[iOS-App]`, `[iOS-Browser]`.
- **Create** from an active session: **Pause Test** -> select the steps -> **Create Module** -> Name/Description/Tags.
- **Import** into a test: **+** icon or **/** -> **Add Module** -> **Add in Queue** to execute its steps.
- Modules support variables, parameters, and secrets for dynamic data. Saving changes to a module creates a new module version (tests pick it up on next run - including While loops inside modules).
- Only modules **not linked to any test case** can be deleted.

---

## 12. Triggering Test Runs from CI/CD (HyperExecute API)

Trigger a saved KaneAI test run from **GitHub Actions, Jenkins, or any pipeline**.

### Prerequisites
- Access to **Test Manager**, a project with KaneAI-generated test cases, and TestMu AI credentials (username + access key).

### Step 1 - Get the Test Run ID
In **Test Manager -> your project -> Test Runs**, open the desired test run and copy the **Test Run ID** from its URL.

### Step 2 - Trigger the run (POST)

Authenticate with **Basic Auth** (`base64(username:access_key)`):

```bash
curl --location 'https://test-manager-api.lambdatest.com/api/atm/v1/hyperexecute' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <Base64Auth>' \
  --data '{
    "test_run_id": "YOUR_TEST_RUN_ID",
    "concurrency": 1,
    "title": "UNIQUE_BUILD_NAME",
    "environment_id": 0,
    "retry_on_failure": true,
    "max_retries": 1,
    "region": "eastus",
    "report_enabled": true,
    "report_email_to": ["email1@example.com"]
  }'
```

**Request parameters** (all optional except `test_run_id`):

| Parameter | Default | Notes |
|---|---|---|
| `test_run_id` | - | **Required.** From Step 1. |
| `concurrency` | `1` | Parallel sessions. |
| `title` | random | Build name; auto-generated if omitted. |
| `console_log` | `false` | Web only. `false, error, warn, info, true`. |
| `network_logs` / `network_full_har` | `false` | Capture network calls (full HAR is web only). |
| `region` | - | Web: `eastus`, `centralindia`. |
| `mobile_region` | - | Mobile: `us`, `eu`, `ap`. |
| `tunnel` | - | Tunnel **name** for private apps. Mutually exclusive with the next two. |
| `dedicated_proxy` | - | Proxy **region** (`us`, `eu`). Mutually exclusive. |
| `geolocation` | - | Geolocation **region** (see the supported-geolocations doc). Mutually exclusive. |
| `environment_id` | `null` | Environment for the run (numeric ID). |
| `retry_on_failure` | `true` | Retries fire on **testRunnerCommand failure and individual test-case failure**. |
| `max_retries` | `1` | Maximum 5. |
| `timezone` | - | Web only, e.g. `{"region":"Indianapolis"}`. |
| `android_app_id` / `ios_app_id` | - | `lt://<APP_ID>`. |
| `app_profiling` | `false` | Native-app performance metrics (mobile). |
| `performance` | `false` | Lighthouse report (web). Limited OS/browser combos; may slow execution. |
| `accessibility` | `false` | WCAG 2.1 AA checks. Web with **Chrome and Edge only**; may slow execution. |
| `network_throttle` | - | Mobile only. Object: `{"label", "value", "download_speed", "upload_speed", "latency", "honor_network"}`. |
| `replaced_url` | - | Array of `{pattern_url, replacement_url}` to swap URLs at run time. |
| `report_enabled` / `extent_report_enabled` | `false` | HTML / Extent report - **mutually exclusive, enable only one**. Downloadable from the HyperExecute Job page. |
| `report_email_to` | - | Array of emails (**max 10**). Requires `report_enabled: true`; report arrives as an HTML attachment. |

> **Retry note:** test-case failure retries only work for code exported **from May 10, 2026 onwards** - older exports retry only on testRunnerCommand failure. Fix: regenerate the code export in Test Manager. Keep your credentials secure.

### Step 3 - Response

```json
{
  "job_id": "abcd1234-abcd-1234-abcd-1234abcd1234",
  "app_job_id": "abcd1234-abcd-1234-abcd-1234abcd1234",
  "test_run_id": "01LAMBDATEST2024KANEAIJ8NPGDP",
  "job_link": "https://hyperexecute.lambdatest.com/hyperexecute/task?jobId=<job_id>",
  "mobile_job_link": "https://hyperexecute.lambdatest.com/hyperexecute/task?jobId=<app_job_id>"
}
```

`job_id` = the **desktop web** job; `app_job_id` = the **mobile / real-device** job. Both appear when the run contains both test types - **poll each job you care about** (a mobile-only pipeline must poll `app_job_id`, not `job_id`).

### Step 4 - Poll job status (GET)

```bash
curl --location "https://api.hyperexecute.cloud/v2.0/job/$job_id" \
  --header "accept: application/json" \
  --header "Authorization: Basic <Base64Auth>"
```

Read `.data.status`; treat `"completed"` as success (fail the pipeline otherwise).

### GitHub Actions example

```yaml
name: Run Sanity Tests on LambdaTest
on:
  push: { branches: [main] }
  pull_request: { branches: [main] }
jobs:
  sanity-test:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Sanity Test on LambdaTest
        id: trigger-test
        run: |
          response=$(curl --location 'https://test-manager-api.lambdatest.com/api/atm/v1/hyperexecute' \
            --header 'accept: application/json' \
            --header 'Content-Type: application/json' \
            --header 'Authorization: Basic <Base64Auth>' \
            --data '{ "test_run_id": "<test_run_id>", "concurrency": 1 }')
          job_id=$(echo $response | jq -r '.job_id')
          echo "job_id=$job_id" >> "$GITHUB_OUTPUT"
      - name: Check Test Status
        run: |
          job_id=${{ steps.trigger-test.outputs.job_id }}
          sleep 240
          response=$(curl --location "https://api.hyperexecute.cloud/v2.0/job/$job_id" \
            --header "accept: application/json" \
            --header "Authorization: Basic <Base64Auth>")
          status=$(echo $response | jq -r '.data.status')
          if [[ "$status" != "completed" ]]; then
            echo "Tests failed."; exit 1
          fi
          echo "Sanity tests passed."
```

> The support doc's sample uses the deprecated `::set-output` syntax; the block above uses the current `$GITHUB_OUTPUT` form. For mobile runs, extract `.app_job_id` instead.

---

## 13. GitHub Integration

### 13a. Validate Pull Requests with `@KaneAI`

**Setup (required - the trigger is inert without it):**
1. Install the **TestMu AI Cloud GitHub App**: https://github.com/apps/lambdatest-ai-cloud (needs repo admin access; the account must have KaneAI enabled). After install you're redirected to the integration settings page where all config values (project ID, folder ID, assignee, environment ID) are shown with copy buttons.
2. Create **`.lambdatest/config.yaml`** in the repository root:

```yaml
project_id: "your_project_id"        # Test Manager project
folder_id: "your_folder_id"          # folder for generated test cases
assignee: your_user_id               # user assigned to test runs
configuration_id: configuration_id   # target env (browser, OS, device)
test_url: "https://your-deployed-app-url.com/"
tunnel_name: "your_tunnel_name"      # optional; overridable per PR
```

**Trigger commands** (comment on the PR):

| Command | Effect |
|---|---|
| `@TestMuAI Validate this PR` | Full AI testing workflow: analysis, generation, execution, reporting |
| `@KaneAI Validate this PR` | Alias for the above |

Optional flags (independent, combinable): `--url <test_url>` overrides `test_url` for this PR (ephemeral preview environments); `--tunnel <tunnel_name>` routes traffic through a named tunnel - **required for locally hosted / private apps, and the tunnel must be active when triggered**.

```
@TestMuAI Validate this PR --url https://preview-123.your-app.com --tunnel my-tunnel-name
```

**What happens:** KaneAI gathers context from your **README.md, PR title/description/comments, and AGENT.md**, generates tests, adds semantically similar existing tests from Test Manager (**Smart Intelligence**), executes, and posts results in the PR thread. The first signal (test plan + progress tracker) appears within ~1 minute.

> **Maximize quality:** keep README.md comprehensive (app overview, key workflows, tech stack) and use **agent.md** for custom instructions - testing priorities, scenarios to cover or skip, domain rules. Test-case links (TC-XXXXX) are visible to anyone in your org with Test Manager access; authoring-status links only to the installing user. Sample repo: https://github.com/LambdaTest/ai-native-quality-validation-sample

### 13b. Export test code as a PR (BETA)

KaneAI can export generated test code to **GitHub or GitLab** as a PR/MR. Beta - request access via support@testmuai.com.
- Supported: Desktop Browser / Mobile Browser -> **Selenium (Python)**; Mobile App -> **Appium (Python)** - one `test.py` per test, at `{project_name}/{test_id}_{test_name}/{version_no}`.
- Single-repo or per-project multi-repo strategy; configurable base branch; **Auto-PR** (off by default) opens a PR whenever new code is generated; manual: Test Manager -> test case -> three-dot menu -> **Create PR** (button only appears when the version has no PR yet).
- Admin role required for configuration; Bitbucket support "coming soon".

Also: KaneAI is **native to Jira & Azure DevOps** - build, assign, and update test cases inside them - and **Smart Bug Detection** captures the trace, drafts the ticket, and routes it to the right owner.

---

## 14. Troubleshooting & FAQs

**Where do I see results?** Every run is saved to **Test Manager**; use the shareable **Test Summary link**.

**Blocked by a CAPTCHA / Cloudflare challenge?** KaneAI runs on cloud browsers; bot protection (Cloudflare Turnstile, Google reCAPTCHA, hCaptcha) may block the session - the token is rejected even when the form is filled correctly. **KaneAI cannot solve CAPTCHAs** (no tool reliably can). Stop the challenge from reaching test traffic:
1. **Whitelist TestMu AI's cloud IPs** (recommended) - ranges and steps: https://www.testmuai.com/support/docs/testmu-public-ip/ - scoped to your test domain (Cloudflare IP Access rule / WAF / Turnstile allowlist). A config change, not new infrastructure.
2. **Use a test environment without the live challenge** - disable it on staging/UAT or use Turnstile test keys that always pass.
3. **Allowlist a custom request header** on your test environment (Section 4d Custom Headers). *Test environments only.*

**Private network / localhost app?** IP whitelisting only works for public apps - use the **TestMu AI Tunnel**: https://www.testmuai.com/support/docs/network-whitelisting-and-tunnel-guide/

**Common authoring failures:**

| Symptom | Likely cause | Fix |
|---|---|---|
| Step acts on the wrong element | Ambiguous phrasing | Be specific; name the element type: `click the 'Submit' button in the checkout form` |
| New tab interactions fail | Context not switched | `Switch to 2nd tab` after opening (1-indexed; tab must exist) |
| "repeat..." / "while..." step rejected | `WHILE_NOT_SUPPORTED_VIA_NL` - loops can't be created in natural language | Press **/** -> **Add While Loop** (Section 6b) |
| Loop fails after 30 iterations | `LOOP_MAX_LIMIT_REACHED` - condition never became false | Ensure a body step advances the condition; cap is fixed at 30 |
| Loop rejected at condition | `BOTH_OPERANDS_AS_PARAMETERS` | Make one operand a runtime value: `{{counter}} < ${max_retries}` |
| `long press ... 3 times` / `triple click` rejected | Mutually exclusive click modifiers / unsupported phrase | Use one modifier; `click X 3 times` for multi-click |
| Assertion stops the run unexpectedly | Default failure condition is *Fail test immediately* | Set the step to *Warn but continue* for non-critical checks (Section 7) |
| Steps stopped being recorded mid-session | Manual Interaction paused (Draft state) | Click **Start recording** (Section 4c) |
| Value not reused across test cases | Local variable scope | Convert to **global**/**environment** (Section 8) |
| Flaky step after slow action / scroll | Missing explicit wait | Add `Wait for N seconds` after the triggering step (Section 5) |

---

## 15. Reference

- **Register:** https://www.testmuai.com/register/, **KaneAI homepage:** https://www.testmuai.com/login/?redirectTo=https://kaneai.lambdatest.com/objective
- **Variables page:** https://kaneai.lambdatest.com/variables
- **Trigger API (POST):** `https://test-manager-api.lambdatest.com/api/atm/v1/hyperexecute`
- **Job status API (GET):** `https://api.hyperexecute.cloud/v2.0/job/$job_id`, full HyperExecute APIs: https://www.testmuai.com/support/api-doc/?key=hyperexecute
- **GitHub App:** https://github.com/apps/lambdatest-ai-cloud
- **Docs:** https://www.testmuai.com/support/docs/getting-started-with-kane-ai/ - command guide, while loops, conditional logic, variables, parameters, secrets, failure conditions, manual interaction, modules, auto-heal, CI/CD automation
- **Community:** https://community.testmuai.com/, **Support:** support@testmuai.com