# CoWork

## Overview

CoWork is QApilot's agentic, human-in-the-loop test authoring mode. It takes your existing test cases written in plain English or BDD format, and automates them on a real mobile device. The system reads the screen, decides what actions to take, and adapts on the fly.

CoWork is one among the three test authoring modes on QApilot - each mode designed for a different testing need:

<table><thead><tr><th width="101.08770751953125">Mode</th><th width="167.78472900390625">Type</th><th>Best For</th></tr></thead><tbody><tr><td><strong>Crawler</strong></td><td>Agentic · Autonomous</td><td>Fully autonomous app exploration and test generation with zero human input</td></tr><tr><td><strong>CoWork</strong></td><td>Agentic · Human in the loop</td><td>Converting existing test cases into automated recordings with AI assistance</td></tr><tr><td><strong>Record &#x26; Playback</strong></td><td>RPA · AI-Assisted</td><td>Capturing precise user interactions manually for full test coverage</td></tr></tbody></table>

> **See also:** [Platform Overview](#) for a full introduction to QApilot's modes.

## How to CoWork

### Workflow at a Glance

<table><thead><tr><th width="42.454833984375">#</th><th width="157.6544189453125">Step</th><th>What Happens</th></tr></thead><tbody><tr><td>1</td><td><strong>Ingest</strong></td><td>Upload or create test cases from excel</td></tr><tr><td>2</td><td><strong>Invoke</strong></td><td>Configure and launch CoWork on a selected test case</td></tr><tr><td>3</td><td><strong>Translate</strong></td><td>Review and optionally edit the auto-generated BDD steps</td></tr><tr><td>4</td><td><strong>Execute</strong></td><td>CoWork runs the test on a live device, replanning automatically as needed</td></tr><tr><td>5</td><td><strong>Review &#x26; Accept</strong></td><td>Accept the recorded steps or hand off to the RPA module for manual recording</td></tr><tr><td>6</td><td><strong>Run &#x26; Report</strong></td><td>Execute the test suite and view results - shared across all authoring modes</td></tr></tbody></table>

***

## Prerequisites

Before using CoWork, make sure the following are set up in QApilot:

* **Device farm Integration** - Connect to a supported device farm (LambdaTest) via **Settings**
* **App uploaded** - The mobile app under test must be uploaded to the platform as an App Source

> CoWork currently supports **Android** only. iOS support is coming soon.

***

## 1. Ingest - Build Your Test Cases

Navigate to **CoWork** in the left sidebar. You'll find two sections: **Configuration** and **Test Cases**.

The **Test Cases** page is your CoWork test case bank - a library of all test cases available for CoWork to run upon. Each entry shows the test case name, ID, supported OS, last updated timestamp, scenario, source, and actions.

> **Cross-reference note:** The `Source` column in the Test Cases bank displays `CoWork` for all cases authored here. See [Test Case](/detailed-documentation/test-plan-executions/test-case.md) for the full platform-wide test case view.

### Adding Test Cases

{% tabs %}
{% tab title="Option 1: Upload via Excel" %}

1. Click the **Upload** button (top right of the Test Cases page)
2. In the **CoWork Test Case Upload** modal, attach your Excel file from your local machine
3. Ensure the file includes all required fields:

   <table><thead><tr><th width="172.33502197265625">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>allure_id</code></td><td>Unique identifier for the test case</td></tr><tr><td><code>name</code></td><td>Test case name</td></tr><tr><td><code>feature</code></td><td>Feature or module the test case belongs to</td></tr><tr><td><code>scenario</code></td><td>Scenario name</td></tr><tr><td><code>test steps</code></td><td>The actual steps to execute</td></tr></tbody></table>

> **Tip:** Click **Download Sample Excel File** to get the `CoWork-sample.xlsx` template. Fill in your test case details and upload.
> {% endtab %}

{% tab title="Option 2: Create Manually" %}

1. Click the **+** icon (top right of the Test Cases page)
2. Fill in the **Test Case Create** form:

   <table><thead><tr><th width="148.22998046875">Field</th><th width="107.08935546875" align="center">Required</th><th>Notes</th></tr></thead><tbody><tr><td>Test Case Title</td><td align="center">✅</td><td></td></tr><tr><td>Test ID</td><td align="center"></td><td>Reference a case in your test management tool</td></tr><tr><td>Severity</td><td align="center">✅</td><td>e.g., Critical, Major, Minor</td></tr><tr><td>OS</td><td align="center">✅</td><td>Android, iOS, or Both</td></tr><tr><td>Scenario</td><td align="center"></td><td>Associate with an existing scenario</td></tr><tr><td>Precondition</td><td align="center"></td><td>Credentials, etc.</td></tr><tr><td>Expected Result</td><td align="center"></td><td>What the test should confirm</td></tr><tr><td>User Steps</td><td align="center">✅</td><td>Step-by-step actions in plain English</td></tr></tbody></table>
3. Click **Create**

Newly created test cases appear at the top of the bank with a **Draft** status.

> **Coming soon:** Import test cases directly from test management tools such as TestRail.
> {% endtab %}
> {% endtabs %}

> Open CoWork section from the left panel -

<figure><img src="/files/HIMnGHp3BidMFePrqMx9" alt=""><figcaption></figcaption></figure>

> Upload Test Case Sheet to add Cases and Steps into the platform

<figure><img src="/files/bYsf6jQGoZW0TstycNKL" alt=""><figcaption></figcaption></figure>

> Or write cases manually through Test Case Create

<figure><img src="/files/5yUUG23bUmC26OVTSpRV" alt=""><figcaption></figcaption></figure>

### Managing Test Cases

Click the three-dot-menu on any test case row to access the following options:

<figure><img src="/files/5e5Z1NFa2diORwkETyRA" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="169.46014404296875">Action</th><th>Description</th></tr></thead><tbody><tr><td><strong>Edit</strong></td><td>Modify the test case details</td></tr><tr><td><strong>Manage Steps</strong></td><td>View or edit recorded steps associated with the test case</td></tr><tr><td><strong>CoWork</strong></td><td>Launch CoWork directly on this test case</td></tr><tr><td><strong>Delete</strong></td><td>Permanently remove the test case</td></tr></tbody></table>

***

## 2. Invoke - Launching CoWork

CoWork can be launched from two places in the platform.

{% tabs %}
{% tab title="Option 1: From the Configuration Page" %}

1. Select **Configuration** from the CoWork left panel
2. Complete **Step 1 - Select Platform & App Source:**
   * Select **App Platform** (Android)
   * Choose your **Service** (e.g., LambdaTest)
   * Select your **App Source**
3. Complete **Step 2 - Configure Scenario & Test Case:**
   * Select a **Scenario**
   * Select the **Test Case** you want to automate
4. Click **Launch**
   {% endtab %}

{% tab title="Option 2: From the Test Cases Page" %}

1. Click the **⊙** actions menu next to any test case
2. Select **CoWork**
3. A **CoWork Configuration** modal appears with the same two-step form — the Scenario and Test Case fields are pre-filled based on your selection
4. Fill in Step 1 (platform, service, app source) and click **Launch**
   {% endtab %}
   {% endtabs %}

> Configuration Screen -

<figure><img src="/files/34zzs4ZAG9swaeZ3gmSQ" alt=""><figcaption></figcaption></figure>

> Test Cases Screen -

<figure><img src="/files/5kS1aOCvcjC0itGrGZ9n" alt=""><figcaption></figcaption></figure>

> Launch CoWork post Configuration -

<figure><img src="/files/SaLjvhQwLJRfg50AJgU6" alt=""><figcaption></figcaption></figure>

### Device Connection

After clicking Launch, CoWork allocates a device from your device farm and establishes a live connection. A progress modal displays:

* Device name (e.g., Galaxy S24)
* App name and package identifier
* Connection progress and elapsed time

Once connected, the CoWork workspace opens with the device live on the left panel.

***

## 3. Translate - Reviewing BDD Steps

The CoWork workspace is split into three panels.

<figure><img src="/files/ZVyQuqteugsJap77f7gH" alt=""><figcaption></figcaption></figure>

### **Left Panel: Live Device**

A real-time mirror of the mobile device. The app is already launched and ready. You can watch actions execute here as CoWork runs.

### Center Panel: Planner Workspace

**Source Requirements** *(expandable, read-only)*

Expand this section to view the original test case data pulled from the bank:

* Preconditions
* User Steps
* Expected Result

This is read-only. It reflects your source test case exactly as entered.

**Planner Input (BDD Steps)**

CoWork automatically translates your plain English test steps into BDD format. These steps are editable — you can refine them before starting a run.

Typical BDD steps looks like this:

```gherkin
  Scenario: Account Confirmation Letter details
    Given the app is launched
    And user enters email qa.user.example.test
    And user enters passcode: 15900
    And user clicks on Login: 15900
    And the user clicks on Account details
    And select any account
    Then the user clicks on Account confirmation letter button
```

Click **Save BDD Steps** to save any edits.

> The BDD steps generated during a CoWork run are saved back to the test case automatically for future reference.

**Additional App Context**

Use this free-text field to pass extra information to the planner - for example, login credentials, screen-specific values, or navigation hints that aren't captured in the test steps.

**Action Buttons**

<table><thead><tr><th width="209.6119384765625">Button</th><th>Action</th></tr></thead><tbody><tr><td><strong>Automate with CoWork</strong></td><td>Starts the CoWork and begins automated execution on the live device</td></tr><tr><td><strong>Record Manually</strong></td><td>Skips CoWork and opens the Record &#x26; Playback (RPA) module on the platform for manual recording</td></tr></tbody></table>

### Right Panel: Planner Output

{% tabs %}
{% tab title="Plan Tab" %}
Displays the planner's current execution plan as a numbered, live-updating step list. Each step includes:

* A plain-language description of the action
* The action type: `click`, `wait`, `scroll`, or `reactivate`
* The target selector (element identifier used to locate the UI element)
* Real-time status indicator: ○ pending · ✓ succeeded · ✗ failed

The badge on the tab reflects the total number of steps in the current plan version. If a replan occurs, this count updates.
{% endtab %}

{% tab title="Plan History Tab" %}
Logs every version of the plan generated during the session. Expand any version to see:

* Version label and status (`in_progress`, `replaced`, or `completed`)
* The planner's reasoning — a natural language explanation of the approach taken
* Full scenario context (BDD steps, app package, app context)
* Step-by-step execution summary with success/failure indicators per step
  {% endtab %}

{% tab title="Replans Tab" %}
When a step fails, CoWork does not stop - it automatically generates a new plan from the point of failure. The Replans tab records each replan event in detail:

<table><thead><tr><th width="140.20660400390625">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>Triggered at</strong></td><td>The step and plan version where the failure occurred</td></tr><tr><td><strong>Error</strong></td><td>The exact error returned by the failed action</td></tr><tr><td><strong>Failed step</strong></td><td>Action type, description, and selector that was attempted</td></tr><tr><td><strong>Reasoning</strong></td><td>The planner's analysis of what went wrong and how it will recover</td></tr><tr><td><strong>New plan</strong></td><td>The version number and file generated to replace the failed plan</td></tr></tbody></table>

**Example of adaptive replanning in action:**

The planner expected a "Not now" dismiss button on an update prompt. Instead, the device showed a Change Language screen. CoWork detected the mismatch, reasoned that the language screen needed to be cleared by tapping "Proceed", generated a new 2-step plan (v2) spliced in from step 3, and continued execution — all without manual intervention.
{% endtab %}
{% endtabs %}

***

## 5. Review & Accept

Once execution completes, the plan steps are displayed with their final status. Review the run and choose how to proceed:

{% tabs %}
{% tab title="Accept Steps" %}
Click **Accept Steps** to save all generated steps to the test case on the platform.

> *The test case is saved with the recorded steps and is ready for execution.*

Use this when you're satisfied with how CoWork executed the test and want to move forward without changes.
{% endtab %}

{% tab title="Record Manually" %}
Click **Record Manually** to save the generated steps as a **Draft** and open them in the **Record & Playback** module.

> *From the Recorder screen, you can review, validate, edit, and approve each step before finalizing.*

Use this when you want to inspect the steps closely, correct specific interactions, or fill in gaps before accepting the recording.

> **Cross-reference note:** See [Creating Test Steps Using Test Recorder](/detailed-documentation/test-recording/create-test-steps-using-test-recorder.md) for full documentation on the RPA module and how to work with draft steps in the Recorder screen.
> {% endtab %}

{% tab title="Edit & Rerun" %}
To adjust the BDD steps based on what was observed during execution, click **Edit & Rerun**.

This returns you to the Planner Workspace where you can edit the BDD input and re-execute the test from the beginning with the updated steps.
{% endtab %}
{% endtabs %}

<figure><img src="/files/Hc7If95jSHdrK03Yc4v9" alt=""><figcaption></figcaption></figure>

***

## 6. Run & Report

Once a test case has been recorded and accepted via CoWork, it joins your test suite and can be executed like any other test case on QApilot.

Test execution and reporting work the same way across all authoring modes - CoWork, Crawler, and Record & Playback.

> **Cross-reference note:** See [Test Plan Executions](/detailed-documentation/test-plan-executions.md) and [Reports Dashboard](/detailed-documentation/reports/reports-dashboard.md) for full details on scheduling runs, selecting devices, and interpreting test results.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.qapilot.io/detailed-documentation/cowork.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.