> This is part 1 of 2 of the full documentation (pages 1–100 of 119).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.mozark.ai/llms-full.txt/1
> Page index: https://docs.mozark.ai/llms.txt

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mozark.ai/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

---

# Documentation

<button type="button" class="button primary" data-action="ask" data-icon="robot">Hi! What do you want to know today?</button>

<button type="button" class="button secondary small" data-action="ask" data-query="How do I get started?" data-icon="rocket-launch">Get started</button> <button type="button" class="button secondary small" data-action="ask" data-query="Tell me more about Appium Testing" data-icon="mobile-screen">Appium Testing</button> <button type="button" class="button secondary small" data-action="ask" data-query="Create your first requirement?" data-icon="square-check">Create your first requirement</button> <button type="button" class="button secondary small" data-action="ask" data-query="What are Mozark agents?" data-icon="robot">Read about our agents</button>

***

### Products

<table data-view="cards"><thead><tr><th>Product</th><th data-hidden data-card-target data-type="content-ref">Target</th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><h4><i class="fa-sliders" style="color:$primary;">:sliders:</i> Test Context Manager</h4><p>Manage device state, environment variables, and session context across runs for reproducible, persistent test conditions.<br><br><a href="https://mozarkdocs.gitbook.io/appx_documentation/test-context-manager-documentation" class="button secondary" data-icon="book-open">Learn More</a> <a href="https://testcontext.mozark.ai/" class="button secondary" data-icon="rocket-launch">Quickstart</a> <button type="button" class="button secondary" data-action="ask" data-query="How do I create a test case in Test Context Manager?" data-icon="square-check">Create test case</button></p></td><td><a href="https://mozarkdocs.gitbook.io/appx_documentation/test-context-manager-documentation">https://mozarkdocs.gitbook.io/appx_documentation/test-context-manager-documentation</a></td><td><a href="https://3543984478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn2jTEky8DEwpJgVAnoFt%2Fuploads%2FTakKAhIaJ0mg1meZko8n%2FScreenshot%202026-07-14%20at%2012.44.36%E2%80%AFPM.png?alt=media&amp;token=23dfddf4-9686-4b1d-a320-156b6afb4011">Screenshot 2026-07-14 at 12.44.36 PM.png</a></td></tr><tr><td><h4><i class="fa-server" style="color:$primary;">:server:</i> Test Infrastructure</h4><p>Provision dedicated device labs, configure MDM policies, network isolation, and DRM environments for enterprise testing.<br><br><a href="https://mozarkdocs.gitbook.io/appx_documentation/test-infrastructure-documentation" class="button secondary" data-icon="book-open">Learn More</a> <a href="https://testinfra.mozark.ai/" class="button secondary" data-icon="rocket-launch">Quickstart</a> <button type="button" class="button secondary" data-action="ask" data-query="How do I start a device session in Test Infrastructure?" data-icon="mobile-screen">Launch a Device</button></p></td><td><a href="https://mozarkdocs.gitbook.io/appx_documentation/test-infrastructure-documentation">https://mozarkdocs.gitbook.io/appx_documentation/test-infrastructure-documentation</a></td><td><a href="https://3543984478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn2jTEky8DEwpJgVAnoFt%2Fuploads%2FAIYTL3ycCR4FcGT6m6dK%2FScreenshot%202026-07-14%20at%2012.45.09%E2%80%AFPM.png?alt=media&amp;token=d42d236e-9629-43dd-8de7-625064fd5cf4">Screenshot 2026-07-14 at 12.45.09 PM.png</a></td></tr><tr><td><h4><i class="fa-robot" style="color:$primary;">:robot:</i> AI Workspace</h4><p>AI-powered agents that autonomously explore, validate and report on your apps across real device workflows.<br><br><a href="https://mozarkdocs.gitbook.io/appx_documentation/agent-workspace-documentation" class="button secondary" data-icon="book-open">Learn More</a> <a href="https://testcontext.mozark.ai/" class="button secondary" data-icon="rocket-launch">Quickstart</a> <button type="button" class="button secondary" data-action="ask" data-query="How do I start a session with Mozark agents?" data-icon="mobile-screen">Start session</button></p></td><td><a href="https://mozarkdocs.gitbook.io/appx_documentation/agent-workspace-documentation">https://mozarkdocs.gitbook.io/appx_documentation/agent-workspace-documentation</a></td><td><a href="https://3543984478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn2jTEky8DEwpJgVAnoFt%2Fuploads%2FDTY139VTG4WKSVqFxUin%2FScreenshot%202026-07-14%20at%2012.48.48%E2%80%AFPM.png?alt=media&amp;token=41abd8fd-cb13-470b-a042-7456b8dffd80">Screenshot 2026-07-14 at 12.48.48 PM.png</a></td></tr><tr><td><h4><i class="fa-user-gear" style="color:$primary;">:user-gear:</i> Admin Console</h4><p>Manage organization settings, users, and access from a centralized control plane.<br><br><a href="https://mozarkdocs.gitbook.io/appx_documentation/administration-control-plane" class="button secondary" data-icon="book-open">Learn More</a> <a href="https://id.mozark.ai/" class="button secondary" data-icon="rocket-launch">Quickstart</a> <button type="button" class="button secondary" data-action="ask" data-query="How do I invite users in the Admin Console?" data-icon="user-plus">Invite users</button></p></td><td><a href="https://mozarkdocs.gitbook.io/appx_documentation/administration-control-plane">https://mozarkdocs.gitbook.io/appx_documentation/administration-control-plane</a></td><td><a href="https://3543984478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn2jTEky8DEwpJgVAnoFt%2Fuploads%2FnwIdrh8ngZRuKuXTBOfh%2FScreenshot%202026-07-14%20at%2012.50.23%E2%80%AFPM.png?alt=media&amp;token=e3b80dc3-61c7-4706-a65e-6e560494f33f">Screenshot 2026-07-14 at 12.50.23 PM.png</a></td></tr><tr><td><h4><i class="fa-plug" style="color:$primary;">:plug:</i> MCP</h4><p>Connect an MCP-compatible AI assistant to Mozark. Manage tests, generate coverage, and automate devices with plain-language prompts.<br><br><a href="https://docs.mozark.ai/mcp" class="button secondary" data-icon="book-open">Learn More</a> <button type="button" class="button secondary" data-action="ask" data-query="How do I connect to Mozark&#x27;s MCP?" data-icon="plug">Connect MCP</button></p></td><td><a href="https://docs.mozark.ai/mcp">https://docs.mozark.ai/mcp</a></td><td></td></tr><tr><td><h4><i class="fa-table-cells-large" style="color:$primary;">:table-cells-large:</i> No Code Studio</h4><p>Build and schedule test flows visually. Connect actions, assertions, and devices on a drag-and-drop canvas.<br><br><a href="https://docs.mozark.ai/no-code-studio" class="button secondary" data-icon="clock">Learn More</a></p></td><td><a href="https://docs.mozark.ai/no-code-studio">https://docs.mozark.ai/no-code-studio</a></td><td><a href="https://3543984478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn2jTEky8DEwpJgVAnoFt%2Fuploads%2Fg0XijHjencXplV56XCYI%2FScreenshot%202026-07-14%20at%203.32.57%E2%80%AFPM.png?alt=media&amp;token=a8149ac1-8e7a-4606-bc74-0360f814be5f">Screenshot 2026-07-14 at 3.32.57 PM.png</a></td></tr></tbody></table>

{% hint style="info" %}
Use search or the shortcuts above to jump into your first session, your first test case, or agents.
{% endhint %}


# Overview

App Studio is Mozark's no-code test automation for mobile apps. You record a test by using a real device in your browser, reuse steps as modules, vary the data per device, and run the result across a fleet of Android and iOS devices. No code to write and nothing to install.

## Where to start

| If you want to...                                         | Read                                                                                                                      |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| See the whole flow in one page                            | [User journey](/no-code-studio/getting-started/user-journey)                                                              |
| Record and run your first test (about 15 minutes)         | [Author your first test](/no-code-studio/getting-started/author-your-first-test)                                          |
| Learn the vocabulary: elements, steps, modules, data sets | [Core concepts](/no-code-studio/concepts/core-concepts)                                                                   |
| Reuse a login flow across tests                           | [Modules](/no-code-studio/authoring-tests/modules)                                                                        |
| Run the same test with different data on each device      | [Test data](/no-code-studio/authoring-tests/test-data)                                                                    |
| Bring an existing Optics Framework suite                  | [Importing an existing script](/no-code-studio/authoring-tests/importing-an-existing-script)                              |
| Understand a failed run                                   | [Reports](/no-code-studio/running-and-reporting/reports) and [Troubleshooting](/no-code-studio/reference/troubleshooting) |

## How these docs are organised

1. **Getting started**: the end-to-end journey and a hands-on first test.
2. **Core concepts**: the building blocks every other page refers to.
3. **Authoring tests**: recording, modules, conditions, test data and importing.
4. **Running and reporting**: launching runs, scheduling, and reading results.
5. **Advanced**: API calls, live run view, per-test-case data and error definitions.
6. **Reference**: keyword catalogue and troubleshooting.


# User journey

Record a test on a real device, run it across a fleet, read the result.

```
CREATE                                       EXECUTE
──────────────────────────────────────────   ─────────────────────────
Upload app → Start session → Record → Run  → Report
                                  │
                        ┌─────────┴─────────┐
                     Modules            Data sets
                  (reuse steps)      (vary the values)
```

## Create your test

1. **Upload your app.** Go to **Test Creation**. In the **Uploaded Apps** panel, click **Upload** and choose your `.apk` or `.ipa` (up to 250 MB). Wait for the row to show *ready*, then click it to select it.
2. **Start a session.** Pick any free device from the list and click **Start Testing**. A live screenshot of the real device opens in the **Workspace**.
3. **Record a step.** Tap and type on the device screenshot to reach the screen you want, then right-click any element and pick a command. The step appears on the right with its locator already filled in.
4. **Verify.** Click **Run all** to replay your steps on the device. Use **Run from here** to skip a long login while you iterate on the last step.
5. **Stop the session and name the test case.** **Stop** saves your steps and releases the device, then opens the recording on the **Test Cases** screen. Type a name and click **Save**.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FDenCttct1xNqBKItQWqN%2F01-test-creation.png?alt=media&amp;token=90df6f82-02e8-475b-b587-90ada722c54b" alt=""><figcaption></figcaption></figure>

## The three commands that cover most tests

| Command             | What it does                                                                       |
| ------------------- | ---------------------------------------------------------------------------------- |
| **Press Element**   | Taps the element                                                                   |
| **Enter Text**      | Taps the element, then types into it                                               |
| **Assert Presence** | Checks that something is on the screen. This is what turns a recording into a test |

## Reuse steps with modules

Select a group of steps and click **Create module**. It becomes a single block you can drop into any other test.

Modules are versioned. Each test stays pinned to the version it was built against, so improving a module never changes a passing test until you choose to update it. See [Modules](https://docs.mozark.ai/no-code-studio/authoring-tests/modules).

## Vary the values with data sets

A data set is a table with a key column, almost always `device_serial`. To use one, click into a step's field, click the data set button, and pick the column. The field becomes `${movie_name}`.

Run that one test on two devices and each types its own movie name.

{% hint style="info" %}
One test, many devices, not many loops. Each device reads its own row, in parallel. It does not run twice on one device.
{% endhint %}

See [Test data](https://docs.mozark.ai/no-code-studio/authoring-tests/test-data).

## Run your test

Open **Test Suites → New test suite**, tick the tests and devices, **choose the Application explicitly**, and click **Run now**. Details in [Running tests](https://docs.mozark.ai/no-code-studio/running-and-reporting/running-tests); results in [Reports](https://docs.mozark.ai/no-code-studio/running-and-reporting/reports).

## Next

* [Author your first test](https://docs.mozark.ai/no-code-studio/getting-started/author-your-first-test): the same flow, step by step.
* [Core concepts](https://docs.mozark.ai/no-code-studio/concepts/core-concepts)


# Author your first test

App Studio records a test by watching you use a real device. You tap the phone on your screen, App Studio writes the step. There is no code to write and nothing to install.

By the end of this page you will have a test case that runs on a real device and a report you can share.

* **Time:** about 15 minutes.
* **You will need:** a build of your app, an `.apk` for Android or an `.ipa` for iOS, under 250 MB.
* **Before you start:** pick your **Organization**, **App** and **Project** from the selectors in the top bar. Everything you create belongs to the selected project, so getting this right first saves you moving things later.

## Step 1: Upload your app

1. Go to **Test Creation** in the sidebar. The panel on the right is **Uploaded Apps**.
2. Click **Upload** and choose your build.
3. Wait for the row to show *ready*.

The file has to match the platform tab you are on: `.apk` while **Android** is selected, `.ipa` while **iOS** is selected. App Studio checks this before the upload starts and tells you if it is wrong, so you do not wait for a 200 MB transfer to find out.

| Platform | What happens after upload                                                                             |
| -------- | ----------------------------------------------------------------------------------------------------- |
| Android  | The row is ready straight away                                                                        |
| iOS      | The row sits at *processing* while the build is re-signed for the device fleet, then flips to *ready* |

iOS re-signing usually takes a minute or two. You can keep working; the panel polls and updates itself. If a build is still processing after several minutes, the panel says so. Re-upload it rather than waiting.

Once it is ready, click the row to **select** it. The selected app is the one that gets installed when your session starts.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FVTi0ZAOkJbfLF0DbkTHo%2F01-test-creation.png?alt=media&amp;token=a29e457b-58c2-484c-b889-5554dc53f13b" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**Why the app matters later.** The app you pick here also tells App Studio how to launch your app when the test runs unattended. A test recorded without an app selected has nothing to open, and the run will fail on its first step.
{% endhint %}

## Step 2: Start a device session

Still on **Test Creation**, the main area lists every device in the fleet that is currently free.

1. Use the **Android / iOS** tabs, the brand list on the left, or the search box to narrow it down.
2. Click the device you want.
3. Click **Start Testing**.

The device list refreshes every few seconds, so a device that someone else grabs disappears on its own.

If the app you selected is an `.ipa` and the device is Android (or the reverse), App Studio stops and explains. You can either clear the app and start anyway, or go back and pick a matching build.

### Optional: session capabilities

Before starting you can open Advanced settings (the sliders icon beside Select a device, available once a device is selected) to change what gets captured during the session. The defaults are sensible; the ones worth knowing are:

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FlNwUpPN6buWyoH65TJJL%2F02-capabilities.png?alt=media&amp;token=2c337013-0140-4b26-a55f-9a00da9387ad" alt=""><figcaption></figcaption></figure>

| Capability           | What it does                                                                     |
| -------------------- | -------------------------------------------------------------------------------- |
| Record Session Video | Records the whole session and attaches the video to the report                   |
| Step Screenshots     | Captures a screenshot after every step, which is what builds the report timeline |
| Capture Device Logs  | Collects logcat / syslog for the session                                         |
| Live Device Video    | Streams the device screen into the workspace while you author                    |

## Step 3: Find your way around the workspace

Starting a session opens the **Workspace**. Two halves:

* **Left: the device screenshot.** A live screenshot of the real device. It is interactive: you can tap and type on it directly, exactly as if you were holding it.
* **Right: the authoring panel.** The **Step Builder** (your recorded steps) and an **overflow (⋯) menu that opens** **Elements** (a searchable list of everything on the current screen) and **Page Source** (the raw UI tree).

Drive the app to the screen you want to test: navigate through the login, dismiss the onboarding, whatever it takes. You record steps explicitly, so none of that navigation ends up in your test.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FTLDnu8D5VSD87lr4J19Z%2F14-workspace.png?alt=media&amp;token=92614d9c-e668-408d-a2b3-ddea16bed407" alt=""><figcaption></figcaption></figure>

## Step 4: Record your first step

This is the core interaction of App Studio: **right-click any element on the device screenshot.**

A menu opens. The strip along the top shows which element you are pointing at (its visible text, or its XPath when it has no text) so you can confirm you grabbed the right thing before choosing an action.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FuQ8VtqnOo1h6k65h7cld%2F15-context-menu.png?alt=media&amp;token=64a843e3-cf62-4834-bd92-7cca335dda9d" alt=""><figcaption></figcaption></figure>

The menu has two levels:

* **Popular**: the three commands that cover most of what a test does: **Press Element**, **Enter Text**, **Assert Presence**.
* **All Commands**: hover or click it and a second panel slides out with the full Optics keyword catalogue, a search box, and everything grouped into categories.

| Category            | Examples                                           |
| ------------------- | -------------------------------------------------- |
| Element Actions     | press, enter text, swipe, scroll, get text         |
| App Actions         | launch another app, terminate, background          |
| Validation          | validate element, assert presence, validate screen |
| Device Actions      | rotate, lock, unlock, set orientation              |
| Source & Inspection | capture screenshot, capture page source            |
| Waits               | sleep                                              |

At the bottom of that panel is a **Tools** section for things that are not test steps:

* **Extract value into variable**: read the text off this element at run time and keep it in a `${variable}` for a later step. This is how you carry an OTP, an order number or a balance from one screen to the next.
* **Copy XPath**: copies the element's locator to your clipboard.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FITmAx6W3rzey7lKg9g9r%2F16-all-commands.png?alt=media&amp;token=bf5705f4-8950-4720-a9a7-cde69eb8474f" alt=""><figcaption></figcaption></figure>

Pick a command and the step appears in the Step Builder with the element's locator already filled in.

### Locators and fallbacks

You never type a locator. When you right-click an element, App Studio captures its primary XPath **plus** a set of fallback candidates. At run time the engine tries each in turn, then falls back to matching by visible text and finally OCR. That is why a recorded test survives small UI changes that would break a hand-written XPath.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2F67XmZstH0ju6KKbUJzQP%2F17-recorded-step.png?alt=media&amp;token=f67c14f3-dc3c-49e6-882f-f6c0552b89e5" alt=""><figcaption></figcaption></figure>

## Step 5: The three commands you will use most

### Press Element

Taps the element. The everyday action: buttons, tabs, list rows, links.

{% hint style="info" %}
**Press Element runs immediately when you record it.** The tap happens on the real device there and then, so the device screenshot stays in step with your test. Every other command is recorded without being executed; play it yourself when you are ready (Step 6).
{% endhint %}

| Field                              | Default           | What it means                                                                                                                                  |
| ---------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Element                            | filled in for you | What to tap                                                                                                                                    |
| Repeat                             | 1                 | How many times to tap it                                                                                                                       |
| Match index                        | 0                 | Which match to act on when the locator finds several. 0 is the first                                                                           |
| Offset X / Y                       | 0                 | Pixels added to the matched point before tapping. Only applies when the element is matched by image or OCR; ignored for an XPath or text match |
| Search area X / Y / width / height | 0 / 0 / 100 / 100 | Limits where the element is looked for, as a percentage of the screen. Leave at the defaults to search all of it                               |

**Match index** is the fix for "there are four *Add to cart* buttons on this screen". Record the step, then set the index to the one you want.

### Enter Text

Taps the element, then types into it. The **Text** field is where data-driven testing enters the picture. It takes a plain literal, a `${variable}` reference, or a mix of both:

```
Interstellar
${movie_name}
Hello ${first_name}, your order ${order_id} is ready
```

Use the `{x}` button at the top of the step list to insert a variable at your cursor, or the data-set button to pull a column straight out of a table. [Test data](https://docs.mozark.ai/no-code-studio/authoring-tests/test-data) covers that properly. For your first test, just type a literal.

Two neighbours worth knowing about, both under **All Commands**:

* **Enter Text Direct**: types into whatever already has focus. No element, no tap. Useful when the keyboard is already up and the field is hard to target.
* **Enter Text Using Keyboard**: types key by key through the device keyboard, for fields that ignore programmatic input.

### Assert Presence

Checks that something is on the screen. This is what turns a recording into a **test**: without an assertion, a test only proves that nothing crashed.

Because it accepts a list, one step can cover several outcomes:

```
Elements: Payment Successful|Transaction Complete
Rule:     any
```

That passes if the app shows either wording, which is useful when the copy differs by build or locale.

{% hint style="warning" %}
**Presence is not visibility.** Assert Presence passes for an element that exists in the UI tree even if it is scrolled off-screen. When you specifically need "the user can see this right now", use **Assert Visibility**, which has the same fields and checks that it is actually rendered.
{% endhint %}

## Step 6: Play your steps back

The Step Builder header has **Run all**. It replays your steps on the live device from the top, one at a time, and each row picks up a pass or fail state as it goes.

* **Stop** halts a run in progress.
* The overflow menu on any step gives you **Run from here**, so you do not have to replay a long login every time you iterate on the last step.
* **Remove step** deletes a row. Steps can also be dragged to reorder.

Play everything back at least once before you move on. A step that works while you are authoring is a step that works when it runs unattended.

## Step 7: Stop the session and name your test case

When you are done recording, click **Stop** in the workspace header. That saves your steps, returns the device to the pool for the next person, and opens the recording on the **Test Cases** screen.

Until you name it, the recording carries a placeholder such as `Unsaved recording · Pixel 7 · 26 Aug, 15:42`. Type a real name in the panel and click **Save**. While you are there you can review the whole flow, reorder it, or delete steps.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2Fj0H8RqsANW3wt59fFvjL%2F20-after-stop.png?alt=media&amp;token=2b1290b2-d41d-4d73-9d92-ad1064dfe3ed" alt=""><figcaption></figcaption></figure>

You will not see a "launch app" step, and that is correct. Your session was already open while you recorded, so there was nothing to launch. When the test runs unattended, App Studio generates the launch step for you from the application you select on the run screen.

## Step 8: Run it

Open **Test Suites** in the sidebar and click New test suite.

| Field       | What to do                                                  |
| ----------- | ----------------------------------------------------------- |
| Suite name  | Optional label for the run, e.g. *Checkout smoke - nightly* |
| Tests       | Tick the test case you just recorded                        |
| Devices     | Tick one or more devices. The same test runs on each        |
| Application | Pick the build to install. Do this: see the note below      |
| Test data   | Leave on *No data set* for now                              |
| Schedule    | Leave off to run immediately                                |

Click **Run now**. (With a schedule set, the button becomes **Schedule run**.)

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FDAsrkF5gTkb3NEOtXgX3%2F09-new-test-suite.png?alt=media&amp;token=4f51fd39-c8db-44e9-8bdf-6157edb86de4" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
**Always choose an Application.** The default reads *Auto - the app each test was recorded against*, which works only if your test case already remembers a build. If it does not, the run installs nothing, launches nothing, and comes back **DID NOT RUN** several minutes later with no obvious cause. Picking the build explicitly takes a second and removes the whole failure mode.
{% endhint %}

Selecting devices on two different platforms, or tests recorded against two different apps, splits the submission into more than one job: one per platform and app. That is expected, and each job gets its own report.

### If the run is rejected

You may get *"Some ${references} could not be resolved."* App Studio checks every variable, data-set column and module reference in your test **before** spending time on a run. The unresolved names are listed under the form. Fix them and submit again. Usually it is a variable that was renamed or a data-set column that no longer exists.

## Step 9: Read the report

A successful submission takes you straight to the report. You can also get there from **Test Reports**.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2Fi4uOZd4YixDV8MsNPp0q%2F11-job-report.png?alt=media&amp;token=52a44ba6-4b30-4853-a270-07e8923f491c" alt=""><figcaption></figcaption></figure>

* The **job summary** shows pass/fail across the run.
* The **Test cases table** lists every test case on every device with its status and duration, so a failure on one handset out of six is immediately visible.
* Click into a device's session for the drill-down: every step with its timing and status, the screenshots captured along the way, the session video, and the device logs.

A failing step shows you the screenshot taken at the moment it failed, which is usually enough to tell "the button moved" apart from "the app crashed". See [Reports](https://docs.mozark.ai/no-code-studio/running-and-reporting/reports).

## What you have built

* A test case recorded on a real device, with locators and fallbacks captured for you.
* A run across one or more devices, and a report you can share.

## Next

* [Modules](https://docs.mozark.ai/no-code-studio/authoring-tests/modules): stop recording your login flow over and over.
* [Test data](https://docs.mozark.ai/no-code-studio/authoring-tests/test-data): one test, different data per device.
* [Conditions](https://docs.mozark.ai/no-code-studio/authoring-tests/conditions): branching for flows that vary.


# Core concepts

Everything in App Studio is built out of a handful of things. Learn these once and the rest of the product explains itself.

## The building blocks

### Element

Something on the screen: a button, a text field, a label.

You never type an element locator by hand. When you right-click an element on the device screenshot, App Studio captures its **primary XPath plus a set of fallback locators** (resource id, accessibility name, visible text). At run time the engine tries each in turn, then falls back to matching by visible text and finally OCR.

That cascade is why a recorded test survives small UI changes that would break a hand-written XPath.

### Step

One action on one element: *Press Element*, *Enter Text*, *Assert Presence*.

A step is made of a **keyword** (what to do) and its **parameters** (what to do it to, and how). Some parameters take a literal, and some take a `${variable}`.

### Keyword

The action vocabulary: about 50 of them, grouped into Element Actions, App Actions, Validation, Device Actions, Source & Inspection, and Waits. See the [Keyword reference](https://docs.mozark.ai/no-code-studio/reference/keyword-reference).

### Module

A named, reusable group of steps: *Login*, *Add to cart*, *Complete payment*.

Modules are **versioned and immutable**. Editing a module creates version 1.1 rather than changing 1.0. Every test that uses a module **pins** the exact version it was built against, so improving a module never silently changes a test that was passing. See [Modules](https://docs.mozark.ai/no-code-studio/authoring-tests/modules).

### Test case

An ordered list of steps and module blocks. This is the thing you run.

### Data set

A table of values with a **key column**. One row per device, per test, or per whatever you key it on. See [Test data](https://docs.mozark.ai/no-code-studio/authoring-tests/test-data).

### Variable

A named value written as `${name}`. Four kinds:

| Source  | Where the value comes from                      | Who creates it                                                             |
| ------- | ----------------------------------------------- | -------------------------------------------------------------------------- |
| Static  | A literal you typed once                        | You, on the Variables screen                                               |
| Lookup  | A cell in a data set, matched on the key column | Created for you when you bind a data-set column to a step                  |
| Runtime | Read off the screen by an earlier step          | Created for you by *Extract value into variable*                           |
| Context | Injected by the runner for every run            | Always available: `${test_name}`, `${device_serial}`, `${iteration_index}` |

## How they fit together

```
Elements  ──►  Steps  ──►  Modules  ──►  Test case  ◄──  Data set
(locators)    (actions)   (reusable)     (the flow)      (the values)
                                              │
                                              ▼
                                        Test Suites
                                  Job ──► Devices ──► Report
```

You author each thing once and combine them. A locator lives in the step that recorded it, a repeated flow lives in a module, a value lives in a data set, and the test just references them.

## Where things live

| Screen        | What it holds                                                             |
| ------------- | ------------------------------------------------------------------------- |
| Test Creation | The free-device pool and your uploaded app builds. Where sessions start   |
| Workspace     | The live device screenshot and the step builder. Where tests are recorded |
| Test Cases    | Every test in the project                                                 |
| Modules       | The reusable module library, with version history                         |
| Elements      | A named-locator reference library                                         |
| Variables     | Every variable in the project and where its value comes from              |
| Data Sets     | Your data tables                                                          |
| Test Suites   | Where runs are launched and scheduled                                     |
| Test Reports  | Results                                                                   |

## Sessions vs runs

These are two different things and mixing them up causes confusion.

|                | Session (authoring)                                  | Run (execution)                          |
| -------------- | ---------------------------------------------------- | ---------------------------------------- |
| What it is     | A live device you are driving by hand                | An unattended job on one or more devices |
| Where          | The Workspace                                        | The Test Suites                          |
| Started by     | **Start Testing** on the Test Creation screen        | **Run now** on the Test Suites screen    |
| App launch     | Already open: you opened it                          | Generated from the app you select        |
| `${variables}` | Previewed with the value this device will really use | Resolved per device from your data set   |
| Ends when      | You stop the session                                 | The job finishes                         |

While authoring, a bound variable shows the value the device you are on would really use, so what you see typed on the device screenshot is what a real run will type.

## What App Studio does for you at run time

Two things are added to your test automatically, which is why you never author them yourself:

* **The app launch.** Your test has no launch step because your session was already open when you recorded it. The app you pick on the run screen is what gets installed and launched.
* **The test data.** If your test reads data-set columns, the right row for each device is loaded before the test starts.

Your references are also checked before the run begins. A broken variable, data-set column, element or module link stops the run immediately, on screen, before any device time is used. A rejected run costs you nothing but the time to read the list.


# Recording tests

How steps get into a test case: the right-click menu, the keyword catalogue, and what to do when the default locator is not quite right.

**Prerequisites:** an app uploaded and a device session started. See [Author your first test](https://docs.mozark.ai/no-code-studio/getting-started/author-your-first-test).

## The workspace

Starting a session opens the Workspace:

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FxDlcdtXoXZGP1jSVMURN%2F14-workspace.png?alt=media&amp;token=cbbf85b9-751e-4304-91c1-410d1fe70328" alt=""><figcaption></figcaption></figure>

* **Left: the device screenshot.** A live screenshot of the real device. It is interactive: tap and type on it exactly as if you were holding it.
* **Right: the authoring panel.** The **Step Builder** holds your recorded steps. The **⋯ menu above it opens Elements** (a searchable list of everything on the current screen) and **Page Source** (the raw UI tree).

## Recording a step

Right-click any element on the device screenshot. The strip along the top of the menu shows the element you are pointing at (its visible text, or its XPath when it has no text) so you can confirm you grabbed the right thing before choosing an action.

The menu has two levels:

* **Popular**: the three commands that cover most of what a test does: **Press Element**, **Enter Text**, **Assert Presence**.
* **All Commands**: hover or click to open the full catalogue beside it, with a search box and everything grouped by category.

Pick a command and the step lands in the Step Builder with the element's locator already filled in.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FaZvwd00het73dhipTnKa%2F17-recorded-step.png?alt=media&amp;token=7e2174d8-3463-41bc-846a-fd54e8f6cd8e" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Press Element runs immediately when you record it.** The tap you just authored happens on the real device there and then, so the device screenshot stays in step with your test. Every other command is recorded without being executed; play it back yourself when you are ready.
{% endhint %}

### Tools

At the bottom of the **All Commands** panel is a **Tools** section for things that are not test steps:

| Tool                        | What it does                                                                                         |
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
| Extract value into variable | Reads the text off this element at run time and stores it in a `${variable}` for a later step to use |
| Copy XPath                  | Copies the element's locator to your clipboard                                                       |

### Adding a step without an element

Not every step acts on something you can point at: *Sleep*, *Launch other app*, *Enter Text Direct*. Use **Add → Step** in the Step Builder header and pick the keyword from the list. Locator parameters are left empty for you to fill in.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FQbw4R6VOGrSuu97cQ1uU%2F19-add-menu.png?alt=media&amp;token=15f1f015-9391-4ed8-a206-cd4a3a9f1e1b" alt=""><figcaption></figcaption></figure>

## Locators and fallbacks

When you right-click an element, App Studio records more than one way to find it:

```
Primary   //android.widget.EditText[@resource-id="et_search"]
Fallback  //*[@content-desc="Search movies"]
Fallback  Search movies
```

At run time the engine tries each candidate in order. Each candidate also cascades through the matching strategies: XPath, then visible text, then OCR.

This is why a recorded test tends to survive a redesign that would break a hand-written selector, and why the same test usually runs unchanged on devices whose XPaths differ.

If a step still cannot find its element, see [Troubleshooting](https://docs.mozark.ai/no-code-studio/reference/troubleshooting).

### Search-area parameters

Most element keywords carry four extra parameters, **Search area X, Y, width, height**. They are percentages of the screen and default to `0, 0, 100, 100` (the whole screen).

Narrow them when the same text appears more than once and you only care about one region. To match only in the bottom half of the screen:

```
Search area X       0
Search area Y       50
Search area width   100
Search area height  50
```

Leave them at the defaults unless you have a reason.

## Working with recorded steps

| Action                   | How                                                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Reorder                  | Drag a step by its handle                                                                                                       |
| Edit a parameter         | Click the field on the step card and type                                                                                       |
| Play everything          | **Run all** in the Step Builder header                                                                                          |
| Stop a run               | **Stop**, which replaces Run all while it is running                                                                            |
| Play from one step       | Step overflow menu → **Run from here**                                                                                          |
| Delete                   | Step overflow menu → **Remove step**                                                                                            |
| Insert a variable        | Focus a field, then click `{x}` at the top of the step list                                                                     |
| Insert a data-set column | Focus a field, then click the data-set button. See [Test data](https://docs.mozark.ai/no-code-studio/authoring-tests/test-data) |

Use **Run from here** while you iterate. It saves replaying a long login every time you adjust the last step.

## Stopping and naming

Click **Stop** when you are done. It saves the steps, releases the device, and opens the recording on the **Test Cases** screen, where it carries a placeholder name such as `Unsaved recording · Pixel 7 · 26 Aug, 15:42`.

Type a real name and click **Save**. To carry on editing an existing test on a device later, open it from **Test Cases** and start a session from there.

## Capturing a value from the screen

Some tests need a value the app generates: an OTP, an order number, a balance.

1. Right-click the element showing the value.
2. **All Commands → Tools → Extract value into variable**.
3. Give it a name, for example `order_id`.

App Studio records a **Get Text** step that reads the element and stores the result in `${order_id}`. Any later step can use it:

```
Get Text         "#ORD-99341"   →  ${order_id}
Press Element    "Track order"
Enter Text       ${order_id}
Assert Presence  Tracking ${order_id}
```

Variable names must start with a letter or underscore and contain only letters, digits and underscores. `order_id` is valid; `2nd-order` is not.

The variable appears on the **Variables** screen with source **Runtime**, meaning its value only exists while the test is running.

{% hint style="warning" %}
**Order matters.** A runtime variable is only available to steps that come after the step that captured it. Using it earlier is a scope error, flagged with an amber badge on the step.
{% endhint %}

## The Elements screen

**Elements** is a named-locator reference library for the project. Each entry has a name and a set of per-platform locator candidates. It is useful as documentation of the locators your app uses, and it is populated automatically when you [import an existing Optics script](https://docs.mozark.ai/no-code-studio/authoring-tests/importing-an-existing-script).

{% hint style="info" %}
Recorded steps carry their own locators. A step you record in the workspace stores its XPath and fallbacks directly on the step; it does not point at an Elements entry. Editing an Elements row does not change steps you have already recorded. Treat this screen as a reference library, not as a central place to re-point existing tests.
{% endhint %}

## Keywords

Around 50 keywords are available. The ones you will actually use are listed in the [Keyword reference](https://docs.mozark.ai/no-code-studio/reference/keyword-reference).

## Next

* [Modules](https://docs.mozark.ai/no-code-studio/authoring-tests/modules): stop recording your login flow over and over.
* [Test data](https://docs.mozark.ai/no-code-studio/authoring-tests/test-data): one test, different data per device.
* [Conditions](https://docs.mozark.ai/no-code-studio/authoring-tests/conditions): branching for flows that vary.


# Modules

A module is a named, reusable group of steps: *Login*, *Search for a movie*, *Complete payment*. Record it once, use it in every test that needs it.

Modules are the difference between a suite you can maintain and forty test cases that each contain their own copy of the login flow.

## Create a module

1. In the Step Builder, select the steps you want to group.
2. Click **Create module**.
3. Give it a name, an optional description, and optional tags.

The selected steps are replaced in your test by a single **module block**: one card that stands for the whole group.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FMqbZ6Y3VnvIPW1eLct2z%2F28-create-module.png?alt=media&amp;token=4095e7e2-d25c-4f24-b64e-383e1ca81268" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Name modules after what they achieve, not how. *Login* ages better than *Tap email, type, tap password, type, tap submit*.
{% endhint %}

## Insert a module into another test

In the Step Builder, use **Add → Module** and pick from the library. The block is inserted at the end of your steps; drag it where you need it. Everything inside a module runs in order, exactly as recorded.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FEE2evN5DsWs3XMERWTuG%2F04-modules.png?alt=media&amp;token=270c20ce-0152-4bd9-8c19-501fb3e6624f" alt=""><figcaption></figcaption></figure>

## Versions

Modules are **versioned and append-only**. This is the part worth understanding, because it is what stops a shared module from breaking tests behind your back.

* The first save is version **1.0**.
* Editing the steps creates **1.1**, then **1.2**, and so on. The old version is never changed and never deleted.
* Reverting to an old version creates a **new** version that restores that snapshot. History stays intact.

Every test that uses a module **pins** the exact version it was built against. Improving a module does not change any existing test until you choose to move it.

| Change type | When it happens                                 |
| ----------- | ----------------------------------------------- |
| create      | The module was created                          |
| edit        | Its steps were changed                          |
| revert      | An older snapshot was restored as a new version |

### When a newer version exists

Open a test whose module block is pinned to an older version and App Studio tells you. You choose:

* **Update**: re-pin this block to the newest version.
* **Keep current**: stay on the pinned version. You will not be asked again for that version.

Nothing updates silently in either direction.

## The module detail page

Click a module in the library to open it. Three tabs:

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2F8YW8sKZrqZ7q0E90Q6eF%2F21-module-detail.png?alt=media&amp;token=f004694a-7d9f-410a-a2db-1a690475a230" alt=""><figcaption></figcaption></figure>

| Tab               | What it shows                                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Steps             | The steps in the current version                                                                                           |
| History           | Every version, who saved it and when, with the change type. Select two versions to see a step-by-step diff of what changed |
| Linked test cases | Every test using this module, and which version each one pins                                                              |

**Linked test cases** is also the delete guard: a module in use cannot be deleted. Remove its blocks from those tests first.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FIgyPN6u4W3cfjQrF5gI3%2F22-module-history.png?alt=media&amp;token=5c8316cb-0ba5-4d7a-ba27-3c09e547c0c2" alt=""><figcaption></figcaption></figure>

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2F4WjcG68qMeGaRmqjuEsv%2F23-module-linked.png?alt=media&amp;token=6cc13a0b-1813-4aeb-9267-9aeda267421a" alt=""><figcaption></figcaption></figure>

## Editing a module on a real device

Editing a module's steps blind is a good way to write a broken module. Instead, open the module on a live device and edit it against the real screen:

1. Open the module from the Modules library, or click a module block inside a test.
2. Start a device session.
3. Record, delete and reorder steps as usual, with **Run all** to verify them.
4. Click **Save version**.

Module edits are **not** autosaved, unlike test cases. Saving mints a new immutable version, so it is always an explicit action. If you opened the module from inside a test, saving hands you straight back to that test.

## Variables inside modules

Modules have scoping rules, because a module has to make sense wherever it is dropped in.

| Rule                                                             | Meaning                                                                                           |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Project variables work everywhere                                | Static variables, data-set lookups and the reserved context names are available inside any module |
| A variable captured inside a module is available after its block | Extract an OTP inside *Login* and later steps in the test can read it                             |
| A variable captured outside a module is not available inside it  | A module cannot depend on something a specific test happened to capture earlier                   |

The third rule is what keeps modules portable. If a module needs a value from its caller, put that value in a [data set](https://docs.mozark.ai/no-code-studio/authoring-tests/test-data) or a static variable instead of capturing it outside.

Violations show as an amber **variable scope** badge on the step, listing which names are missing. The **Create module** dialog warns you at the point of extraction if the steps you selected read outer variables.

## Worked example

A streaming app suite:

```
Modules
├── Launch and sign in          1.3
├── Navigate to watchlist       1.0
└── Search for a movie          1.2      ← reads ${movie_name}

Test cases
├── Add a movie to the watchlist
│     Launch and sign in     (pinned 1.3)
│     Search for a movie     (pinned 1.2)
│     Press Element  "Add to list"
│     Assert Presence  "Added to your list"
│
└── Remove a movie from the watchlist
      Launch and sign in     (pinned 1.3)
      Navigate to watchlist  (pinned 1.0)
      Press Element  "Remove"
      Assert Presence  "Your list is empty"
```

The sign-in flow is recorded once. When the login screen gets a new consent checkbox, you edit *Launch and sign in* on a device, save version 1.4, and update both tests, deliberately, when you are ready.


# Test data

One test case, different data on every device. This is what turns a recording into a test suite.

## The model: lookup by key

Read this section before anything else on this page. It is the one thing about App Studio that is genuinely different from what most people expect.

{% hint style="warning" %}
Test data binds by **looking up a row on a key column**. It does **not** iterate over rows.
{% endhint %}

Suppose you have a data set of movie names:

| device\_serial    | movie\_name  |
| ----------------- | ------------ |
| 0002721R60000D2A  | Interstellar |
| R5CT10ABCDE       | The Batman   |
| 00008110-001E2D3C | Dune         |

Run one test case on those three devices and you get **one run per device**, each reading **its own row**:

```
Pixel 7      (0002721R60000D2A)   ──► types "Interstellar"
Galaxy S23   (R5CT10ABCDE)        ──► types "The Batman"
iPhone 14    (00008110-001E2D3C)  ──► types "Dune"
```

Three devices, three different inputs, one test case, one run.

What it does **not** do is run three times on one device, once per row. If you want a value used on a particular device, put it in that device's row.

### Why it works this way

It maps onto how a device fleet actually works. Each device runs the suite in parallel, and each one knows its own serial number. The key column is how a row finds its device.

### What you can key on

The three reserved context names are supplied automatically for every run:

| Key column        | Matches on                                | Use it for                                    |
| ----------------- | ----------------------------------------- | --------------------------------------------- |
| `device_serial`   | The serial of the device running the test | Different data per device. The common case    |
| `test_name`       | The name of the test case being run       | Different data per test, same on every device |
| `iteration_index` | The iteration number                      | Repeat runs                                   |

## Variables

A variable is a named value written `${name}`. There are four sources.

| Source  | Value comes from                                | Created                                                                    |
| ------- | ----------------------------------------------- | -------------------------------------------------------------------------- |
| Static  | A literal you typed                             | By you, on the Variables screen                                            |
| Lookup  | A cell in a data set, matched on the key column | Automatically, when you bind a column to a step                            |
| Runtime | Read off the screen by an earlier step          | Automatically, by *Extract value into variable*                            |
| Context | Injected by the runner                          | Always available: `${test_name}`, `${device_serial}`, `${iteration_index}` |

Most of the time you never visit the Variables screen. Variables are created for you as a side effect of binding data or capturing a value. The screen is where you go to see what exists, check where a value comes from, or create a static one.

### Naming rules

Names must start with a letter or underscore, and contain only letters, digits and underscores. Names share one namespace across variables, elements and data sets, so two things cannot have the same name.

| Valid        | Invalid                     |
| ------------ | --------------------------- |
| `movie_name` | `movie name` (space)        |
| `order_id`   | `2nd_order` (leading digit) |
| `_temp`      | `order-id` (hyphen)         |

### Create a static variable

**Variables → New variable.** Give it a name and a value:

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FjAUV3lKzGJpIoQglviSC%2F24-new-variable.png?alt=media&amp;token=1b72671b-8276-4228-9636-cf1322c0c0a6" alt=""><figcaption></figcaption></figure>

```
Name    support_email
Value   support@example.com
```

Use it anywhere with `${support_email}`. Change it in one place and every test picks up the new value on its next run.

## Create a data set

**Data Sets → New data set.**

1. Name it, for example `movie_names`.
2. Enter the value columns (comma-separated), for example movie\_name.
3. Choose which row a test reads: Per device (key column device\_serial) or Per test case (key column test\_name).
4. Save, then open it and fill in the grid.

### Import instead of typing

The grid accepts a CSV or Excel file (`.csv`, `.xlsx`, `.xls`). Column headers become columns. Existing spreadsheets of test data usually drop straight in.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FaPyHeSAQZLSyN3fDy8vc%2F08-new-data-set.png?alt=media&amp;token=1b9906b5-2200-418b-bd7e-d32ca21661cc" alt=""><figcaption></figcaption></figure>

### Getting device serials

The serial in your key column has to match the device that will run the test. You can read a device's serial from the Test Creation screen, or from the Info tab of any past session in Test Reports.

### Secret columns

Mark a column **secret** to mask its values. Use it for passwords, PINs and card numbers.

| device\_serial   | username                | password 🔒 |
| ---------------- | ----------------------- | ----------- |
| 0002721R60000D2A | <test.user@example.com> | ••••••••    |

Secret values are masked in the UI and in reports. They still reach the device (the app under test needs them to work), so treat a secret column as "not shoulder-surfable", not as a vault.

## Bind a data-set column to a step

This is the whole point. Walkthrough, using the movie example.

**Goal:** an **Enter Text** step that types a different movie name on every device.

1. **Record the step normally.** On a live device, right-click the search field → **Enter Text**. Type anything for now, or leave it empty.
2. **Focus the Text field.** Click into the step's **Text** parameter. The field you have focused is where the next inserted reference will land.
3. **Open the data-set picker.** Click the **data set** button at the top of the step list. If the project has one data set, you go straight to its columns. Otherwise pick the data set first, for example `movie_names`. The picker lists the **value columns** only. Your key column is not offered, because that is the value you are matching *on*, not a value you are reading. Next to each column, the picker shows the value from **the row this device will actually match**, not simply the first row. What you see is what will be typed.
4. **Insert.** Select `movie_name` and click **Insert**. The step's Text field becomes `${movie_name}`.

That is it. Behind the scenes App Studio created a **lookup variable** for you:

```
Name     movie_name
Source   Lookup
Rule     read movie_name from movie_names
         where device_serial = the device running the test
```

You can see it on the **Variables** screen. Bind the same column again from another step and the existing variable is reused. You never end up with five variables pointing at the same cell.

5. **Mix it with literals.** A field takes any combination of text and references:

```
Search: ${movie_name}
Hello ${first_name}, order ${order_id} is ready
```

## Run it with data

1. Go to the **Test Suites → New test suite**.
2. Select your test case.
3. Select the devices, the ones whose serials are in the data set.
4. Select the **Application**.
5. **Test data**: see the note below.
6. **Run now**.

### About the Test data dropdown

If your data set is keyed on `device_serial`, App Studio finds it automatically. You do not have to select it: the columns your test references are loaded per device either way.

Select it explicitly when:

* the data set is keyed on something other than `device_serial`, or
* you want to be certain which data set a run used, or
* you have several data sets and want to be unambiguous.

Selecting it never hurts. It is safe to always pick the data set your test uses.

### What you get on the run

You do not have to do anything else. When the test runs, each device looks up its own row and every `${column}` you bound is filled in before the first step touches the app.

If you want to see exactly what a test will do with its data, download its bundle from the **Test Cases** screen. Your data grids are included, as saved. See [Running tests](https://docs.mozark.ai/no-code-studio/running-and-reporting/running-tests).

## Runtime variables: carrying a value between steps

Data sets supply values you know in advance. **Runtime variables** capture values the app generates.

1. Right-click the element showing the value.
2. **All Commands → Tools → Extract value into variable.**
3. Name it, for example `order_id`.

Any later step can use `${order_id}`. A runtime variable only exists during the run, and only after the step that captured it. Using it earlier raises a scope warning on the step.

## Common patterns

### Different credentials per device

Key: `device_serial`. Devices never collide over the same account, so tests can run in parallel.

| device\_serial   | username                | password 🔒 |
| ---------------- | ----------------------- | ----------- |
| 0002721R60000D2A | <test.user@example.com> | ••••••••    |

### Different expectations per test case

Key: `test_name`. Both tests use the same recorded steps and the same modules; only the data differs.

| test\_name           | search\_term | expected         |
| -------------------- | ------------ | ---------------- |
| Search finds a match | Interstellar | 1 result         |
| Search finds nothing | Zzzzqqq      | No results found |

### An environment value shared by everything

A static variable, not a data set:

```
Name   base_url
Value  https://staging.example.com
```

## Troubleshooting test data

| Symptom                                                    | Cause                                                                               | Fix                                                                       |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Run rejected: *Some ${references} could not be resolved*   | A step uses a name nothing supplies, usually a renamed variable or a deleted column | The unresolved names are listed under the form. Fix them and submit again |
| A step types nothing, or types the literal `${movie_name}` | No row matched this device                                                          | Check the serial in the key column matches the device exactly             |
| Every device types the same value                          | The data set is keyed on something constant                                         | Key it on `device_serial`                                                 |
| The picker will not let you insert                         | The data set has no key column                                                      | Open it and set one                                                       |
| A number comparison behaves oddly                          | Numeric comparisons use whole numbers                                               | Use integers, not decimals                                                |


# Conditions

Real apps do not always do the same thing. A promo screen appears on first launch. A consent dialog shows in some regions. A returning user skips onboarding.

A **Condition** block branches your test so one test case handles all of it.

## Add a condition

In the Step Builder, **Add → Condition**. A new block appears with two branches:

```
IF    <condition>
        (steps)
ELSE
        (steps)
```

Record steps into a branch by selecting it as the recording target, then right-clicking on the device as usual. Steps land in the branch you targeted.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FY26HF78YhGwnIqhecwIw%2F25-condition-block.png?alt=media&amp;token=d88cc0d2-60fa-43df-8a6e-cd02d9ae219c" alt=""><figcaption></figcaption></figure>

Add more paths with **ELSE IF**. Conditions can be nested inside branches.

{% hint style="info" %}
An empty branch is ignored entirely. If you add an ELSE and never put steps in it, it is simply not part of the test. Nothing breaks.
{% endhint %}

## Building the condition

Each branch runs when its condition is true. A condition is one or more **clauses**, joined by AND or OR. A clause has three parts: a **source**, an **operator**, and usually a **value** to compare against.

### Sources

| Source     | Checks                                                   | Example                            |
| ---------- | -------------------------------------------------------- | ---------------------------------- |
| Element    | Something on the screen                                  | `"Skip"` exists                    |
| Variable   | A `${variable}` value                                    | `${region}` equals `US`            |
| Expression | A raw expression, for cases the first two cannot express | `${count} > 0 and ${region}=="US"` |

For an element clause, enter the element as **visible text or an XPath**: the same thing you would see in the right-click menu header.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FAevPtApJaC2e3wE5Ih0z%2F26-condition-sources.png?alt=media&amp;token=e2161749-4527-42d1-b6b9-45f69fbbaf84" alt=""><figcaption></figcaption></figure>

### Operators

**Element clauses**

| Operator       | Meaning                                   |
| -------------- | ----------------------------------------- |
| exists         | The element is on screen                  |
| is not present | The element is not on screen              |
| text equals    | The element's text exactly equals a value |
| text contains  | The element's text contains a value       |

**Variable clauses** compare a variable with a value, including whole-number comparisons (`>` and `<`).

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FbGCwdMUayAFpkbG4X86u%2F27-condition-operators.png?alt=media&amp;token=0e785123-3d99-4f06-ab4d-5209b89d58aa" alt=""><figcaption></figcaption></figure>

### Probe timeout

Element clauses have a **timeout**, defaulting to 5 seconds: how long to look for the element before deciding it is not there.

Keep it short. This timeout is paid on **every** run where the element is absent, so a 30-second probe on a screen that usually does not appear adds 30 seconds to every run.

## Combining clauses

Clauses can be combined, with one restriction. A condition must be either:

* all element *exists* checks joined by AND, **or**
* all variable / expression checks (AND or OR).

Mixing an element check with a variable check in one condition is not supported. App Studio tells you rather than silently mis-compiling:

> Combine only element "exists" checks with AND, or only variable/expression checks. For other mixes, use an ELSE IF branch.

To express a mix, use separate branches or nest a condition inside a branch.

## Worked example: skip an onboarding screen

Your app shows a *Get started* carousel on first launch, but not for a returning user. Without a condition you need two test cases. With one:

```
Launch and sign in                       (module)
IF   "Get started"  exists   (timeout 5s)
       Press Element  "Skip"
       Press Element  "Continue"
ELSE
       (empty - nothing to do)
Navigate to watchlist                    (module)
Assert Presence  "My list"
```

One test case, both paths, no flakiness.

## Worked example: branch on looked-up data

Combine conditions with [test data](https://docs.mozark.ai/no-code-studio/authoring-tests/test-data) to vary behaviour per device or per market.

| device\_serial   | region |
| ---------------- | ------ |
| 0002721R60000D2A | US     |
| R5CT10ABCDE      | IN     |

```
IF   ${region}  equals  "IN"
       Press Element   "Pay with UPI"
       Enter Text      ${upi_id}
ELSE
       Press Element   "Pay with card"
       Enter Text      ${card_number}
Assert Presence  Payment Successful|Payment Complete   (rule: any)
```

## Things to know

|                                      |                                                                                                |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Numbers are whole numbers            | `>` and `<` compare integers. A decimal will not compare the way you expect. Use whole numbers |
| Empty branches are dropped           | A branch with no steps is not part of the test                                                 |
| Element clauses cost time when false | Every probe waits out its timeout before deciding the element is absent                        |
| Nesting is allowed                   | Put a condition inside a branch when the logic genuinely nests                                 |
| Modules work inside branches         | Insert a module block into a branch like any other step                                        |


# Importing an existing script

Already have an Optics test suite? Import it and carry on editing it in App Studio, with the device screenshot, modules, versions and data sets.

Go to **Test Cases** and click **Import script**.

## What you can upload

The **CSV files** of the suite. App Studio works out what each file is from its **header row**, never from its name, so folder structure and file names do not matter.

| Header contains                                            | The file is read as    | Becomes                                                             |
| ---------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------- |
| `test_case`, `test_step`                                   | Test cases             | A test case per name                                                |
| `module_name`, `module_step` (+ `param_1`, `param_2`, ...) | Modules                | A module at version 1.0                                             |
| `element_name`, `element_id` (+ fallback id columns)       | Elements and variables | Elements, or variables when the value is data rather than a locator |
| `error_code`, `match_string`                               | Error definitions      | Stored as project error codes. See Error definitions                |
| Anything else with a header and at least one row           | A data file            | A data set                                                          |

Two file types are **rejected, not skipped**:

* **`.zip` archives.** The contents cannot be read, so the suite cannot be checked. Unzip and upload the CSV files.
* **`.yaml` / `.yml` suite files**, other than `config.yaml`. YAML import is not supported yet, and a suite that hides entities in one cannot be validated.

`config.yaml` is ignored quietly. It carries nothing that is imported.

{% hint style="warning" %}
Header spelling matters to Optics itself: it looks for `test_case`, not `Test Case`. Case does not matter; spaces instead of underscores do. A file Optics ignores may still import here, so if a suite imports but never ran properly upstream, check the headers first.
{% endhint %}

## The wizard

```
Upload  ──►  Validate  ──►  Review  ──►  Done
```

1. **Upload.** Drop the files in, or use **Select files** / **Select folder**. Picks accumulate, so you can add `elements.csv` after `modules.csv`. Files that are not CSV, YAML or zip are filtered out of the selection.
2. **Validate.** The suite is checked with Optics' own linter. Every finding is anchored to a **file and a line**. Nothing is written at this stage.
3. **Review.** When there are no errors you get counts of what will be created: test cases, modules, actions, elements, variables and data sets, plus any warnings about how things were mapped.
4. **Import.** The suite is re-validated server side and written in a **single transaction**. Either all of it lands or none of it does. There is no half-imported state to clean up.

## What your suite becomes

| Your suite                             | Becomes                                                                             |
| -------------------------------------- | ----------------------------------------------------------------------------------- |
| A test case                            | A test case in **Test Cases**, built from module blocks in order                    |
| A module                               | A versioned module at version 1.0 in **Modules**                                    |
| An element                             | An entry in **Elements**, with its fallback ids, inlined onto the steps that use it |
| A `${variable}` with a literal value   | A static variable                                                                   |
| A `${variable}` set to `ENV:SOMETHING` | An env variable                                                                     |
| A `read_data` lookup                   | A lookup variable bound to the right data set and key column                        |
| A data CSV                             | A data set, with its key column detected from the lookup that reads it              |

The `read_data` loaders and the device-serial capture step are recognised and turned back into data sets and lookup variables, so they do not clutter your step list. They are regenerated automatically when you run.

### Names already in the project

Elements, variables and data sets are **reused** when the name matches (ignoring case), so re-importing an updated suite merges into the project library instead of littering it with copies.

Modules and test cases are **never** merged into: a clash gets a suffix, so you end up with `Login (imported)`, `Login (imported 2)` and so on. The Review and Done screens list what was reused.

## Fixing a broken script

Errors block the import. Warnings do not, but each one is telling you something about how your suite will behave. Fix the file at source and upload again.

### Errors

| Message                                                           | What happened                                                                       | Fix                                                                                                                         |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `Module 'X' not found`                                            | A test step names a module no uploaded file defines                                 | Upload the missing modules file, or correct the spelling. Module names must match exactly                                   |
| `'X' is not a keyword or module`                                  | A module step names neither an Optics keyword nor another module                    | Correct the keyword spelling, or add the module the step is calling                                                         |
| `'X' takes 1-2 params, got 3`                                     | The step passes the wrong number of parameters                                      | Usually a stray comma, or a notes column that is not named `description`. Remove the extra cell, or rename the column       |
| `'x' is not a defined element or variable`                        | A `${x}` reference has no matching row in an elements file, and no step produces it | Add the row, or fix the name. Data set column headers do not count: a column named `username` does not define `${username}` |
| `Row has fewer than 2 columns, which aborts the whole run`        | A short row in a test cases or error definitions file                               | Fill in the missing cell or delete the row. Optics crashes on these before anything runs                                    |
| `Cannot read inside an archive` / `Cannot read a YAML suite file` | A zip or a non-config YAML was uploaded                                             | Upload the CSV files directly                                                                                               |

### Warnings

| Message                                                     | What it means                                                                                                   |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `Row has fewer than 2 columns, so it is skipped`            | A short row in a modules or elements file. Optics drops the row, so the step or element silently does not exist |
| `Row has more columns than the header`                      | A ragged row. The extra cells are discarded. Often a comma inside an unquoted cell                              |
| `Whitespace-only line`                                      | A line of spaces. Harmless, but usually a sign of a hand-edited file                                            |
| `Duplicate module / test case 'X', see ...`                 | Two definitions of the same name. The later one wins wherever the files sit, so the first is dead weight        |
| `Duplicate error code / match string`                       | The same code is defined twice, or two rows match the same text and both fire                                   |
| `Row has no error_code / match_string, so it never matches` | An incomplete error definition row                                                                              |

### Things that are no longer errors

If you have imported this suite before and remember them failing:

* The same element name repeated with different ids is how fallback locators are written. Optics gathers them into one list and tries each in turn.
* A ragged row in an elements file loads fine. It is a warning now.

## If something goes wrong

| Message                                       | What to do                                                                                                                       |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| No suite files were uploaded                  | The selection was empty, or held no CSV. Select the CSV files themselves                                                         |
| Suite validation is unavailable               | The validator could not be reached. Nothing was checked and nothing was saved. Retry, and tell your administrator if it persists |
| Suite failed validation; nothing was imported | The files changed between Validate and Import. Validate again                                                                    |
| No test cases found in the uploaded suite     | No file was read as test cases. Check the `test_case` / `test_step` header                                                       |
| Upload the suite CSV files directly to import | A zip was still in the selection. Remove it                                                                                      |
| Import failed                                 | The write was rolled back. Nothing was saved. Retry                                                                              |

### Validation passed, but the counts look wrong

Nothing was rejected, but the Review step shows fewer test cases, modules or elements than the suite has. The usual causes:

* A file was left out of the selection. Add it and validate again.
* A header is misspelled, so the file was read as a data set instead of as test cases or modules. Check the header row against the table above.
* Rows were skipped for being short. Those appear as warnings with their line numbers.

If **0 test cases** are found, the import is refused outright with *No test cases found in the uploaded suite*.

## Worth checking after an import

* **Data set keys.** When no `read_data` lookup reads a data file, the key is guessed as the first column and you get a warning saying so. Open the data set and correct it if the guess is wrong.
* **Recovered descriptions.** If a modules file omits the empty-parameter comma before its description column, the description text lands in a parameter. App Studio detects the case and recovers it, with a warning naming the file. Verify those steps in the editor.
* **Imported locators land under Android.** An iOS suite imports, but its locators sit in the Android slot in the Elements library.

## After importing

Your suite is now editable like anything else in App Studio:

* Open a test case and record new steps against a live device.
* Open an imported module and edit it on a device, then save a new version.
* Open a data set and edit the grid, or add columns.
* [Run it](https://docs.mozark.ai/no-code-studio/running-and-reporting/running-tests).


# Running tests

Take the tests you recorded and run them unattended, on as many devices as you like, now or on a schedule.

**Prerequisites:** at least one saved test case, and an app build uploaded from the **Test Creation** screen.

## Launch a run

Go to **Test Suites**.

| Field       | What to do                                                                                                                             |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Suite name  | Optional label for the run, for example *Checkout smoke - nightly*. Shows up in reports                                                |
| Tests       | Tick one or more test cases                                                                                                            |
| Devices     | Tick one or more devices. Every test runs on every device you pick                                                                     |
| Application | The build to install. **Always set this**: see below                                                                                   |
| Test data   | The data set to bind. Optional for device-keyed sets. See [Test data](https://docs.mozark.ai/no-code-studio/authoring-tests/test-data) |
| Schedule    | Off runs immediately. On runs weekly                                                                                                   |

Click **Run now**. With a schedule set the button reads **Schedule run**.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FWYYZn7Wrgk9Ujt7QcD8O%2F09-new-test-suite.png?alt=media&amp;token=67d2f065-0967-44d7-9250-a44aefb2bf5f" alt=""><figcaption></figcaption></figure>

The footer summarises what you are about to launch, for example *"3 tests · 5 devices · movie\_names"*, so you can sanity-check before committing device time.

### Always choose an Application

The Application dropdown defaults to *"Auto - the app each test was recorded against"*. That works only if the test case already remembers a build. If it does not, the run installs nothing, launches nothing, and comes back **DID NOT RUN** several minutes later with no obvious cause.

{% hint style="danger" %}
Pick the build explicitly. It takes a second and removes the single most common cause of a wasted run.
{% endhint %}

Only builds that match your selected devices' platform are offered. Each option shows the app name, version, package name, platform and upload time, so two builds of the same app are easy to tell apart:

```
Streaming App · v4.2.1 · com.example.streaming · Android · 2 hours ago
```

## How a run is split into jobs

**One job = one platform + one app.** App Studio groups your selection accordingly and submits one job per group.

| Your selection                                             | Jobs                     |
| ---------------------------------------------------------- | ------------------------ |
| 3 tests, 4 Android devices, one app                        | 1 job                    |
| 3 tests, 2 Android + 2 iOS devices                         | 2 jobs, one per platform |
| 2 tests recorded against different apps, 4 Android devices | 2 jobs, one per app      |

This is expected, and each job gets its own report. Submitting a mixed selection is fine; you just get more than one result to read.

## Scheduling

Turn **Schedule** on and pick a day of the week and a time. The run fires at the next matching slot.

Scheduled runs do not open a report immediately. Check **Test Reports** after the scheduled time.

## When a run is rejected

Before any device time is used, App Studio checks every `${variable}`, data-set column, element and module reference in your selection. If something does not resolve you get:

> Some ${references} could not be resolved. Close this to see the details below, fix them, and try again.

The unresolved names are listed under the form with the test case they came from. Typical causes:

| Message points at | Usually means                                           |
| ----------------- | ------------------------------------------------------- |
| A variable name   | It was renamed or deleted after the step was recorded   |
| A data-set column | The column was renamed or removed                       |
| A module          | The module was deleted while a test still referenced it |
| An element        | The element entry a step points at is gone              |

Nothing was run. Fix the names and submit again.

## Export a runnable bundle

Need to run a test outside App Studio, or hand a reproducible suite to a developer? On the **Test Cases** screen, select one or more test cases and choose **Download bundle**.

You get a zip named after the test and the time, for example:

```
Add a movie to the watchlist 2026-08-27 1432.zip
```

It contains everything the test needs (steps, modules, locators and your data grids) for both platforms. Run it with the Optics CLI:

```shell
optics execute .
```

The bundle is generated the same way a real run is, so what you download is what would have executed.

## After you submit

A successful submission takes you straight to the report for the job. If the submission produced more than one job, you land on the reports list instead.

Next: [Reports](https://docs.mozark.ai/no-code-studio/running-and-reporting/reports)


# Reports

What happened, on which device, and where it went wrong.

## The reports list

**Test Reports** lists every job for the project, newest first: the suite name, when it ran, the platform and its overall status. Click a job to open its report.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FVLBbTAKdOjFc6LEdDQjc%2F10-reports-list.png?alt=media&amp;token=8c505ba7-89b7-4c4f-a406-d3f39c91ebe4" alt=""><figcaption></figcaption></figure>

## The job report

The top of the report summarises the run: who ran it, the run type, the app, the project, the duration, and a pass-rate chart, with Rerun and Get Shareable Link alongside.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2Fe1bfP9s0UgrDeyDBZUTS%2F11-job-report.png?alt=media&amp;token=adda5568-88a0-4484-84a2-d358e9ba7328" alt=""><figcaption></figcaption></figure>

Below it is the **Test cases table**:

* One **row** per test case
* Columns: Test case, Status, Device, Duration

```
Test case   Status   Device            Duration
TC-01       Passed   Samsung A50       1m 12s
TC-01       Passed   Redmi 9           1m 10s
TC-01       Failed   Samsung M12       1m 18s
```

This layout answers the question that matters most: **is this a broken test, or a broken device?** The same test case failing on every device is a test problem. Every test case failing on one device is usually a device or build problem.

## Statuses

| Status      | Meaning                                                                                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Passed      | Every step succeeded                                                                                                                                                |
| Failed      | A step failed, or an assertion did not hold                                                                                                                         |
| Did not run | The test never started, usually because the app never installed or launched. See [Troubleshooting](https://docs.mozark.ai/no-code-studio/reference/troubleshooting) |
| Running     | Still executing                                                                                                                                                     |
| Skipped     | Not executed in this run                                                                                                                                            |
| Completed   | Finished, without a pass/fail verdict                                                                                                                               |

## Session details

Click any row to open that session: one test case on one device. Five tabs:

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2F3SFWqQNwdN1aCXGPtnHL%2F12-session-steps.png?alt=media&amp;token=6fb55f10-62cc-43a6-bc5f-a9730342c93d" alt=""><figcaption></figcaption></figure>

| Tab         | What is in it                                                                                |
| ----------- | -------------------------------------------------------------------------------------------- |
| Steps       | Every step in order, with its status and timing. Expand a step to see its individual actions |
| Screenshots | Every screenshot captured during the session                                                 |
| Video       | A recording of the whole session, if session video was enabled                               |
| Files       | Logs and other artefacts produced by the run                                                 |
| Info        | Device, app, session and run metadata                                                        |

## Reading a failure

1. Open **Steps** and find the **first** failed step. Later failures are usually consequences of the first one.
2. Look at the step's screenshot. Most failures are obvious from the picture: the app was on a different screen, a dialog was in the way, the button moved.
3. If the screen looks right but the step still failed, the locator did not match. See [Troubleshooting](https://docs.mozark.ai/no-code-studio/reference/troubleshooting).
4. If the screen looks wrong, scrub the **Video** back a few seconds to see how it got there.

{% hint style="info" %}
The first failure is the real one. A test that fails at step 4 will usually fail every step after it too, because the app is no longer where the test thinks it is.
{% endhint %}

## Capturing more, or less

What ends up in a report is chosen when you start the session, in Advanced settings on the **Test Creation** screen:

| Capability           | Effect on the report                 |
| -------------------- | ------------------------------------ |
| Record Session Video | Adds the **Video** tab               |
| Step Screenshots     | Populates the screenshot timeline    |
| Capture Device Logs  | Adds logcat / syslog to **Files**    |
| Capture Network Logs | Adds network traffic to **Files**    |
| Capture App Profile  | Adds CPU, memory and battery samples |

The defaults capture everything useful. Turn things off only if you have a specific reason.


# Call an API from a test

An **Invoke API** step calls an API in the middle of your test. You extract a value from the API response and use it in later steps.

## 1. Add the step

In the Step Builder header, choose **Add → Add step**, search for `invoke api`, and pick it. The step lands in the list as *No request configured yet*. Click **Configure**.

## 2. Configure the request

| Field      | Example                                                      |
| ---------- | ------------------------------------------------------------ |
| Collection | **+ New collection...** → `Optics API Testing`               |
| API name   | `get_name` (letters, digits and underscores only)            |
| Method     | `POST`                                                       |
| URL        | `https://optics-api-testing.free.beeceptor.com/api/get-name` |

Then open the **Params** tab:

| Key       | Value  |
| --------- | ------ |
| `user_id` | `1234` |

The drawer confirms what the step will call:

```
This step will call Optics_API_Testing.get_name
```

{% hint style="info" %}
**Base URL.** The first request in a new collection needs the full URL. Its host becomes the collection's base URL. Every later request in that collection can then be a plain path like `/api/get-name`.
{% endhint %}

**Variables work everywhere.** Params, headers and body all take `${refs}`, resolved when the test runs:

```
Params   user_id: ${user_id}
Header   Authorization: Bearer ${auth_token}
Body     { "email": "${user_email}" }
```

Click **Save**. The request is saved on the collection, so any other test can add a step that calls it by name.

## 3. Send it

Click **Send** to run the request against your live device session (you need a session open, the same one you are recording in). The **Response** panel shows the status, the time, the headers and the body:

```json
{ "name": "randomName" }
```

This is the same call the packaged run makes, so what you see here is what the run will do.

## 4. Use the response in a step

Hover the `name` value in the response and click **extract**. The modal shows the path and suggests a variable name:

```
JSON path   name
Value       "randomName"
Name        name
```

Click **Create**. It appears under **Extracted values** as `${name}`. The value refreshes on every run.

Now any **later** step can use it. Right-click the field on the device, choose **Enter Text**, and type `${name}` into the Text parameter. At run time step 3 types whatever the API returned on that run.

```
1  Invoke API        Optics_API_Testing.get_name   →  ${name}
2  Press Element     Search box
3  Enter Text        ${name}
4  Assert Presence   Results for ${name}
```

## Worth knowing

| Symptom                                  | Cause                                                                                   |
| ---------------------------------------- | --------------------------------------------------------------------------------------- |
| Send is disabled                         | No device session. Start one on **Test Creation**                                       |
| "The response is not JSON"               | Only JSON responses can be extracted from                                               |
| The API name is rejected                 | No dots, spaces or hyphens. The name is half of the identifier the run resolves         |
| A later step types the literal `${name}` | The extract was added after that step last ran. Send again, or replay from the API step |


# Watch a run live

While a job is still running you can watch the device and read its logs without waiting for the report.

## Where it is

**Test Reports** → open the running job → click any cell whose status is **Running**. The session drawer opens on a **Live** tab.

```
                  Pixel 7      Galaxy S23
Add to watchlist  Passed       Running   ← click this one
```

The job report refreshes itself every few seconds, so a cell that flips to Running becomes clickable on its own.

## The three panels

| Panel          | What you see                                                       |
| -------------- | ------------------------------------------------------------------ |
| Live Video     | The device screen as the test drives it. Read-only: you cannot tap |
| Framework Logs | What the automation framework is doing: each keyword, its result   |
| Device Logs    | Raw logcat (Android) or syslog (iOS) from the device               |

Switching tabs keeps all three connected, so you can jump between the screen and the log without losing the stream.

## When the session ends

The **Live** tab disappears: *This session has ended - the Video and Files tabs hold the recording.*

Everything you were watching is still there afterwards: the recording on **Video**, the logs on **Files**. See [Reports](https://docs.mozark.ai/no-code-studio/running-and-reporting/reports).

## Worth knowing

| Symptom                                 | Cause                                                                              |
| --------------------------------------- | ---------------------------------------------------------------------------------- |
| No **Live** tab on a running session    | Live views are off on this deployment                                              |
| "No device is attached to this session" | The run never reached a device. Check the job report's status                      |
| "Live view unavailable"                 | The stream could not connect. The run carries on; read the report when it finishes |


# Different data for each test case

Sometimes the data does not change per device. It changes per **test**: same steps, different customer, different region, different expected result.

A data set keyed **per test case** does that: one row per test case, matched on the test case's name. For the per-device model, see [Test data](/no-code-studio/authoring-tests/test-data).

## 1. Create the test cases

**Test Cases → New test case.** Name it and save, for example `TC_UK`. It has no steps yet, and that is fine: the name is what the data set binds to, so it has to exist first.

Repeat for every scenario you want its own row of data: `TC_IN`, `TC_US`.

## 2. Create the data set

**Data Sets → New data set:**

| Field                       | Value                             |
| --------------------------- | --------------------------------- |
| Name                        | `Customers`                       |
| Which row does a test read? | **Per test case**                 |
| Value columns               | `name`, `phone_number`, `address` |

`test_name` is added for you as the key column.

## 3. Map the test cases to rows

Open the data set. The key cell is a **test case picker**, not a text box: click it and choose the test case by name, so the name can never be mistyped. Add one row per test case and fill in the values.

| test\_name | name        | phone\_number   | address            |
| ---------- | ----------- | --------------- | ------------------ |
| TC\_UK     | Alice Brown | +44 7700 900123 | 12 King St, London |
| TC\_IN     | Rahul Menon | +91 98765 43210 | 4 MG Road, Pune    |
| TC\_US     | Dana Reed   | +1 415 555 0134 | 900 Market St, SF  |

An **amber cell** means the test case that row names no longer exists: it was renamed or deleted. Pick the right one again.

## 4. Write the steps and use the data

Back on **Test Cases**, open `TC_UK` and click **Edit on device**. Pick a device and record your steps as usual.

To type a value from the data set instead of a literal:

1. Click into the step's field (the **Text** parameter) so it has focus.
2. In the Step Builder header, choose **... → Insert variable**.
3. Choose **Import from data set...**
4. Pick `Customers`, select `name`, and click **Insert**.

The field becomes `${name}`, and the picker shows the value it will use (`Alice Brown`) because you are editing `TC_UK`. Open `TC_IN` and the same `${name}` resolves to `Rahul Menon`. You never select the row; the test case's name picks it.

```
Enter Text   ${name}           →  Alice Brown
Enter Text   ${phone_number}   →  +44 7700 900123
```

If the test case you are editing has no row yet, the picker says so and offers **Edit data set**, so you can add it without leaving the recording:

```
No row for "TC_US" yet - this test would have no data to read.
```

{% hint style="warning" %}
Take that warning seriously. Unlike a device-keyed set, a test-case-keyed set does **not** fall back to another row. No row means the step has nothing to type.
{% endhint %}

## 5. Run them

**Test Suites → New test suite**, select the test cases and your devices, then **Run now**. Each test case looks up its own row; the device it lands on makes no difference. More on launching runs: see [Running tests](/no-code-studio/running-and-reporting/running-tests).

## Worth knowing

| Symptom                                   | Cause                                                             |
| ----------------------------------------- | ----------------------------------------------------------------- |
| A step types nothing                      | This test case has no row. Add one                                |
| Run rejected, `${name}` unresolved        | Same thing: the row is missing, or the column was renamed         |
| The row stopped matching                  | The test case was renamed. Re-pick it in the grid's key cell      |
| You need per-device **and** per-test data | Use two data sets, one keyed each way, and bind columns from both |


# Error definitions

Every step can pass and the app can still end on an error screen: "Session expired", "Service unavailable", a payment declined.

An **error code** is a piece of text a run looks for on the screen at the end of each test case. If the text is there, the test case fails and the report says which code it was.

## 1. Open the error codes

Error codes live in the **project**, not in a test. Open them from a device session: **Test Creation** → start a session → **...** (left of refresh) → **Error codes**. The drawer lists every code in the project. Every run in the project checks all of them.

<figure><img src="https://952269762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRBaaAIJoDzwDclOOVa8Z%2Fuploads%2FgX2C0zGxddy95gFJ35Ty%2F18-error-codes.png?alt=media&amp;token=54307b97-955c-4eaf-8948-15c6386239e4" alt=""><figcaption></figcaption></figure>

## 2. Add a code

Click **New error code**:

| Field             | Example                        |
| ----------------- | ------------------------------ |
| Code              | `E_TIMEOUT`                    |
| Matches on screen | `Request timed out`            |
| Severity          | `medium`                       |
| Description       | Server took too long to answer |

**Code** and **Matches on screen** are required. Severity is free text: App Studio only shows it in the report, it does not change how the run behaves. A code must be unique in the project. Edit and delete from the row's menu, or select several rows to delete them together.

## 3. See it while you record

While you record, App Studio checks the screen in front of you against your codes. When one is on screen, an amber **⚠** appears in the inspector header, next to **...**. Click it: the panel lists the codes that matched (code, severity, the text that matched, and its description). **Re-check** runs the check again after the screen changes. *No errors* means nothing on this screen matches.

| Code        | Severity | Match string      | Matched on                            | Description                     |
| ----------- | -------- | ----------------- | ------------------------------------- | ------------------------------- |
| `E_SESSION` | high     | `Session expired` | Session expired, please sign in again | Kicked back to the login screen |

## 4. Read it in the report

A test case whose last screen matched a code is marked **Failed**, with the code as its reason, even if every step passed. Open the session from the job report. Its drawer has an **Errors** tab. No Errors tab means no code matched. See [Reports](https://docs.mozark.ai/no-code-studio/running-and-reporting/reports).

## How matching works

* The screen is checked **once, at the end of each test case**, whether its steps passed or not. A code that flashes up mid-test and goes away is not caught.
* The match is **plain text, ignoring case**. `Session expired` matches `SESSION EXPIRED, please sign in again`. It is not a pattern: `*` and `.` are matched literally.
* It reads the **text on the screen** (the page source), not the pixels. Text drawn inside an image is not seen.

## Import and export

An existing suite's error definitions come in through **Import script**. Any CSV whose header has `error_code` and `match_string` is read as error codes (`description` and `severity` are picked up too):

```
error_code,match_string,description,severity
E_SESSION,Session expired,Kicked back to the login screen,high
E_DOWN,Service unavailable,,medium
```

Codes already in the project are reused when the code matches, ignoring case. When a run is packaged, every code in the project goes into it as `test_data/error_definitions.csv`: all of them, not only the ones a test uses. See I[mporting an existing script](/no-code-studio/authoring-tests/importing-an-existing-script).

## Worth knowing

| Symptom                                         | Cause                                                                                                                    |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| The error screen showed but no **Errors** tab   | The text was not on screen when the test case ended, or it is inside an image. Or it differs: check spelling and spacing |
| A test case failed but every step passed        | Its last screen matched an error code. The **Errors** tab says which                                                     |
| A code matches on every run                     | Its text is too common. `Session` matches any screen that says "session" anywhere. Use a longer phrase                   |
| Two codes fire on the same screen               | Both texts are on it, or one contains the other                                                                          |
| Code already exists                             | Codes are unique per project, ignoring case. Edit the existing one                                                       |
| The import counted an errors file as a data set | Its header is not `error_code`, `match_string`. Fix the header row                                                       |
| No step for error codes in the Step Builder     | There isn't one. Codes are checked on every run; you do not add them to a test                                           |


# Keyword reference

Around 50 keywords are available. These are the ones you will actually use. Open the full catalogue any time with **right-click → All Commands**.

## Element actions

| Keyword                   | What it does                                                                            | Key parameters                                 |
| ------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
| Press Element             | Taps the element                                                                        | element, repeat (1), index (0), offset x/y (0) |
| Enter Text                | Taps the element, then types into it                                                    | element, text                                  |
| Enter Text Direct         | Types into whatever already has focus. No element, no tap                               | text                                           |
| Enter Text Using Keyboard | Types key by key through the device keyboard, for fields that ignore programmatic input | text                                           |
| Enter Number              | Types a numeric value                                                                   | number                                         |
| Clear Element Text        | Empties a text field                                                                    | element                                        |
| Get Text                  | Reads the element's text into a variable                                                | element, variable name                         |
| Press By Coordinates      | Taps an absolute point                                                                  | x, y (device pixels), repeat                   |
| Press By Percentage       | Taps a relative point. `50, 50` is the centre of the screen                             | x, y (0-100), repeat                           |
| Press Keycode             | Sends an Android key code: 4 is Back, 3 is Home, 66 is Enter                            | keycode                                        |
| Detect And Press          | Taps the element if it appears within the timeout. Passes even if it never appears      | element, timeout                               |
| Select Dropdown Option    | Scrolls a dropdown looking for an option and picks it                                   | option, timeout                                |

## Scrolling and swiping

| Keyword                      | What it does                                                                            | Notes                                                  |
| ---------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| Scroll                       | Scrolls from an element                                                                 | Up and down only. Use Swipe for sideways movement      |
| Scroll Until Element Appears | Keeps scrolling until the element shows up or the timeout expires                       | Up and down only                                       |
| Swipe                        | Swipes from an absolute starting point                                                  | start x, start y, direction, distance in device pixels |
| Swipe By Percentage          | Same, but the distance is a percentage of screen height (up/down) or width (left/right) | Not pixels: this one is the exception                  |
| Swipe Until Element Appears  | Keeps swiping until the element shows up                                                | All four directions                                    |

## Validation

| Keyword           | What it does                                                                    |
| ----------------- | ------------------------------------------------------------------------------- |
| Assert Presence   | Checks the element exists in the UI tree. Accepts a list and a rule (any / all) |
| Assert Visibility | Same fields, but checks the element is actually rendered on screen              |
| Validate Element  | Checks a state of the element: visible / invisible, enabled / disabled          |
| Validate Screen   | Checks the screen as a whole                                                    |

{% hint style="warning" %}
**Presence is not visibility.** Assert Presence passes for an element that exists in the UI tree but has been scrolled out of view. When you mean "the user can see this right now", use Assert Visibility.

On Validate Element, **visible / invisible** check the screen, so they work for image and OCR matches. **enabled / disabled** need a real element handle and do not work on image or OCR matches.
{% endhint %}

## App actions

| Keyword          | What it does                        |
| ---------------- | ----------------------------------- |
| Launch Other App | Opens a different app on the device |
| Terminate App    | Closes an app                       |
| Background App   | Sends the app to the background     |

## Device actions

Rotate Device, Set Orientation, Lock Device, Unlock Device, Shake Device.

## Waits and inspection

| Keyword             | What it does                                                                     |
| ------------------- | -------------------------------------------------------------------------------- |
| Sleep               | Pauses for a number of seconds. Use sparingly; prefer a wait-for-element keyword |
| Capture Screenshot  | Takes a screenshot into the report at this point                                 |
| Capture Page Source | Dumps the UI tree into the report                                                |

## Keywords you will not see

A few keywords are not in the picker because App Studio handles them for you:

* **App launch** is generated from the app you pick on the run screen.
* **Branching** is authored through the [Condition](https://docs.mozark.ai/no-code-studio/authoring-tests/conditions) block rather than a keyword.

## Search-area parameters

Most element keywords carry four extra parameters, **Search area X, Y, width, height**, all percentages of the screen, defaulting to `0, 0, 100, 100`. See [Recording tests](https://docs.mozark.ai/no-code-studio/authoring-tests/recording-tests).


# Troubleshooting

Common problems, grouped by where you meet them. Each entry says what is usually behind it and how to fix it.

## Starting and authoring

| Symptom                                                                            | Usually means                                                               | Fix                                                                                                                                                              |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The upload is refused before it starts                                             | The file does not match the platform tab (`.apk` on Android, `.ipa` on iOS) | Switch tab, or pick the right build                                                                                                                              |
| An iOS build stays at *processing*                                                 | Re-signing is slow or failed                                                | Wait a couple of minutes; if it is still processing after several minutes, re-upload                                                                             |
| App Studio stops when you click **Start Testing** and mentions a platform mismatch | The selected app and the device are on different platforms                  | Clear the app and start anyway, or go back and pick a matching build                                                                                             |
| A step cannot find its element                                                     | None of the recorded locators matched on this screen or device              | See below                                                                                                                                                        |
| A step is flagged with an amber **variable scope** badge                           | It uses a variable captured later, or outside its module                    | Move the capturing step earlier, or put the value in a data set or static variable. See [Modules](https://docs.mozark.ai/no-code-studio/authoring-tests/modules) |

### A step cannot find its element

1. Re-record the step on the current screen and compare the locators with the old one.
2. If the same text appears more than once, set **Match index** or narrow the **Search area**. See [Recording tests](https://docs.mozark.ai/no-code-studio/authoring-tests/recording-tests).
3. If the element only appears sometimes, wrap the step in a [Condition](https://docs.mozark.ai/no-code-studio/authoring-tests/conditions).
4. Check that the element is in the UI tree, with **Inspect → Elements** or **Page Source**.

## Running

| Symptom                                                  | Usually means                                                                                                   | Fix                                                                                                                                               |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **DID NOT RUN** several minutes after submitting         | The Application was left on *Auto* and the test does not remember a build, so nothing was installed or launched | Re-run with the **Application** chosen explicitly. See [Running tests](https://docs.mozark.ai/no-code-studio/running-and-reporting/running-tests) |
| Run rejected: *Some ${references} could not be resolved* | A variable, data-set column, element or module a step uses no longer exists                                     | The unresolved names are listed under the form. Fix them and submit again                                                                         |
| You got more than one report from one submission         | The selection spans several platforms or apps, so it was split into jobs                                        | Expected: one job per platform and app                                                                                                            |
| A scheduled run produced no report                       | Scheduled runs do not open a report immediately                                                                 | Check **Test Reports** after the scheduled time                                                                                                   |

## Test data

| Symptom                                                    | Cause                                       | Fix                                                           |
| ---------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------- |
| A step types nothing, or types the literal `${movie_name}` | No row matched this device                  | Check the serial in the key column matches the device exactly |
| Every device types the same value                          | The data set is keyed on something constant | Key it on `device_serial`                                     |
| The picker will not let you insert                         | The data set has no key column              | Open it and set one                                           |
| A number comparison behaves oddly                          | Numeric comparisons use whole numbers       | Use integers, not decimals                                    |

## Reports

| Symptom                        | Fix                                                                                                                                 |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| A whole **row** failed         | It is a test problem. Open any cell in the row and find the first failed step                                                       |
| A whole **column** failed      | It is usually a device or build problem. Check the **Info** tab and the build you selected                                          |
| The later steps all failed     | Only the first failure matters. Fix it and re-run                                                                                   |
| No video or logs in the report | The capability was off when the session started. See [Reports](https://docs.mozark.ai/no-code-studio/running-and-reporting/reports) |

## Importing a script

See the error and warning tables in [Importing an existing script](https://docs.mozark.ai/no-code-studio/authoring-tests/importing-an-existing-script).


# Test Infrastructure

Start here to navigate the Testing Portal docs by workflow, platform topic, and support need.

## Test Infrastructure&#x20;

Use this space to understand the Testing Portal and navigate to the relevant workflow or platform topic.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2FY7zumOG0dj1ZDMJO6k7W%2FScreenshot%202026-07-02%20at%2012.19.11%E2%80%AFPM.png?alt=media&amp;token=8cb3616d-60d9-4280-8b34-ae9231cafcf9" alt=""><figcaption></figcaption></figure>

### Start here

* [Getting Started](/test-infrastructure-documentation/getting-started/create-your-first-workflow) — Access the portal, sign in, and select the appropriate organization, app, and project.
* [Product Overview](/test-infrastructure-documentation/getting-started/overview) — Understand the portal's main modules, services, and navigation model.

### Explore by workflow

* [Interactive Testing](/test-infrastructure-documentation/interactive-testing/overview) — Launch live manual test sessions across web, mobile, and TV platforms.
* [Automation](/test-infrastructure-documentation/automation/overview) — Connect Playwright and Appium suites to remote execution infrastructure.
* [Sessions](/test-infrastructure-documentation/sessions/overview) — Search, filter, and review interactive and automation session history.

### Shared platform topics

* [File Management](/test-infrastructure-documentation/file-management/overview) — Upload, organize, and reuse app builds and test assets.
* [UI and Navigation Behavior](/test-infrastructure-documentation/ui-and-navigation-behavior) — Understand themes, notifications, navigation, and shared interface patterns.
* [Permissions and Security](/test-infrastructure-documentation/permissions-and-security) — Review authentication, access control, and project-level isolation.

### Operational guidance

* [Known Limitations and Edge Cases](/test-infrastructure-documentation/known-limitations-and-edge-cases) — Review current constraints and release-specific behavior.
* [Best Practices](/test-infrastructure-documentation/best-practices) — Follow recommended patterns for sessions, bugs, files, and AI usage.
* [Troubleshooting & FAQs](/test-infrastructure-documentation/troubleshooting-and-faqs) — Resolve common issues with login, sessions, devices, files, and scheduled tests.

### Intended audience

* **QA engineers and manual testers** who run interactive sessions, file bugs, and review recordings.
* **Automation engineers** who connect Playwright or Appium suites, or use Optics AI workflows.
* **Engineering managers and stakeholders** who review coverage, session history, and quality outcomes.


# Overview

A high-level map of the portal's modules and how they connect.

## Product Overview

Use this page to understand the portal's main modules and how they work together.

### Architecture at a glance

The Testing Portal is a single-page web application connected to several backend services.

You do not need deep backend knowledge to use it effectively.

This model helps explain why some actions feel instant, while others take longer.

Launching a session is usually immediate.

Loading session video can take longer because recorded assets are fetched separately.

| Service                   | What it does                                                                               | When you interact with it                                          |
| ------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| Session Service           | Creates and tracks test sessions. Stores metadata, notes, and configuration.               | Launching sessions, viewing session history, editing session names |
| Manual Test Service       | Manages bugs filed against sessions and video timestamp markers.                           | **Bugs** tab, **Video** tab markers                                |
| Tags Service              | Creates and assigns searchable labels to sessions.                                         | Adding or removing tags in session rows                            |
| Files Service             | Stores app builds and test artifacts with metadata.                                        | **File Management** page                                           |
| Admin Control Panel (ACP) | Manages organizations, apps, projects, and user assignments.                               | Organization, app, and project selector in the top navigation      |
| Optics AI Service         | Runs AI browser agents through WebSocket connections for live interaction and exploration. | **Interact** page, **Explorer** page                               |

### Main modules

#### Interactive testing

Launch live manual test sessions on web, mobile, and TV platforms.

Capture bugs and screenshots in real time.

#### Automation testing

Connect Playwright and Appium test suites to the platform's remote hubs.

View automation results alongside interactive sessions.

#### Optics AI automation

Use natural language to control a live browser in **Interact**.

Use **Explorer** to let AI discover and test application flows autonomously.

#### Sessions

View all sessions across platforms in one searchable list.

Filter, paginate, and open sessions to review video, screenshots, bugs, and notes.

#### File Management

Upload app builds, APKs, IPAs, and other test assets.

Tag files with metadata, then download or share them as needed.

#### External integrations

Open the Mozark Dashboard and Test Case Repository from the sidebar.

These links open the rest of the quality suite in one click.

### Navigation structure

The portal includes three persistent navigation elements.

#### Top navigation bar

The top bar spans the full width of the portal.

It includes the Mozark logo, a light and dark theme toggle, and your user menu.

Use the user menu to switch organization, app, and project context.

You can also open the Admin portal from there.

#### Sidebar

The sidebar runs vertically on the left.

It is collapsible.

Use the arrow at the bottom to switch to icon-only mode and free more horizontal space.

The sidebar contains top-level navigation items.

External links such as **Dashboard** and **Test Case Repository** open in a new tab.

#### Breadcrumbs

Breadcrumbs appear at the top of the main content area.

They show your current location in the portal hierarchy.

For example: `Interactive → Sessions → Session Summary`

Select any breadcrumb item to go back to that level.


# Create your first workflow

Access the portal, sign in, and select the right working context before your first test.

## Getting Started

Use this page to access the portal, sign in, and select the appropriate working context before your first test.

### Prerequisites

Before you begin, make sure you have:

* An invitation email from your organization's platform administrator, or an account already created for you by your administrator.
* Access to an email inbox that can receive verification codes, if multi-factor authentication is enabled.
* Membership in at least one organization, app, and project in the Mozark Admin Control Panel.
* A modern Chromium-based desktop browser:
  * Google Chrome 110+
  * Microsoft Edge 110+
* Safari and Firefox support is limited for live device streaming.
* A stable internet connection. Live session streaming uses WebSocket connections and works best with low latency.

### Logging in

The Testing Portal uses Single Sign-On through the Mozark identity provider.

You do not create a separate password for this portal.

1. Open the portal URL - <https://testinfra.mozark.ai&#x20>;
2. If you are not already signed in, the portal redirects you to id.mozark.ai&#x20;
3. Enter your credentials on the sign-in page.
4. Use your corporate email and password, or your organization's identity provider if SAML or OAuth federation is enabled.
5. After authentication succeeds, the portal redirects you back automatically.

Your session token is stored securely and refreshed in the background.

If your session expires while you are active, the portal redirects you back to the sign-in page.

Save work regularly, since open forms or unsaved changes may be lost.

{% hint style="info" %}
**Tabs stay in sync**

If you sign out in one browser tab, all open portal tabs sign out within seconds.

This behavior prevents stale sessions.
{% endhint %}

### Selecting your working context

The portal organizes data in a three-level hierarchy:

`Organization → App → Project`

Before you run any test, confirm that the correct context is selected.

Sessions, files, and bugs are always scoped to the active project.

1. Open the top navigation bar.
2. Click your user avatar or name on the right side.
3. Select your **Organization**.
4. Select your **App**.
5. Select your **Project**.

If you belong to multiple organizations, choose the one you want to work in first.

The selected organization controls which apps and projects are available.

Projects usually map to a release, feature area, or team.

Use the search box in the dropdown if the project list is long.

The portal saves your selection automatically.

When you return in the same browser, your last-used organization, app, and project are preselected.

{% hint style="warning" %}
**Always verify your project before launching a session**

Sessions, bugs, and files stay tied to the project that was active when they were created.

If you launch a session under the wrong project, its results will not appear in the intended project's history.
{% endhint %}


# Overview

Launch and run live manual test sessions across web, mobile, and TV platforms.

## Interactive Testing

Use this page to launch and run live manual test sessions across web, mobile, and TV platforms.

{% hint style="info" %}
Interactive Testing sessions open in a separate browser window or application provided by Mozark's session infrastructure.

The Testing Portal handles configuration and session tracking.

The live device view runs in that separate window.
{% endhint %}

### Web Testing

Test websites and web applications in real browsers running on real operating systems.

#### Launching a Web Session

Navigate to **Interactive → Web** in the sidebar.

The configuration screen uses four selection columns.

Complete them from left to right.

Each column becomes active only after the previous one is filled.

1. **Operating System** Select the OS family, such as Windows or macOS.

   Then select a specific version, such as Windows 11, Windows 10, or macOS Sonoma.

   Options shown in gray are temporarily unavailable.
2. **Browser** Select the browser.

   Available options include Chrome, Firefox, Edge, and Safari.

   Safari availability depends on the selected OS.

   Options with no available versions appear disabled.
3. **Browser Version** Select the specific browser version.

   Newer versions appear first.

   Unavailable versions appear grayed out.
4. **Resolution** Select the screen resolution for the session, such as `1920×1080`.

   Available resolutions depend on the selected browser and OS.
5. **Launch Session** Click **Launch Session** in the top-right corner.

   The portal contacts the session service, allocates a remote machine, and redirects you to the live session.

   If all slots are occupied, the portal shows an error toast.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2Foa6aghPHu9bvp5xuWEW0%2FScreenshot%202026-07-01%20at%204.38.13%E2%80%AFPM.png?alt=media&amp;token=02fb325a-885e-4422-8d8b-3bb4c0dcf0e0" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Do not close the configuration tab immediately after launch.

The redirect to the live session window happens automatically.

If you close the tab before the redirect completes, the session can become orphaned and may not appear in session history.
{% endhint %}

#### Configuration Auto-Selection

When you open the Web selection page, the portal automatically preselects the first available option in each column.

You can launch immediately with the default configuration.

Change values only when you need a specific setup.

### Mobile Testing

Test native Android and iOS applications on real device configurations.

Navigate to **Interactive → Mobile**.

The selection screen works like Web testing, but uses a device-oriented layout.

1. **Select Platform** Choose **iOS** or **Android**.
2. **Select Device Brand** Review the available manufacturers for the selected platform.
3. **Select Device Model** Choose from the available models for that brand.

   Each model card shows the device name and relevant specifications.
4. **Launch Session** Click **Launch** to start the live device session.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2FenBumMYkXPhVGDJzLyNJ%2FScreenshot%202026-07-01%20at%204.39.23%E2%80%AFPM.png?alt=media&amp;token=7a85c44c-fa6b-4fba-aa5a-59c05e6f28da" alt=""><figcaption></figcaption></figure>

### TV Testing

Test connected TV and OTT applications on real TV device configurations.

Navigate to **Interactive → TV**.

The selection screen mirrors the mobile layout.

Select the TV brand and model, then launch the session.

TV sessions use a dedicated routing path within Mozark's infrastructure.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2Frryyi6Fqr036hCIASQ3Z%2FScreenshot%202026-07-01%20at%204.41.48%E2%80%AFPM.png?alt=media&amp;token=fb28a234-51bd-4702-8dd1-a7a16f2699e2" alt=""><figcaption></figcaption></figure>

### What happens during a session

Once launched, the live session opens in the Mozark session runner in a separate window or tab.

Within the runner, you can:

* Interact with the device or browser normally.
* Take screenshots that stay linked to the session.
* File bugs directly from the session runner toolbar.
* End the session when testing is complete.

#### Stream panel actions

Interactions with the stream panel are translated into real device actions.

| Stream panel action | Device action                             |
| ------------------- | ----------------------------------------- |
| Single click or tap | Touch tap at the corresponding coordinate |
| Click and drag      | Swipe gesture along the drag path         |
| Scroll wheel        | Scroll gesture                            |
| Keyboard typing     | Text input on the focused element         |
| Long click and hold | Long press gesture                        |

#### Action toolbar

The toolbar above the video stream contains session controls.

* **Screenshot** captures and downloads a full-resolution screenshot of the current screen.
* **Start Recording** and **Stop Recording** begin or end session video recording.
* **Home**, **Back**, and **Menu** send the corresponding hardware button press to the device.
* **End Session** cleanly terminates the session and releases the device back to the available pool.

Recordings are saved automatically and appear in the session's Downloads section after the session ends.

#### Ending a session

To end a session, click **End Session** in the toolbar or close the browser tab.

The platform marks the session as complete.

It then uploads recordings, logs, and screenshots automatically.

You can access them later from the Session Summary screen.

If a session stays idle longer than the configured timeout, the platform ends it automatically and releases the device.

The default idle timeout is typically 10 minutes.

The portal automatically saves the session recording, screenshots, and filed bugs.

You can review them later from the Sessions list or the Session Details page.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2FC0rmtROdbMOCjgi3dLgr%2FScreenshot%202026-07-01%20at%204.48.14%E2%80%AFPM.png?alt=media&amp;token=4f4cca55-5bf8-45ba-a409-49353c89e94a" alt=""><figcaption></figcaption></figure>


# Overview

Connect Playwright and Appium test suites to Mozark's remote execution infrastructure.

## Automation

Use this section to connect Playwright and Appium test suites to Mozark's remote execution infrastructure.

### Overview

The Automation Testing section includes documentation hubs for two popular open-source frameworks:

* **Playwright** for web automation
* **Appium** for mobile automation

These hubs provide the configuration details your team needs to point existing test suites at Mozark's real-device grid instead of local machines or generic cloud grids.

This includes:

* Hub URLs
* Capability sets
* Authentication requirements
* Quick-start examples

Sessions run through these frameworks appear in **Automation → Sessions**.

From there, you can review, tag, and analyze them alongside interactive sessions.

### Available hubs

* [**Playwright Hub**](/test-infrastructure-documentation/automation/playwright-hub) for browser-based automation on Mozark's grid
* [**Appium Hub**](/test-infrastructure-documentation/automation/appium-hub) for mobile automation on Mozark's real device cloud
* [**Enterprise Testing**](/test-infrastructure-documentation/automation/enterprise-testing) for upcoming enterprise-grade testing features


# Playwright Hub

Connect Playwright test suites to Mozark's browser grid.

## Playwright Hub

Use this page to connect Playwright-based test suites to Mozark's browser grid.

### Overview

Navigate to **Automation → Playwright Testing**.

This page provides the connection details needed for Playwright's remote browser session flow.

### What this page includes

* The Hub URL to use as the WebSocket endpoint for Playwright's `connect` method
* A quick-start example that shows how to adapt an existing Playwright test
* Available browser and OS capabilities supported on the grid
* Authentication requirements for project-level access

Your project token is pre-filled in the provided snippets.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2F17Ftl7ina3fh80JsX4cl%2FScreenshot%202026-07-01%20at%204.57.45%E2%80%AFPM.png?alt=media&amp;token=b0dfabc3-daed-4358-9213-530de47cae21" alt=""><figcaption></figcaption></figure>

### Quick start

Mozark Playwright Testing runs existing Playwright suites in the cloud without local browser setup.

Connect over WebSocket and authenticate with a Bearer token or API key.

Your existing test code stays the same.

For generated connection details, code examples, and CI/CD setup guidance, sign in to [Playwright Testing](https://testinfra.mozark.ai/automation/playwright-testing).

Use that page to get:

* Your project-specific WebSocket hub endpoint
* Authentication headers for the current session
* `playwright.config.ts` connection settings
* Language-specific sample code and run commands

Supported browsers include Chromium, Firefox, and WebKit from the same hub.

### Result

After you configure your tests, sessions created by the suite are ingested automatically.

They appear under the Playwright Testing tab in the **Automation Sessions** list.


# Appium Hub

Connect Appium test suites to Mozark's real device cloud.

## Appium Hub

Use this page to connect Appium-based test suites to Mozark's real device cloud.

### Overview

Navigate to **Automation → Appium Testing**.

This page provides the connection details required for Appium remote execution.

### What this page includes

* The Appium Hub URL to use as the remote WebDriver endpoint
* Required and optional desired capabilities for iOS and Android
* Quick-start code examples in Java and Python
* Instructions for uploading app builds to **Files** and referencing them by file ID in capabilities

### Quick start

For generated connection details and full setup guidance, sign in to [Appium Testing](https://testinfra.mozark.ai/automation/appium-testing).

Use that page to get:

* Your project-specific Appium hub endpoint
* Authentication details for the current session
* Device-specific capabilities for iOS or Android
* Start and stop session examples for API clients

Use the in-product page when you need comprehensive docs, code examples, or CI/CD setup guidance.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2Fows8EtFEwseBoQBa8Y1u%2FScreenshot%202026-07-01%20at%204.59.12%E2%80%AFPM.png?alt=media&amp;token=c9830439-b114-4007-8a32-649da88bf36a" alt=""><figcaption></figcaption></figure>

### Result

After you configure your tests, Appium sessions appear under the Appium Testing tab in the **Automation Sessions** list.


# Enterprise Testing

Advanced enterprise testing features coming soon.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2FNJt2mgyuqBr0p7FivVrI%2FScreenshot%202026-07-01%20at%204.59.45%E2%80%AFPM.png?alt=media&amp;token=3574751f-48bb-4189-a58f-cdd227fef70a" alt=""><figcaption></figcaption></figure>

## Enterprise Testing

Use this page to track upcoming enterprise-grade testing capabilities.

### Overview

Navigate to **Automation → Enterprise Testing**.

This module is currently reserved for upcoming enterprise testing features.

At this stage, the page shows a coming-soon placeholder.

### Upgrade path

If you want access to advanced enterprise testing options, book a meeting to discuss a plan upgrade.

This path is intended for teams evaluating expanded enterprise coverage and support.


# Overview

Upload, organize, and share app builds, test data, and other testing artifacts.

## File Management

Use this page to upload, organize, and share app builds, test data, and other artifacts used in testing.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2Fs4qLK6jVX356oMG4iupI%2FScreenshot%202026-07-01%20at%205.44.06%E2%80%AFPM.png?alt=media&amp;token=9f006277-e354-4ae3-be2b-9e455776be45" alt=""><figcaption></figcaption></figure>

### Accessing File Management

Navigate to **File Management** in the sidebar.

Files are scoped to the currently selected organization, app, and project.

Confirm that your working context is correct before uploading.

### Uploading a file

1. Click **Upload File** at the top-right of the page.
2. In the upload dialog, click **Choose File** or drag a file into the upload area.
3. Optionally, add metadata as key-value pairs.
4. Click **Upload**.

Use metadata to capture context such as version, environment, or test suite association.

Examples:

* `version: 2.4.1`
* `environment: staging`
* `suite: smoke-tests`

For large files, the portal shows upload progress.

Some file types require a short server-side processing step.

This appears as a **Re-signing** status and usually completes within a few minutes.

{% hint style="warning" %}
Do not close the upload dialog while a file is uploading.

Closing the dialog cancels the transfer.

If re-signing continues after the dialog closes, the portal keeps polling for status updates in the background for up to five minutes and refreshes the list automatically.
{% endhint %}

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2FtxBbJbkJEuH0katqAMXM%2FScreenshot%202026-07-01%20at%205.44.27%E2%80%AFPM.png?alt=media&amp;token=33bb238d-0df7-4c98-aaba-a367767fc64c" alt=""><figcaption></figcaption></figure>

### File table columns

| Column          | Description                                              |
| --------------- | -------------------------------------------------------- |
| **Name**        | Original filename as uploaded.                           |
| **Path**        | Storage path inside Mozark's file store.                 |
| **Status**      | Current file state, such as `Available` or `Re-signing`. |
| **Size**        | File size in KB, MB, or GB.                              |
| **Uploaded**    | Timestamp when the file was uploaded.                    |
| **Uploaded By** | Email of the team member who uploaded the file.          |
| **Actions**     | Download and delete actions.                             |

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2FEy33WwV6wYyCj3qCvRf9%2FScreenshot%202026-07-01%20at%205.44.48%E2%80%AFPM.png?alt=media&amp;token=dda5e160-8d63-4e54-80b2-3f4f51ff8d1f" alt="" width="375"><figcaption></figcaption></figure>

### Viewing file details

Click any file row to open the File Detail Panel.

The panel slides in from the right side of the screen.

It shows full file information, including metadata, MIME type, and a download button.

You can also edit metadata from this panel without re-uploading the file.

### Downloading a file

Download a file in either of these ways:

* Click the download icon in the **Actions** column
* Click **Download** in the File Detail Panel

The file is fetched securely and saved to your browser's default download location.

### Deleting a file

Delete a file in either of these ways:

* Click the delete icon in the **Actions** column
* Click **Delete** in the File Detail Panel

The portal asks for confirmation before deleting the file.

Click **Delete** to confirm or **Cancel** to keep the file.

{% hint style="warning" %}
Deletion is permanent.

There is no recycle bin or undo.

If an Appium test suite references a deleted file in its capabilities, those runs will fail.

Coordinate with your team before deleting shared builds.
{% endhint %}

### Column visibility

Click **Columns** at the top-right of the table to show or hide columns.

This works the same way as the Sessions view.


# Overview

Find, filter, and review interactive and automation sessions.

## Sessions

Use this section to manage and review session data across interactive and automation workflows.

### In this section

* [Session Management](/test-infrastructure-documentation/sessions/session-management) — Search, filter, and organize session history.
* [Session Details](/test-infrastructure-documentation/sessions/session-details) — Review session metadata, recordings, screenshots, bugs, notes, and artifacts.

### When to use this section

Use **Session Management** to locate sessions quickly.

Use **Session Details** to inspect the full output of one session.


# Session Details

Inspect session metadata, video, screenshots, bugs, notes, and output artifacts.

## Session Details

Use this page to review the full record of an interactive or automation session.

### Opening Session Details

In the Sessions list, click any session row outside the inline-editable cells.

The portal opens the Session Details page in a new browser tab.

Interactive session URLs follow this pattern:

`/interactive/session-summary/{platform}/{sessionId}`

Automation session URLs follow this pattern:

`/automation/session-summary/{platform}/{sessionId}`

You can bookmark or share direct links to specific sessions.

### Session meta card

The top of the page shows the Session Meta Card.

It summarizes the session at a glance:

* Session name, which you can edit
* Platform, such as Web, Mobile, TV, or the automation framework name
* Configuration, including OS and browser or the selected device
* Start time and duration
* Status badge, such as `Passed`, `Failed`, or `Stopped`
* User who ran the session

### The five tabs

Below the meta card, the page shows five tabs.

The **Bugs** tab is active by default.

#### Bugs tab

The **Bugs** tab lists all bugs filed during or after the session.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2FkPtHeSsXWXiRW96LRFIG%2FScreenshot%202026-07-01%20at%205.43.05%E2%80%AFPM.png?alt=media&amp;token=450009ea-f35e-496c-b9c2-422650b4579b" alt=""><figcaption></figcaption></figure>

Each bug includes:

* Issue key
* Title
* Status badge
* Priority badge
* Platform
* Creator

**Filing a new bug**

Click **+ Add Bug** at the top-right of the **Bugs** tab.

The dialog includes these fields:

| Field                 | Required | Description                                                                    |
| --------------------- | -------- | ------------------------------------------------------------------------------ |
| **Issue Key**         | Yes      | Unique bug identifier, such as `BUG-101`. This is usually auto-generated.      |
| **Title**             | Yes      | Short summary of the defect.                                                   |
| **Description**       | Yes      | Reproduction steps and expected versus actual behavior.                        |
| **Status**            | No       | `Open`, `In Progress`, `Resolved`, `Closed`, or `Reopened`. Default is `Open`. |
| **Priority**          | No       | `Low`, `Medium`, `High`, or `Critical`.                                        |
| **Labels**            | No       | Free-form tags for categorization.                                             |
| **Platform / Device** | No       | Pre-filled from the session configuration.                                     |

#### Screenshots tab

The **Screenshots** tab shows all screenshots captured during the session in a grid gallery.

Each screenshot shows a thumbnail and the timestamp when it was taken.

Click a thumbnail to open the full-size image.

You can download screenshots individually.

Screenshots stay linked to the session and platform automatically.

You cannot upload additional screenshots here.

Screenshots are created only during live sessions.

#### Video tab

The **Video** tab shows the full session recording in a video player.

Key behaviors:

* The recording starts when the session launches.
* Timeline markers appear on the scrubber for screenshots and filed bugs.
* Hover over a marker to inspect it and jump to that point.
* If processing is still in progress, the tab shows a message until the recording is ready.

Recordings usually appear within a few minutes after the session ends.

{% hint style="warning" %}
Video availability depends on session type.

Not every session includes a recording.

The `hasVideo` flag determines whether the tab shows a player or a **No recording available** message.
{% endhint %}

#### Notes tab

The **Notes** tab stores free-form text entries attached to the session.

Use notes for observations, hypotheses, or summaries that do not need a formal bug.

**Creating a note**

1. Click **+ Add Note**.
2. Enter a title.
3. Enter the note content in the rich text editor.
4. Click **Save**.

The note appears in the list with your name and timestamp.

Basic formatting such as bold, italic, and lists is supported.

Notes can be edited or deleted by the person who created them.

To edit a note, open it and update the content.

To delete a note, use the delete icon on the note card.

#### Session artifacts tab

The **Session Artifacts** tab lists output files generated by the session.

Examples include log files, HAR files, and other diagnostic outputs from the test runner.

You can download each artifact directly.

This tab is most useful for automation sessions that produce structured output files.


# Session Management

Find, search, filter, and organize your test sessions.

## Session Management

Use this page to find, search, filter, and organize your test sessions.

### Accessing the Sessions list

You can open the Sessions list from two places, depending on the session type:

* **Interactive → Sessions** shows sessions from manual interactive testing across Web, Mobile, and TV.
* **Automation → Sessions** shows sessions from automation frameworks such as Playwright and Appium.

Both pages use the same layout.

A tab bar at the top lets you switch between platforms or frameworks without leaving the page.

### Understanding the session table

Each row in the table represents one test session.

The default columns are:

| Column         | Description                                                                                                                         |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Build Name** | Display name of the session. You can rename it inline.                                                                              |
| **Start Time** | Time the session started, shown in your local timezone.                                                                             |
| **Duration**   | Total session length.                                                                                                               |
| **Status**     | Session outcome, such as `Passed`, `Failed`, or `Stopped`.                                                                          |
| **Config**     | Primary and secondary configuration. For web sessions, this is OS and browser. For mobile and TV sessions, this is the device name. |
| **Tags**       | Labels attached to the session. You can add or remove them inline.                                                                  |
| **User**       | Email address of the person who ran the session.                                                                                    |
| **Actions**    | Quick access to Video, Screenshots, Bugs, and Notes without leaving the list.                                                       |

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2Fusnh3sr6gfjsiICLzVkM%2FScreenshot%202026-07-01%20at%205.37.36%E2%80%AFPM.png?alt=media&amp;token=5c5de585-4e44-4a45-bd54-ed287be50530" alt=""><figcaption></figcaption></figure>

### Inline editing

You can rename a session and manage its tags directly from the list.

To rename a session, click the name cell to enter edit mode.

Press `Enter` or click outside the field to save.

To manage tags, click the tags cell to open the tag picker.

From there, assign existing tags or type to create a new one.

### Searching sessions

The search bar at the top-right of the Sessions list supports two modes.

Use the toggle next to the input field to switch between them.

#### Plain text search

Type any word or phrase.

The portal matches it against the session name, session ID, start time, status, configuration, user email, and tags.

Use this mode when you remember any identifying detail.

#### JQL search

Use JQL mode for precise filtering.

Queries follow the format `field = "value"`.

Combine multiple conditions with `AND`.

Examples:

| Query                                              | Result                            |
| -------------------------------------------------- | --------------------------------- |
| `status = "failed"`                                | All sessions with status `Failed` |
| `user = "alice@example.com"`                       | Sessions run by a specific user   |
| `status = "failed" AND user = "alice@example.com"` | Failed sessions run by that user  |

### Filtering sessions

Click **Filter** to open the filter panel.

Filters are grouped by:

* Status
* User
* OS
* Browser
* Device
* Resolution
* Build Name
* Tags

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2F0FbRXJvAs14n3MWyXtYB%2FScreenshot%202026-07-01%20at%205.39.43%E2%80%AFPM.png?alt=media&amp;token=2c3536f5-d44f-4a0a-82ca-f00733684a95" alt="" width="375"><figcaption></figcaption></figure>

You can select multiple values within one group.

Within the same group, filtering works as `OR`.

Across different groups, filtering works as `AND`.

Active tag filters appear as blue chips below the toolbar.

Click **Filter** again to adjust or clear them.

### Controlling column visibility

Click **Columns** next to **Filter** to choose which columns appear in the table.

The Session ID column is hidden by default to reduce clutter.

Enable it when you need to copy session IDs.

### Pagination

The table loads 20 sessions per page by default.

Use the controls at the bottom of the table to move between pages.

You can also change the page size to `10`, `20`, `50`, or `100`.

{% hint style="info" %}
Search and filter apply only to the data loaded on the current page.

If you need older sessions, paginate first, then search.

You can also reduce the page size to keep recent sessions on the first page.
{% endhint %}

### Quick-access modals

The **Actions** column includes four icon buttons that open lightweight modals without leaving the Sessions list.

Use them to quickly review session evidence:

* **Video** opens an in-place video player for the full recording.
* **Screenshots** opens a gallery of captured screenshots.
* **Bugs** lists bugs filed during the session.
* **Notes** displays session notes.

For deeper analysis, click anywhere on a session row outside the **Actions** column.

The portal opens the full [Session Details](/test-infrastructure-documentation/sessions/session-details) page in a new browser tab.


# UI and Navigation Behavior

Understand themes, notifications, navigation patterns, and shared UI behavior across the portal.

## UI and Navigation Behavior

Use this page to understand how the portal behaves across navigation, notifications, errors, and themes.

### Light and dark mode

The portal supports both light and dark themes.

Click the sun or moon icon in the top navigation bar to switch themes.

Your preference is saved in browser local storage.

It persists across sessions and page refreshes.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2FEpfY0FOGIembDZ1n9gIR%2FScreenshot%202026-07-02%20at%2012.05.17%E2%80%AFPM.png?alt=media&amp;token=eeff6dbf-45cc-48c8-8141-f15400684ed1" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2FTjcA2bZPipIfwwjJUZlS%2FScreenshot%202026-07-02%20at%2012.05.22%E2%80%AFPM.png?alt=media&amp;token=f4176677-1aa3-4b3d-8a06-6d10d0efe840" alt=""><figcaption></figcaption></figure>

### Toast notifications

The portal uses toast notifications to show the outcome of actions.

Toasts appear near the bottom center of the screen.

They disappear automatically.

You do not need to dismiss them.

| Toast type  | What it signals                                                  | Example                                              |
| ----------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
| **Success** | The action completed successfully.                               | `File deleted.` or `Note saved.`                     |
| **Error**   | The action failed, usually because of a server or network issue. | `Failed to load sessions.` or `Download failed.`     |
| **Warning** | The action cannot continue because a required step is missing.   | `Please select OS, browser, version and resolution.` |

### Loading states

When the portal fetches data from the backend, it shows a centered spinner in the main content area.

The spinner includes a descriptive label such as `Loading Sessions` or `Loading session details`.

This prevents partial UI states from appearing while data is still loading.

### Breadcrumbs

Every page shows a breadcrumb trail at the top of the main content area.

Each segment is clickable and takes you back up the navigation hierarchy.

The last segment represents the current page.

It appears as plain text, not a link.

Example:

`Interactive → Sessions → Session Summary`

Selecting **Sessions** returns you to the sessions list for the same platform.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2FhfkvY5uinJ6zcXB5G6S9%2FScreenshot%202026-07-02%20at%2012.04.29%E2%80%AFPM.png?alt=media&amp;token=05078856-d5da-46fd-bd40-7e8aeab3eaf4" alt=""><figcaption></figcaption></figure>

### Table behavior

The portal uses different table behaviors depending on the page:

* Session lists use server-side pagination.
* Smaller lists such as files use client-side pagination.
* Clicking a row in the Sessions table opens Session Details in a new browser tab.
* Clicking a row in the Files table opens the File Detail Panel inline.
* Column resizing is not currently supported.

Opening session rows in a new tab makes it easier to compare multiple sessions without losing the list.

### Sidebar collapse

Click the collapse arrow at the bottom of the sidebar to switch to icon-only mode.

In this mode, only icons remain visible.

Hover over an icon to see its label in a tooltip.

Click the expand arrow to restore full labels.

This setting persists for the current session.

It resets on page reload.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2F1tAronHeWfDq9duSnaXQ%2FScreenshot%202026-07-02%20at%2012.06.28%E2%80%AFPM.png?alt=media&amp;token=9b564081-77bb-401b-96d8-93de9419137c" alt=""><figcaption></figcaption></figure>

### External links

**Dashboard** and **Test Case Repository** in the sidebar are external links.

They open in a new browser tab.

They do not navigate within the Testing Portal.

These links point to other Mozark products in the broader quality management suite.


# Permissions and Security

Understand authentication, access control, data isolation, and token handling across the portal.

## Permissions and Security

Use this page to understand how access is controlled, how data is isolated, and how credentials are protected.

### Authentication

The portal uses Single Sign-On through Mozark's central identity service at `auth.mozark.ai`.

There are no separate Testing Portal passwords.

Your organization's IT or security team manages credentials at the identity provider level.

Your authentication token is a signed JWT stored in browser local storage.

It includes your user ID, email, role, and expiry time.

The portal validates this token on every action.

If the token expires, the portal redirects you to the sign-in page.

If you remain active, tokens refresh automatically in the background.

The portal applies a 30-second buffer before token expiry to reduce failures during slow operations.

### Multi-tab and multi-device behavior

Mozark uses `BroadcastChannel` to synchronize authentication state across open tabs in the same browser.

This means:

* Signing out in one tab signs you out in all open tabs in that browser.
* Signing in or re-authenticating updates all open tabs in that browser.
* Different browsers and different devices remain independent sessions.

Signing out on one computer does not sign you out on another.

### Data isolation

Sessions, bugs, notes, and files are scoped to the active organization and project at the time they are created.

You cannot view data from another organization unless your current context grants access to it.

If you belong to multiple organizations, switching context immediately re-scopes the data shown in the portal.

### Role-based access

User roles are managed in the Mozark Admin Control Panel, not in the Testing Portal.

The portal enforces the permissions assigned to your account.

If you cannot see a project, launch a session, or access a module, contact your Mozark account administrator.

They can review your project membership and role assignment.

### API authentication

API requests from the Testing Portal to backend services include your JWT in the `Authorization: Bearer` header.

This is handled automatically during normal portal use.

You do not need to manage API keys for standard UI access.

If you integrate external tools such as Playwright or Appium, use the project-specific credentials shown on the automation hub pages.

### Admin Portal

Organization and project management happens in the Admin Portal.

This includes adding users, creating projects, and managing app configurations.

Open it from **Admin Settings** in the user menu in the top navigation bar.

The Admin Portal opens in a new browser tab.

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2Fn0hBTVNy5TslNMcmW6MZ%2FScreenshot%202026-07-02%20at%2012.08.43%E2%80%AFPM.png?alt=media&amp;token=40f597ea-33d4-4386-a192-1cfe520a03d3" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2123087174-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLMVfKLs2Tk5G2AJukEBS%2Fuploads%2Fg1TIVUKAe2ZHVdN04lOp%2FScreenshot%202026-07-02%20at%2012.08.57%E2%80%AFPM.png?alt=media&amp;token=6b8dcd76-35b4-4c04-9011-ee7a9cf452fc" alt=""><figcaption></figcaption></figure>


# Known Limitations and Edge Cases

Review current constraints and release-specific behaviors across sessions, files, and shared UI.

## Known Limitations and Edge Cases

Use this page to review current constraints and behaviors in this release.

{% hint style="info" %}
These items are known in the current release.

They are expected to improve in future versions.

Check release notes for updates.
{% endhint %}

### Session and testing

* **One Interact session at a time** The Optics AI **Interact** page supports only one active AI session per user.

  End the current session before starting another.
* **Device availability reflects real hardware state** Devices appear as unavailable when they are powered off, unplugged, or experiencing a hardware fault.

  Controllers poll device reachability continuously.

  A device is marked unavailable only after three failed reachability samples to reduce false alarms from brief connectivity issues.
* **Session redirect timing** After you click **Launch** on a Web, Mobile, or TV selection page, the portal redirects you to the live session runner.

  On slower connections, this can take a few seconds.

  Do not click **Launch** more than once.

  Repeating the action can allocate multiple sessions.
* **Stream startup time** Interactive sessions can take two to eight seconds to initialize video streaming.

  During this window, the video panel can show a connecting state while the controller starts the streaming pipeline and establishes the session.
* **Video processing delay** Session recordings are not available immediately after a session ends.

  Processing usually completes within one to three minutes.

  Refresh the Session Details page after that window to check for the video.
* **Video recording length depends on controller storage** Long-running sessions depend on available disk space on the controller machine.

  The platform checks minimum free space before starting new sessions.

  If storage is too low, new session requests can be rejected.
* **Search scope on the Sessions list** Plain text search and JQL search apply only to the currently loaded page of data.

  To search across a larger set, increase the page size to the maximum value before searching.
* **TV session routing** TV sessions use a different infrastructure path than web and mobile sessions.

  If TV sessions fail to launch, the issue can be limited to TV device capacity rather than the wider platform.
* **Smart TV interactions are key-based** TV sessions support key events such as D-pad, media keys, and number keys.

  Coordinate-based touch input does not apply to TV devices.

  Test flows and scripts should use key-event interactions.

### Automation and scheduling

* **iOS app installation requires device-specific signing** IPA files must be signed for the target device UDID.

  An IPA signed for a different device will fail to install.

  Make sure provisioning profiles include the UDIDs for target devices.
* **Browser session concurrency is limited per controller** Each controller machine supports a configurable maximum number of concurrent browser sessions.

  The default limit is typically four.

  Additional sessions wait in a queue until capacity is available.
* **Scheduled tests are not exact to the second** Scheduled runs usually start within about `±60 seconds` of the configured time.

  Timing depends on the scheduler polling interval.

  If a device is busy at the scheduled start time, the test waits until the device becomes free, up to the configured wait timeout.

### File Management

* **No multi-file upload** Upload files one at a time.

  Batch upload is not currently supported.
* **Re-signing delay** Some file types require a server-side re-signing step after upload.

  During this time, the file status shows as `Re-signing`.

  This step can take up to five minutes.

  The file is not available for download until it completes.
* **Permanent deletion** Deleted files cannot be recovered.

  There is no end-user recycle bin or soft-delete flow.

### UI and navigation

* **Sidebar collapse resets on reload** Sidebar collapse state persists only for the current session.

  It resets on page reload.
* **Desktop-first layout** The portal is designed for desktop screens, especially widths of `1280px` and above.

  Tablet landscape mode is usable, but session launch pages and Optics AI canvases work best on a full desktop display.
* **Internet Explorer is not supported** The portal depends on modern browser APIs such as `WebSocket`, `BroadcastChannel`, `Canvas`, and `crypto.randomUUID`.

  These APIs are not available in Internet Explorer or legacy Edge.


# Best Practices

Follow recommended patterns for naming, tagging, filing bugs, using AI, managing files, and reviewing sessions.

## Best Practices

Use this page to follow recommended patterns for getting the most out of the Testing Portal.

### Organizing your work

* **Verify project context before starting** Check **Organization → App → Project** in the top navigation bar before launching sessions or uploading files.

  This quick check prevents data from being saved in the wrong place.
* **Name sessions clearly** Rename sessions as soon as they appear in the Sessions list.

  Good names include the feature, build version, and date.

  Example: `Checkout Flow – v2.4.1 – Regression`
* **Use tags consistently** Agree on a tagging taxonomy with your team.

  Examples include `smoke`, `regression`, `release-2.5`, and `priority-critical`.

  Consistent tags make filtering and historical search much easier.

### Bug filing

* **File bugs from within the session** The session runner captures context and links the current screenshot automatically.

  Filing later is possible, but it loses that automatic screenshot association.
* **Use priority and status consistently** Align on shared definitions with your team.

  A practical model is:

  * `Critical` blocks release
  * `High` breaks a core flow
  * `Medium` affects a secondary flow
  * `Low` is cosmetic or minor
* **Include reproduction steps** Always include preconditions, steps to reproduce, expected result, and actual result.

  This makes bugs faster to validate and fix.

### Using Optics AI effectively

* **Use Interact for targeted flows** Interact works best when you already know the flow you want to test.

  Write commands the way you would explain the task to a teammate.
* **Use Explorer for broad discovery** Explorer is a good first pass on a new build.

  Use it to identify broken paths before writing more detailed tests.
* **Start Explorer with low concurrency** Begin with `Concurrent = 2` on a new application.

  This helps you observe behavior before scaling up.

  Some applications rate-limit or block rapid parallel access.
* **Store credentials in Secrets, not Parameters** Parameters can appear in logs and reports.

  Secrets stay masked.

  Use Secrets for all credential values, including staging.

### File Management

* **Add metadata to every uploaded file** At minimum, include version, environment, and platform.

  Examples: `version`, `environment`, `platform`.
* **Do not delete files used by active suites** Check your Appium or Playwright configurations before deleting a file.

  Deleting a referenced file can break CI runs.

### Session reviews

* **Use quick-access modals for triage** Use **Video**, **Screenshots**, and **Bugs** from the Sessions list to review evidence quickly.

  Open full Session Details only when you need deeper context.
* **Use JQL for targeted reports** JQL is faster than manual scanning when you need precise session sets.

  Example: `status = "failed" AND user = "qa@example.com"`
* **Add notes immediately after sessions** Notes capture context while it is still fresh.

  Even short notes help preserve useful history.

### General tips

* Keep the Testing Portal in its own dedicated browser tab or window.
* Bookmark the Sessions list for your most-used project.
* Use **Admin Settings** in the user menu when expected data is missing and you need to verify project membership.


# Troubleshooting & FAQs

Resolve common issues with login, sessions, devices, files, and scheduled tests.

## Troubleshooting & FAQs

Use this page to resolve common issues with login, sessions, devices, files, and scheduled tests.

### Login and access

<details>

<summary>I click Login but nothing happens, or I keep getting redirected back to the login page.</summary>

This usually means the SSO session expired or the browser is blocking cookies needed for the redirect.

Try these steps:

1. Clear cookies for the portal domain and `auth.mozark.ai`.
2. Allow cookies for Mozark domains.
3. Try an incognito or private window.
4. Disable extensions that could block redirects.

If the issue continues, contact your IT administrator.

Your account could be locked, or your organization's SSO configuration could need attention.

</details>

<details>

<summary>I cannot log in and see an invalid credentials error.</summary>

Verify that you are using the email address your account was created with.

Do not use an alias unless it is the primary account email.

If you recently changed your password, use the new one.

If the issue continues, use the password reset flow or contact your administrator.

</details>

<details>

<summary>I can log in, but I do not see any projects in the selector.</summary>

Your account may not be assigned to any projects.

Ask your Mozark account administrator to confirm your organization, app, and project membership.

</details>

### Sessions and devices

<details>

<summary>I cannot see any devices in the device list.</summary>

Your account may not be assigned to any projects, or no devices may be assigned to those projects.

Ask your platform administrator to verify both project membership and device assignment.

</details>

<details>

<summary>I launched a web session, but I was not redirected anywhere.</summary>

This usually means the platform could not allocate capacity or a network error interrupted the launch.

Check for an error toast.

If you see a launch failure, wait a few minutes and try again.

If the problem continues, contact support.

</details>

<details>

<summary>The live video stream is stuck or keeps showing a loading spinner.</summary>

Try these steps:

1. Refresh the page.
2. Check the browser console for WebRTC errors.
3. Verify that your firewall or VPN is not blocking WebRTC or KVS WebSocket traffic.
4. Try Chrome or Edge.

If the issue continues, the controller for that device could be offline.

Contact your platform administrator.

</details>

<details>

<summary>My interaction taps are landing in the wrong position on the device.</summary>

Set browser zoom to `100%`, then refresh the session.

Use `Ctrl+0` on Windows or `Cmd+0` on macOS.

Tap calibration depends on the rendered video frame size matching the displayed size.

</details>

<details>

<summary>My automated test failed immediately with a device not found or ADB error.</summary>

The device may have disconnected after selection but before the test started.

Check the device status in **Management → Devices**.

If it shows unavailable, there is likely a controller-side connectivity issue.

</details>

<details>

<summary>My session ended unexpectedly.</summary>

Sessions can end automatically because of idle timeout or maximum session duration.

Idle timeout is typically 10 minutes.

Check the Session Details page for the end reason.

If there is no timeout-related reason, the device may have gone unavailable during the session.

</details>

<details>

<summary>My session does not appear in the Sessions list.</summary>

Verify that the current **Organization → App → Project** matches the context used when the session was launched.

Also confirm that you are on the correct session tab, such as Web, Mobile, TV, or the relevant automation framework.

</details>

<details>

<summary>The session summary shows no results for my test.</summary>

Clear active filters and confirm you are in the correct project.

Then search by the test ID shown in the launch confirmation.

Date filters can also hide expected results.

</details>

<details>

<summary>The Video tab shows no recording available for a session that should have been recorded.</summary>

Wait one to three minutes after the session ends, then refresh the page.

If the recording is still missing after 10 minutes, the session may not have generated one.

Some session types do not guarantee recordings.

</details>

<details>

<summary>I cannot edit the session name or tags.</summary>

Edit session names and tags from the Sessions list.

Use the inline controls in the name and tags cells.

The Session Details page does not support those edits.

</details>

### File Management

<details>

<summary>I uploaded a file, but it does not appear in the test configuration dropdown.</summary>

Files are scoped to a project and framework.

Verify that the file was uploaded to the correct project and matches the selected framework type.

</details>

<details>

<summary>My file upload failed midway.</summary>

Check your internet connection and try again.

Large uploads need a stable connection for the full transfer.

If uploads fail consistently at a similar size, contact support to confirm whether a plan-specific upload limit applies.

</details>

<details>

<summary>The file I uploaded still shows re-signing after more than 10 minutes.</summary>

Refresh the file list first.

If the status does not change, delete the file and upload it again.

If the issue repeats, contact Mozark support.

</details>

### Scheduling

<details>

<summary>My scheduled test did not run at the configured time.</summary>

Check **Management → Jobs** to confirm that a job was created.

If no job appears, the schedule may be paused.

If the job exists but failed, open its details to review the failure reason, such as device unavailable or build not found.

</details>


# Test Context Manager

Centralized test management for planning, execution, traceability, and reporting.

Test Context Manager gives QA teams a single place to plan, run, and track their testing work. Use it to connect test design, execution, defect tracking, traceability, and reporting across every release.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FETSPXP3FxEP38H2y0rBp%2FScreenshot%202026-07-02%20at%2012.18.21%E2%80%AFPM.png?alt=media&amp;token=3d069ec6-0266-4167-aa31-4b68685059de" alt=""><figcaption></figcaption></figure>

### What you can do

* Create and organize test cases, plans, and runs
* Capture results, evidence, comments, and linked bugs
* Measure coverage, progress, and quality across projects

### How the workflow works

1. Test cases define the scenarios you need to validate.
2. Test plans organize execution scope for a release or cycle.
3. Test runs record outcomes, evidence, bugs, and progress.

### Explore Test Context Manager

**Start here**

* Getting started — set up your workspace and complete your first workflow

**Plan and execute**

* Test cases — design, structure, and manage reusable test coverage
* Test plans — prepare scope and execution for each cycle
* Test runs — execute tests and capture step-level results

**Track and improve**

* Bug tracking — log, link, and follow defects through resolution
* Requirements — map requirements to tests and coverage
* Reports and analytics — review quality metrics, trends, and outcomes
* Integrations — connect external systems such as JIRA


# Overview

Start using Test Context Manager with a new account, starter data, and core navigation.

This section walks you through the essentials: signing in, exploring your starter workspace, and completing your first workflow.

#### What's included

* [Sign up and first login](https://app.gitbook.com/o/Hqnn1kUFC3MfzBNYRUTL/s/IgQEgtjvk4zIWyVkgQ5o/getting-started/overview/sign-up-and-first-login)
* [Your starter workspace](https://app.gitbook.com/o/Hqnn1kUFC3MfzBNYRUTL/s/IgQEgtjvk4zIWyVkgQ5o/getting-started/overview/your-starter-workspace)
* [Basic navigation](https://app.gitbook.com/o/Hqnn1kUFC3MfzBNYRUTL/s/IgQEgtjvk4zIWyVkgQ5o/getting-started/overview/basic-navigation)
* [Create your first workflow](https://app.gitbook.com/o/Hqnn1kUFC3MfzBNYRUTL/s/IgQEgtjvk4zIWyVkgQ5o/getting-started/create-your-first-workflow)

#### What to expect

By the end of this section, you'll be able to move through the core workflow with confidence.

Already familiar with the basics and want to jump straight in? Start here:

* [Creating a test case](https://app.gitbook.com/o/Hqnn1kUFC3MfzBNYRUTL/s/IgQEgtjvk4zIWyVkgQ5o/test-cases/creating-a-test-case)
* [Creating a test plan](https://app.gitbook.com/o/Hqnn1kUFC3MfzBNYRUTL/s/IgQEgtjvk4zIWyVkgQ5o/test-plans/creating-a-test-plan)
* [Creating a test run](https://app.gitbook.com/o/Hqnn1kUFC3MfzBNYRUTL/s/IgQEgtjvk4zIWyVkgQ5o/test-runs/creating-a-test-run)


# Your starter workspace

Understand the default organization, app, project, and sample data created for new users.

When you first enter Test Context Manager, your workspace is ready to use — no setup required.

### What's included

Test Context Manager automatically creates:

* A default organization
* A default app
* A default project

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FncRSAVxcKuISQY7YU2el%2FScreenshot%202026-07-01%20at%201.30.17%E2%80%AFPM.png?alt=media&amp;token=89baa99c-226b-4552-9b3f-04905acd3a62" alt="" width="322"><figcaption></figcaption></figure>

You can rename any of these later in the **Administration Portal** by clicking on **Edit Profile.**

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FWxVYHEOEOBOR7R7YHzRG%2FScreenshot%202026-07-15%20at%202.45.41%E2%80%AFPM.png?alt=media&amp;token=7f4a8624-1224-46fa-98a0-a832d0d75780" alt=""><figcaption></figcaption></figure>

Test Context Manager also pre-seeds sample data so you can explore the product right away. Starter data includes:

* Requirements
* Test cases
* Test plans
* Test runs
* Reports

Use this sample data to learn the workflow before adding your own project data.

#### Verify your workspace

To confirm everything is set up correctly:

1. Open the main product areas and check that the sample records are visible.
2. Confirm the default organization, app, and project appear in your workspace.

If the starter data is present, you're ready to explore the workflow.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FNK8osz58MpY4Ye0ISrYP%2FScreenshot%202026-07-01%20at%201.31.52%E2%80%AFPM.png?alt=media&amp;token=1c9b66a5-bf0f-4cf3-b668-145a048f2b89" alt=""><figcaption></figcaption></figure>


# Basic navigation

Find the main areas of Test Context Manager and move between core workflows.

Test Context Manager uses the left sidebar to organize your workflows and give you quick access to every major area.

#### Sidebar

Use the left sidebar to move between the main areas of the product. Common entry points include:

* Test Cases
* Test Plans
* Test Runs
* Requirements
* Bugs
* Reports

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2F5XSfDo9WpX9Far2BeQxR%2FScreenshot%202026-07-01%20at%201.37.10%E2%80%AFPM.png?alt=media&amp;token=90dc0154-6210-40e7-a66d-e77e793bbeab" alt=""><figcaption></figcaption></figure>

### For You page

The **For You** page is your default project overview. It gives you a quick view of repository health, runs, bugs, and coverage at a glance.

See [For You dashboard](/test-context-manager-documentation/reports-and-analytics/generating-a-report/for-you-dashboard) for details.


# Sign up and first login

Create your account, verify your email, and sign in for the first time.

#### Create an account

1. Open the sign-up page on <https://testcontext.mozark.ai&#x20>;
2. Enter your email address.
3. Enter a password.
4. Confirm the password.
5. Click **Sign up**.

Your password must:

* Be at least 8 characters long
* Include uppercase and lowercase letters
* Include a number
* Include a special character

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2F1LnWafWYzTOPYEuaAH2V%2FScreenshot%202026-07-01%20at%201.23.40%E2%80%AFPM.png?alt=media&amp;token=2be2f34c-9386-437c-b94d-3516b47ef135" alt=""><figcaption></figcaption></figure>

#### Verify your account

After sign-up, Test Context Manager sends a confirmation code to your email. Enter the code to verify your account.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FlKrarynDbgcxXeSApBCo%2FScreenshot%202026-07-01%20at%201.24.01%E2%80%AFPM.png?alt=media&amp;token=9fb8d798-324d-4a92-8abb-be8e13b1c1dc" alt=""><figcaption></figcaption></figure>

#### Sign in

Once your account is verified, you can sign in. You can also sign in with:

* Google
* Microsoft

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FX4eNS6v5YiiFCjfAl1Ia%2FScreenshot%202026-07-01%20at%201.24.25%E2%80%AFPM.png?alt=media&amp;token=cba73730-0edc-4e2f-a0ea-7e0666738887" alt=""><figcaption></figcaption></figure>

#### Verify setup

Confirm that:

1. You can sign in successfully after verification.
2. The default workspace opens without errors.

If sign-in succeeds and the workspace loads, your setup is complete.


# Create your first workflow

Create your first test case, plan, and run in Test Context Manager.

## Create your first workflow

Use this workflow to understand how Test Context Manager connects planning and execution.

A simple first workflow looks like this:

1. Create a test case.
2. Add the test case to a test plan.
3. Create a test run from the plan.
4. Execute the test case.
5. Review the results.

Use these pages for the full steps:

* [Creating a test case](/test-context-manager-documentation/test-cases/creating-a-test-case)
* [Creating a test plan](/test-context-manager-documentation/test-plans/creating-a-test-plan)
* [Creating a test run](/test-context-manager-documentation/test-runs/creating-a-test-run)
* [Executing a test case](/test-context-manager-documentation/test-runs/creating-a-test-run/executing-a-test-case)


# Overview

Learn what the Requirements module does in Test Manager.

## Overview

The **Requirements** module helps teams manage specifications.

### What this feature does

Use requirements to define what needs coverage and connect it to testing work.

### What's included

This module helps teams track coverage across test cases and bugs.

Linking requirements to test cases and bugs enables traceability.

This data powers the traceability matrix in reports.

### What's not included

Requirements do not execute tests or store execution results.

Use test runs for execution and reports for aggregated outcomes.


# Creating a requirement

Create a requirement and save its key details.

## Creating a requirement

### Before you start

Make sure you have the requirement title and key details ready.

Add only the information you need for traceability and coverage tracking.

To create a requirement:

1. Open **Requirements**.
2. Click **Create Requirement**.
3. Enter a title.
4. Fill in any additional fields you need.
5. Click **Save**.

The title is required.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FvD9IUwEKr6aJvq8Xd8yB%2FScreenshot%202026-07-01%20at%202.56.30%E2%80%AFPM.png?alt=media&amp;token=dc9884f6-1779-4d82-b683-67f08f7b474d" alt=""><figcaption></figcaption></figure>

### Expected result

The requirement is saved in the active project and is available for linking.

You can now connect it to test cases and bugs.

### Next step

For coverage tracking, continue with [Traceability](/test-context-manager-documentation/requirements/creating-a-requirement/traceability).


# Requirement fields reference

Review the fields available on a requirement.

## Requirement fields reference

| Field               | Description                                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Title               | Short description of the requirement. Required.                                                                          |
| Description         | Full specification text.                                                                                                 |
| Status              | `Draft`, `To Be Reviewed`, `Needs Changes`, `In Review`, `Approved`, `Rejected`, `Implemented`, `Active`, or `Archived`. |
| Priority            | `Low`, `Medium`, `High`, or `Critical`.                                                                                  |
| Type                | `Functional`, `Non-Functional`, or `Business`.                                                                           |
| Owner               | Person accountable for the requirement.                                                                                  |
| Assignees           | Team members working on the requirement.                                                                                 |
| Acceptance Criteria | Text description of what done looks like.                                                                                |
| Parent Requirement  | Link to a parent requirement for hierarchy.                                                                              |
| Labels / Tags       | Classification tags.                                                                                                     |
| Linked Work Items   | Linked JIRA issues or other internal entities.                                                                           |
| Attachments         | Supporting documents.                                                                                                    |

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2F2smHgKsBILfGLoPyfwkN%2FScreenshot%202026-07-01%20at%202.57.12%E2%80%AFPM.png?alt=media&amp;token=7b478175-75f8-42ae-bb6a-343ee66735a0" alt=""><figcaption></figcaption></figure>


# Traceability

Link requirements, test cases, and bugs to measure coverage.

## Traceability

Traceability connects requirements to the test cases that verify them.

It also connects requirements to the bugs found while testing those areas.

To build traceability:

1. Open a requirement detail page.
2. Link the test cases that cover the requirement in **Linked Work Items**.
3. Open a test case detail page.
4. Link the requirements covered by that test case.
5. Open a bug detail page.
6. Link the related test case and requirement.

After these links are in place, the traceability report shows the coverage matrix.

### Coverage status

| Coverage Status | Meaning                                           |
| --------------- | ------------------------------------------------- |
| Covered         | At least one linked, passing test case exists.    |
| Partial         | Linked test cases exist, but not all are passing. |
| Uncovered       | No linked test cases exist for the requirement.   |


# Overview

Learn what test cases are and how to access them in Test Context Manager.

## Overview

Test cases are the core unit in Test Context Manager.

### What this feature does

A test case defines a scenario to verify.

It includes preconditions, steps, and expected results.

### What's included

This area lets you create, organize, search, and maintain test cases in the active project.

It also gives each test case a readable ID and a structured execution format.

### What's not included

Test cases do not group execution into releases or cycles.

Use test plans for execution setup and test runs for actual execution.

### How to access it

To open test cases:

1. Go to the sidebar.
2. Click **Test cases**.

The test case list shows all test cases in the active project.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FkhHvXaRnxkaPxL58n8bO%2FScreenshot%202026-07-01%20at%201.44.26%E2%80%AFPM.png?alt=media&amp;token=c1815bd1-2d83-4475-ad55-86b5dfaaca7d" alt=""><figcaption></figcaption></figure>

From this list, you can:

* sort records
* filter records
* search records
* group records
* choose visible columns

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2Fhb9tNBg5PXK3WxUyk0fu%2FScreenshot%202026-07-01%20at%201.44.43%E2%80%AFPM.png?alt=media&amp;token=3bcec70c-3ba6-43f7-adc3-e5ddce1e95b3" alt=""><figcaption></figcaption></figure>


# Creating a test case

Create a test case and add test steps.

## Creating a test case

### Before you start

Make sure you are in the correct project.

Decide the scenario, test data, and expected result before you begin.

To create a test case:

1. Open the **Test Cases** page.
2. Click **Create** in the top right.
3. Enter a title.
4. Fill in any other fields you need.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FlLpMESsKBCqJZI4VOUrA%2FScreenshot%202026-07-01%20at%201.50.11%E2%80%AFPM.png?alt=media&amp;token=ad86ad89-76b6-4ea2-8a33-44258a3500b1" alt=""><figcaption></figcaption></figure>

5. Click **Add Step** to add a step.
6. Enter **Action**, **Test Data**, and **Expected Result** for each step.
7. Drag rows to reorder steps if needed.
8. Click **Save**.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FbXzTGf1DDy9WqiTcbZX0%2FScreenshot%202026-07-01%20at%201.52.38%E2%80%AFPM.png?alt=media&amp;token=883caf5a-0ce4-44cd-9456-9f022a544d25" alt=""><figcaption></figcaption></figure>

The title is the only required field for the initial save.

After saving, Test Context Manager assigns a readable ID automatically.

Examples include `TC-001` and `TC-002`.

### Expected result

The new test case is saved in the active project with its own ID.

You can open it again, edit its details, and add it to a test plan.

### Next step

To review or refine the saved record, see [Viewing and editing a test case](/test-context-manager-documentation/test-cases/creating-a-test-case/viewing-and-editing-a-test-case).

For bulk creation, use CSV import. See [Importing test cases from CSV](/test-context-manager-documentation/test-cases/creating-a-test-case/importing-test-cases-from-csv).


# Test case fields reference

Review the fields available on a test case.

## Test case fields reference

| Field             | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| Title             | Short description of the scenario. Required.                      |
| Description       | Detailed background or notes.                                     |
| Type              | `Manual`, `Automated`, or `Cucumber`.                             |
| Status            | `Draft`, `Active`, `Ready`, or `Deprecated`.                      |
| Priority          | `Low`, `Medium`, `High`, or `Critical`.                           |
| Estimated Time    | Expected execution duration.                                      |
| Assigned To       | One or more team members responsible for execution.               |
| Owner             | Person accountable for the test case.                             |
| Labels / Tags     | Free-form classification tags.                                    |
| Preconditions     | Conditions that must be true before execution.                    |
| Test Steps        | Numbered steps with `Action`, `Test Data`, and `Expected Result`. |
| Start Date        | Planned start date.                                               |
| Due Date          | Target completion date.                                           |
| Linked Work Items | Linked JIRA issues or internal entities.                          |
| Attachments       | Supporting uploaded files.                                        |
| Folder            | Folder that contains the test case.                               |
| Source            | System value such as `Manual`, `AI_Generated`, or `CSV_Import`.   |

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FzTc4mGUMkse1SZUh4whP%2FScreenshot%202026-07-01%20at%201.55.23%E2%80%AFPM.png?alt=media&amp;token=88446c51-ca83-49ab-b6ca-2cdd0606112b" alt=""><figcaption></figcaption></figure>


# Importing test cases from CSV

Import test cases in bulk from a CSV file.

## Importing test cases from CSV

### Before you start

Make sure your CSV includes a title or name column.

Review the source columns before import so the field mapping is easier to validate.

To import test cases from CSV:

1. Open the **Test Cases** page.
2. Click **Import**.
3. Upload your CSV file.
4. Review the detected field mapping.
5. Adjust any column assignments if needed.
6. Preview the imported rows.
7. Click **Import**.

Successfully parsed rows become test cases.

If the import finds duplicate rows, missing required fields, or blank required values, the preview flags those rows and skips them.

You can still import the valid rows in the same file.

To import skipped rows, fix the formatting issues in the CSV and upload it again.

At minimum, your CSV must include a title or name column.

Imported test cases are marked with `Source = CSV_Import`.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FdmMJZCqlxwdhFflEoLC8%2FScreenshot%202026-07-01%20at%202.14.44%E2%80%AFPM.png?alt=media&amp;token=2146222a-08c0-47cb-8ddc-5bf25ad56c03" alt=""><figcaption></figcaption></figure>

### Verify the import

Confirm that the imported rows appear in the test case list.

Check that the field values mapped correctly and that the records show `Source = CSV_Import`.

If any rows fail, correct the CSV and import again.


# Organizing with folders

Group test cases into a folder hierarchy.

## Organizing with folders

Folders let you group test cases in a navigable hierarchy.

Use folders to keep large repositories structured.

### Create a folder

1. Open the **Test Cases** page.
2. Click the folder icon or **New Folder**.
3. Enter the folder details.
4. Save the folder.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FDs8RWEf8UjF7lmYRDLsV%2FScreenshot%202026-07-01%20at%201.56.56%E2%80%AFPM.png?alt=media&amp;token=6c96612c-da69-41a9-93d3-62a8564a2749" alt=""><figcaption></figcaption></figure>

### Move test cases into a folder

1. Select one or more test cases with the checkboxes.
2. Click **Move to Folder**.
3. Choose the target folder.

### Navigate folders

The folder tree appears in the left panel of the **Test Cases** page.

Click a folder to filter the list.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FKgrZH6DSenq8S9fOppM4%2FScreenshot%202026-07-01%20at%202.08.08%E2%80%AFPM.png?alt=media&amp;token=14598c00-b2ec-40af-82a2-5b9a3ed5d980" alt=""><figcaption></figcaption></figure>

### Rename or delete a folder

Right-click a folder in the tree to rename or delete it.

{% hint style="info" %}
Deleting a folder does not delete its test cases. Test Manager moves them to the root level.
{% endhint %}


# Searching and filtering

Search, filter, group, and customize the test case list.

## Searching and filtering

Use the test case list to find records quickly.

### Plain text search

Type in the search bar above the table.

Search matches against:

* title
* description
* readable ID

### JQL mode

Click the **JQL** toggle to switch to JIRA Query Language mode.

Use JQL for more complex queries.

Examples:

```
status = "Active" AND priority = "High"
labels IN ("regression", "smoke")
```

Autocomplete suggestions appear as you type.

### Filters panel

Click **Filters** to open the filter panel.

You can filter by:

* status
* priority
* type
* assignee
* creator
* source
* date ranges
* labels

You can combine multiple filters.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2Fr1MO4F0RkyPbRjquPagz%2FScreenshot%202026-07-01%20at%202.16.52%E2%80%AFPM.png?alt=media&amp;token=8b843b16-d13e-41e4-842c-a114b3318b4a" alt="" width="332"><figcaption></figcaption></figure>

### Grouping and column visibility

Use **Group By** to organize the table into grouped sections.

Common groupings include ID, status, priority, type, creator, and assignee.

Use the columns icon to show or hide columns.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FerFxxhxb8DIOOaVjGaTh%2FScreenshot%202026-07-01%20at%202.17.41%E2%80%AFPM.png?alt=media&amp;token=64fac75d-9fe8-4b2a-8257-3c350fee374b" alt="" width="272"><figcaption></figcaption></figure>


# Viewing and editing a test case

Open a test case, edit fields, and review comments and history.

## Viewing and editing a test case

Click any row in the test case list to open the detail page.

The detail page includes three tabs.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2Fgjsv9bwkX6ENpriVINge%2FScreenshot%202026-07-01%20at%202.20.17%E2%80%AFPM.png?alt=media&amp;token=28b0f343-bd28-4948-819b-692efc0201f4" alt=""><figcaption></figcaption></figure>

| Tab      | What it shows                                                                                                       |
| -------- | ------------------------------------------------------------------------------------------------------------------- |
| Details  | All test case fields. You can edit fields inline. The test steps table also supports inline editing.                |
| Comments | Threaded discussion for the test case. Add a comment and click **Post**. Replies appear under the original comment. |
| History  | A log of each change, including who made it, when it changed, and the old and new values. This tab is read-only.    |


# Attachments

Upload and manage file attachments for test cases and other entities.

## Attachments

You can add file attachments to any entity in Test Manager.

This includes test cases, test plans, bugs, and requirements.

To add an attachment:

1. Open the entity detail page.
2. Scroll to the **Attachments** section.
3. Click **Upload** or drag files into the upload area.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FwqhzHhXide4PW40o9y8z%2FScreenshot%202026-07-01%20at%202.21.46%E2%80%AFPM.png?alt=media&amp;token=dc71d486-b3e2-4c41-8ba3-5fc109748ec4" alt=""><figcaption></figcaption></figure>

Supported file types include:

* images such as `PNG`, `JPG`, `GIF`, and `WebP`
* documents such as `PDF`, Word, Excel, and PowerPoint files
* media and archives such as `MP4`, `MOV`, `ZIP`, and `JSON`

The maximum file size is `50 MB` per file.

Download links stay valid for `1 hour`.

Refreshing the page generates a new download link.


# Exporting test cases

Export filtered or selected test cases in CSV or JSON format.

## Exporting test cases

To export test cases:

1. Open the test case list.
2. Apply filters or select specific rows.
3. Click **Export**.
4. Choose `CSV` or `JSON`.

The file downloads immediately.

Exports include all test case fields, including test steps.

Large exports can take a moment to prepare.


# Overview

Learn what test plans are and how to use them in Test Context Manager.

## Overview

A test plan groups test cases for a specific execution purpose.

### What this feature does

Use a test plan to prepare a repeatable execution set for a release, sprint, regression cycle, or environment check.

### What's included

A plan defines execution setup before anyone starts running tests.

This includes:

* configuration such as browser or device
* environment such as `QA`, `Staging`, or `Production`
* target version

### What's not included

A test plan does not record pass or fail results by itself.

Use a test run to execute the plan and capture results.

### When to use it

Test plans are the recommended starting point for structured testing.

After you create a plan, you can create test runs from it for actual execution.


# Creating a test plan

Create a test plan and link test cases to it.

## Creating a test plan

### Before you start

Make sure the test cases you want to include already exist.

Decide the plan name, environment, and any execution configuration you want to track.

To create a test plan:

1. Open **Test Plans** from the top sub-navigation or sidebar.
2. Click **Create Test Plan**.
3. Enter a name.
4. Fill in any other fields you need.
5. In **Linked Test Cases**, click **Add Test Cases**.
6. Search for test cases by name or ID.
7. Select the test cases to include.
8. Click **Save**.

The plan name is required.

{% hint style="info" %}
Some workspaces let you create a test plan with AI.
{% endhint %}

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FFrItqqpqUzEGVqvg7SLS%2FScreenshot%202026-07-01%20at%202.26.40%E2%80%AFPM.png?alt=media&amp;token=28f7641e-4e41-400f-bce5-99efdd5deb1a" alt=""><figcaption></figcaption></figure>

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FQd6zso2U2S158NAoaVqj%2FScreenshot%202026-07-01%20at%202.29.10%E2%80%AFPM.png?alt=media&amp;token=ffabd126-6295-458f-b3f9-785d7f19a512" alt=""><figcaption></figcaption></figure>

### Expected result

The new plan is saved with its linked test cases and execution setup.

You can open the plan later and create test runs from it.

### Next step

When the plan is ready, continue with [Creating a test run](/test-context-manager-documentation/test-runs/creating-a-test-run).


# Test plan fields reference

Review the fields available on a test plan.

## Test plan fields reference

| Field                | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| Name                 | Name of the test plan. Required.                                 |
| Description          | Purpose and scope of the plan.                                   |
| Version              | Target software version, such as `2.3.0`.                        |
| Status               | `Draft`, `Active`, `Completed`, or `Archived`.                   |
| Environment          | `Development`, `QA`, `Staging`, `UAT`, or `Production`.          |
| Device Type          | `Web`, `Mobile`, or `TV`.                                        |
| Browser Config (Web) | OS, OS version, browser, browser version, and screen resolution. |
| Mobile Config        | Device model, OS, OS version, and resolution.                    |
| TV Config            | Device model, OS, OS version, and resolution.                    |
| Start Date           | Planned execution start date.                                    |
| End Date             | Planned execution end date.                                      |
| Assignees            | Team members assigned to the plan.                               |
| Labels / Tags        | Classification tags.                                             |
| Linked Work Items    | Linked JIRA issues or other entities.                            |
| Attachments          | Supporting files.                                                |

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FYnmj7DHjPaEiM73Rq7E8%2FScreenshot%202026-07-01%20at%202.30.18%E2%80%AFPM.png?alt=media&amp;token=c520287e-1e53-4947-bcce-3c6a531c5f4a" alt=""><figcaption></figcaption></figure>


# Viewing a test plan

Open a test plan and review progress, linked cases, runs, and history.

## Viewing a test plan

Open any row in the test plan list to view its details.

The detail page includes these sections and tabs.

### Execution scoreboard

This summary shows execution progress across linked test cases.

It includes counts for:

* `Passed`
* `Failed`
* `Blocked`
* `In Progress`
* `Not Started`

### Linked test cases

This table lists all linked test cases.

For each test case, you can review:

* latest execution status
* last executed date

### Test runs

This section lists test runs created from the plan.

### Tabs

| Tab      | What it shows                     |
| -------- | --------------------------------- |
| Details  | All editable fields for the plan. |
| Comments | Discussion thread for the plan.   |
| History  | Full change history for the plan. |

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2Fijwp5CbVYe8am1bpfYkV%2FScreenshot%202026-07-01%20at%202.30.58%E2%80%AFPM.png?alt=media&amp;token=6300bc18-195c-496e-98b8-1cb850e3259e" alt=""><figcaption></figcaption></figure>


# Test plan workflows

Understand the core lifecycle from plan creation to execution.

## Test plan workflows

A typical workflow looks like this:

1. Create a test plan.
2. Add the relevant test cases.
3. Set the environment and configuration.
4. Spawn test runs from the plan.
5. Track execution progress from the scoreboard.

Use test plans when you need repeatable, scoped execution for a release or cycle.


# Overview

Learn what test runs are and what they capture.

## Overview

A test run is the execution of a test plan or a selected set of test cases.

### What this feature does

Use a test run to record real execution results for each test case and step.

### What's included

During a run, you execute each test case step by step.

For each step, you record whether it:

* passed
* failed
* was blocked
* was skipped

Test runs also capture evidence, comments, and linked defects.

### What's not included

A test run does not define the long-term structure of your repository.

Use test cases for reusable coverage and test plans for repeatable execution setup.

### Why it matters

Each run creates an execution record that feeds reports and test case history.


# Creating a test run

Create a test run from a plan or as an ad-hoc run.

## Creating a test run

Create a test run when you are ready to execute test cases.

### Before you start

Decide whether you want a structured run from a test plan or a one-off ad-hoc run.

Have the target environment and device configuration ready.

You can create a test run from a test plan or as an ad-hoc run.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2F1P48XM1GxNlu4LLAGx7U%2FScreenshot%202026-07-01%20at%202.33.48%E2%80%AFPM.png?alt=media&amp;token=1f6b01aa-f05b-4772-a012-0e75245f615e" alt=""><figcaption></figcaption></figure>

### From a test plan

1. Open the test plan you want to execute.
2. Click **Create Test Run**.
3. Review the pre-populated test cases and configuration.
4. Confirm or adjust the name, environment, and device configuration.
5. Click **Create**.

Runs created from a plan inherit the plan's test cases and configuration.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FVsrqTmK5hUHOOMtIvalB%2FScreenshot%202026-07-01%20at%202.34.15%E2%80%AFPM.png?alt=media&amp;token=21264216-062e-41dc-a5c0-d93e9cf70d76" alt=""><figcaption></figcaption></figure>

### Ad-hoc test run

1. Open **Test Runs**.
2. Click **Create Test Run**.
3. Choose `Ad-hoc` as the run type.
4. Add test cases manually using search.
5. Set the configuration.
6. Click **Create**.

### Expected result

The new run opens with the selected test cases and saved configuration.

It is now ready for execution.

### Next step

Continue with [Executing a test case](/test-context-manager-documentation/test-runs/creating-a-test-run/executing-a-test-case).


# Executing a test case

Run a test case step by step and record execution results.

## Executing a test case

Run each step and record the outcome in Test Context Manager.

To execute a test case in a run:

1. Open a test run from the **Test Runs** list.
2. Click a test case row.
3. Choose the device or configuration.
4. Execute each step on your application.
5. Record the result for each step.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2F83m8xUbODxbs4dcRWnKP%2FScreenshot%202026-07-01%20at%202.38.45%E2%80%AFPM.png?alt=media&amp;token=fb469e24-3a86-428a-a2e1-79e0c2085840" alt=""><figcaption></figcaption></figure>

Available device options include:

* **Own Cloud Device** for a custom registered device
* **Mozark Cloud Device** for Web, Mobile, or TV

For each step, review:

* **Action**
* **Test Data**
* **Expected Result**

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2F6TcVvKhHAyoYHlPGo1Pm%2FScreenshot%202026-07-01%20at%202.40.38%E2%80%AFPM.png?alt=media&amp;token=464e70c7-919d-46ae-a5ae-1bd5270c636c" alt=""><figcaption></figcaption></figure>

Then mark the step as:

* `Pass`
* `Fail`
* `Blocked`
* `Skip`

When all steps are marked `Pass`, the overall execution status is set to `Passed` automatically.


# Adding evidence and comments

Add per-step attachments and comments during execution.

## Adding evidence and comments

You can add evidence and notes at the step level during execution.

### Per-step evidence

Click the attachment icon next to a step.

Upload supporting files such as:

* screenshots
* videos
* log files

### Per-step comments

Click the comment icon next to a step.

Add a note to explain context, findings, or the reason for failure.


# Linking and creating bugs

Link an existing bug or create a new bug from a failed step.

## Linking and creating bugs

You can link bugs directly from a test step.

### Link an existing bug

1. Click **Link Bug** on the step.
2. Search by bug title or ID.
3. Select the bug to link it.

### Create a new bug

1. Click **Create Bug** on the step.
2. Review the pre-populated bug details.
3. Complete any remaining fields.
4. Save the bug.

The new bug is linked to the step automatically.


# Retrying a test case

Re-run a failed test case without creating a new test run.

## Retrying a test case

If a test case fails, you can retry it without creating a new test run.

To add a retry:

1. Open the execution page.
2. Find the **Run Attempts** section.
3. Click **Add Retry**.
4. Select the device and configuration for the retry.
5. Execute the steps again.
6. Record the result for each step.

The retry can use a different device or configuration from the original attempt.

Test Context Manager supports up to three retries per test case per run.

Attempt labels include:

* `Run-1`
* `Retry-1`
* `Retry-2`
* `Retry-3`

All attempts remain visible in **All Runs Summary**.


# Finishing a test run

Complete a run and lock its execution record.

## Finishing a test run

To finish a run:

1. Open the execution page.
2. Click **Finish Test** in the header.

When you finish a run:

* all step states are saved
* execution data is saved
* the run status is updated
* the run is locked from further edits

The **Finish Test** button becomes active after execution starts.

Record all important evidence and notes before you finish the run.


# Overview

Learn how bug tracking works in Test Manager.

Test Manager includes a built-in bug tracking system.

### What this feature does

Use bug tracking to capture issues found during execution and manage them through resolution.

### What's included

It integrates directly with test execution.

You can create bugs:

* from a failing test step
* from the **Bugs** section

Each bug gets a human-readable ID automatically.

Examples include `BUG-001` and `BUG-002`.

Each bug also includes status, severity, priority, assignee, and history.

### What's not included

Bug tracking does not replace test design or execution records.

Use test cases, plans, and runs for those workflows.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FA4iu6WMMQmGTNSa9nvZd%2FScreenshot%202026-07-01%20at%202.48.20%E2%80%AFPM.png?alt=media&amp;token=86301896-c638-4b69-9559-2cb2afb8e79d" alt=""><figcaption></figcaption></figure>


# Creating a bug

Create a bug from test execution or from the Bugs section.

## Creating a bug

### Before you start

Collect the issue details you want to capture.

If possible, create the bug from a failing step so the execution context is included automatically.

You can create a bug during test execution or manually.

### From test execution

This is the recommended method.

1. Open a failing step during test execution.
2. Click **Create Bug**.
3. Review the pre-filled details.
4. Complete any remaining fields.
5. Click **Save**.

Test Manager pre-fills the bug with the test case name and relevant context.

### Manually

1. Open **Bugs** from the top navigation.
2. Click **Create Bug**.
3. Enter a title and description.
4. Set severity, priority, status, and assignee.
5. Click **Save**.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FtlqBfSiyEG6AYE5Tu6rF%2FScreenshot%202026-07-01%20at%202.50.09%E2%80%AFPM.png?alt=media&amp;token=4eaccc6b-a368-4bb3-abcc-36f2a3e208f0" alt=""><figcaption></figcaption></figure>

### Expected result

The bug is saved with its own ID and lifecycle fields.

If you create it during execution, the bug also keeps the testing context that led to the issue.

### Next step

To understand how bugs move through resolution, see [Bug lifecycle](/test-context-manager-documentation/bug-tracking/creating-a-bug/bug-lifecycle).


# Bug fields reference

Review the fields available on a bug.

## Bug fields reference

| Field              | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| Title              | Short description of the defect. Required.                  |
| Description        | Detailed explanation of the issue.                          |
| Severity           | `Blocker`, `Critical`, `Major`, `Minor`, or `Trivial`.      |
| Priority           | `Low`, `Medium`, `High`, or `Critical`.                     |
| Status             | `Open`, `In Progress`, `Resolved`, `Closed`, or `Reopened`. |
| Assignee           | Person responsible for fixing the bug.                      |
| Environment        | Where the bug was found, such as `Dev`, `QA`, or `Staging`. |
| Steps to Reproduce | Numbered steps that trigger the bug.                        |
| Expected Behavior  | What should have happened.                                  |
| Actual Behavior    | What actually happened.                                     |
| Linked Test Case   | The test case that uncovered the bug.                       |
| Linked Work Items  | Linked JIRA issues or other internal entities.              |
| Labels / Tags      | Classification tags.                                        |
| Attachments        | Screenshots, logs, or other supporting evidence.            |
| Start Date         | Date work began.                                            |
| Due Date           | Target fix date.                                            |

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FXtX0WzFmnUiEvnc6hg0I%2FScreenshot%202026-07-01%20at%202.52.13%E2%80%AFPM.png?alt=media&amp;token=a75e3939-ba1b-4788-a68d-354ce79243c4" alt=""><figcaption></figcaption></figure>


# Bug lifecycle

Understand bug statuses and how they move through resolution.

## Bug lifecycle

Bugs move through a defined status workflow.

| Status      | Meaning                                                       |
| ----------- | ------------------------------------------------------------- |
| Open        | Bug is newly reported and not yet being worked on.            |
| In Progress | A developer or tester is actively investigating or fixing it. |
| Resolved    | A fix has been applied and is ready for verification.         |
| Closed      | The fix has been verified and the bug is no longer active.    |
| Reopened    | A previously closed bug needs more work.                      |

To update the status:

1. Open the bug detail page.
2. Click the status field.
3. Select the new status.

All status changes are recorded in the **History** tab.


# JIRA synchronization

Sync bugs between Test Manager and JIRA when integration is configured.

## JIRA synchronization

If JIRA integration is configured, bugs can synchronize between Test Manager and JIRA.

### What sync covers

Synchronization keeps linked bug records aligned between the two systems.

When a bug is created in Test Manager, a matching JIRA issue is created asynchronously.

The JIRA issue key appears on the bug page.

When a bug is updated in Test Manager, the linked JIRA issue is updated.

When a JIRA issue is updated, an inbound webhook can push changes back to Test Manager.

This requires webhook configuration in JIRA.

To trigger a manual sync:

1. Open the bug detail page.
2. Click **Re-Sync to JIRA**.

For integration setup, see the JIRA integration section.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2Fn6zibfN8g7VQkZ4XY4D1%2FScreenshot%202026-07-01%20at%202.53.35%E2%80%AFPM.png?alt=media&amp;token=82cf5124-32be-4f42-bbf3-ad189534b4b1" alt=""><figcaption></figcaption></figure>

### Verify synchronization

Create or update a bug in Test Manager and confirm that the JIRA issue key appears.

Then update the linked JIRA issue and confirm the change returns to Test Manager when the webhook is configured.

If both directions work, synchronization is active.


# Overview

Learn how reporting and analytics work in Test Context Manager.

Test Context Manager provides built-in reporting across the test lifecycle.

### What this feature does

Use reporting to review execution results, coverage, and quality trends across a project.

### What's included

You can generate reports on demand or on a schedule.

Most reports use test run data from the selected project.

### What's not included

Reports summarize existing data.

They do not replace the source workflows that create test cases, runs, bugs, or requirements.

### How to access it

To access reporting features, open **Reports** from the top navigation.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FOVhhAHGRE3fUWAZNWuQs%2FScreenshot%202026-07-01%20at%203.00.28%E2%80%AFPM.png?alt=media&amp;token=8e05b832-814b-4906-b11b-5b5017930940" alt=""><figcaption></figcaption></figure>


# Generating a report

Create a report, configure its scope, and export it as PDF.

## Generating a report

### Before you start

Make sure the project has the test run data you want to report on.

Decide the report type and scope before generating.

To generate a report:

1. Open the **Reports** page.
2. Click **Create Report** or use a quick access card.
3. Select the report type.
4. Configure the scope.
5. Select test runs and a time range.
6. Click **Generate**.

While the report is processing, its status shows as `Generating`.

When it is ready, the status changes to `Ready`.

Click the report to open it.

To export the report, click **Download PDF**.

<figure><img src="https://95054152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIgQEgtjvk4zIWyVkgQ5o%2Fuploads%2FkmdWnbOujrUGYpvnhpJa%2FScreenshot%202026-07-01%20at%203.01.01%E2%80%AFPM.png?alt=media&amp;token=b96d1a05-3102-41d8-bebe-2cc0624cb7ba" alt=""><figcaption></figcaption></figure>

### Scope options

You can scope a report to:

* all runs
* the last `N` runs
* specific runs

### Expected result

The report appears in the list with a processing status.

When processing finishes, you can open it and download the PDF.

### Next step

To compare available outputs, see [Report types](/test-context-manager-documentation/reports-and-analytics/generating-a-report/report-types).


# Scheduled reports

Schedule reports to generate automatically on a recurring basis.

## Scheduled reports

To create a scheduled report:

1. Open the **Reports** page.
2. Go to the **Scheduled** tab.
3. Click **Create Schedule**.
4. Select the report type and scope.
5. Set the frequency and time window.
6. Click **Save**.

Supported frequencies include:

* daily
* weekly
* monthly

Scheduled reports appear in the report list after generation.

You can view and download them the same way as manually generated reports.


# Report types

Review the report types available in Test Manager.

## Report types

Test Manager includes several report types.

| Report Type                       | What it shows                                                                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Functional Test Execution Summary | Aggregated results such as total test cases, pass rate, failure rate, blocked count, execution duration, and top failing test cases. |
| Defect Summary                    | Bug statistics such as total bugs, open versus resolved, severity distribution, top reporters, and creation trends.                  |
| Requirement Coverage              | Coverage across requirements, including linked test cases, execution progress, and overall requirement coverage status.              |
| Traceability Matrix               | A coverage matrix that compares requirements against linked test cases, execution status, test planning, and related bugs.           |

### Functional Test Execution Summary

Use this report to review overall execution health for a selected scope of test runs.

It summarizes how functional test cases are performing across active or completed execution cycles.

This report helps teams answer key execution questions:

* How many test cases passed, failed, or were blocked
* Which test runs are progressing on track
* Where bug creation is increasing during execution

The report typically includes:

* total executed test cases
* pass, fail, blocked, and skipped counts
* pass rate and failure rate
* execution trend over time
* top failing test cases
* bugs raised from failed execution

Use this report during daily test reviews, cycle tracking, and release checkpoints.

It gives stakeholders a clear view of execution progress and functional quality.

### Defect Summary

Use the defect summary to review bug volume, severity, and resolution trends across the selected scope.

This report helps teams understand the quality impact of issues found during testing.

It can help answer questions such as:

* How many bugs are still open
* Which severities are increasing
* Whether defect resolution is keeping pace with discovery

The report typically includes:

* total bugs raised
* open versus resolved bugs
* severity and priority breakdown
* bug creation trend
* top reporters or impacted areas

Use this report to track defect backlog health and release risk.

### Requirement Coverage

Use this report to measure how much of the requirement set is backed by linked and executed tests.

It focuses on coverage completeness rather than detailed bug-by-bug traceability.

This report helps teams answer:

* Which requirements already have linked test cases
* Which requirements still lack execution coverage
* What percentage of the requirement set is covered

The report typically includes:

* total requirements in scope
* requirements with linked test cases
* executed versus unexecuted coverage
* covered, partial, and uncovered counts
* overall coverage percentage

Use this report before planning sign-off, coverage reviews, and release readiness checks.

### Traceability Matrix

Use the traceability matrix to compare requirements against the testing work that supports them.

It shows how each requirement maps to linked test cases and whether those test cases are being planned and executed.

This helps teams answer three key questions:

* Does each requirement have test coverage
* Are the linked test cases included in active testing workflows
* Are open bugs affecting covered requirements

The matrix combines requirement linkage, latest execution state, and related bug data in one view.

This makes it easier to spot gaps before release reviews.

Teams can use this report to assess coverage completeness, defect impact, and overall release readiness for GA decisions.

For the full workflow and coverage views, see [Traceability report](/test-context-manager-documentation/reports-and-analytics/generating-a-report/traceability-report).


# Traceability report

View requirement coverage, linked test cases, and related bugs in one matrix.

## Traceability report

The traceability report provides a full matrix connecting requirements, test cases, and bugs.

Open **Reports** → **Traceability** to access it.

Use this report to compare product requirements against the testing work and defects connected to them.

The report shows:

* every requirement in the project
* the test cases linked to each requirement
* the latest execution status of each linked test case
* any bugs linked to those test cases
* an overall coverage status for each requirement

### What it helps you compare

The matrix helps you review each requirement against three related signals:

* linked test cases for planned coverage
* latest execution results for actual coverage
* linked bugs for quality risk

This view helps you see whether a requirement is covered, partially covered, or still exposed.

It also helps you compare one requirement against another during release reviews.

Coverage status values include:

* `Covered`
* `Partial`
* `Uncovered`

### How teams use it

Teams often use the traceability report to answer these questions:

* Which requirements are fully covered by tests
* Which covered areas still have open bugs
* Which requirements need more testing before release

This report is especially useful before sign-off or GA review.

It provides a single view of coverage depth, execution outcomes, and defect linkage.

You can use these signals to support a release readiness or GA readiness assessment.

Additional views include:

* **Coverage by Priority** as a bar chart
* **Coverage Trend** as a line chart
* **Uncovered List** as a sortable table


# For You dashboard

Review project-level quality metrics from the For You page.

## For You dashboard

The **For You** page provides a project-level health overview.

You can access it from **Test Manager** in the sidebar.

This dashboard includes:

* **Test Cases** with status distribution for `Active`, `Draft`, and `Deprecated`
* **Test Runs** with execution status across active runs
* **Bugs** with total open bugs and priority breakdown
* **Flakiness** with flakiness rate and top flaky test cases
* **Draft Test Cases** older than `90` days
* **Automation Coverage** for `Automated` versus `Manual` test cases


# Integrations

Connect Test Manager with external systems such as JIRA for traceability and bug synchronization.

## Integrations

Test Manager connects with external systems to keep testing workflows in sync.

Integrations support traceability across test cases, requirements, bugs, and external work items.

### Supported integration patterns

Current workflows include:

* linking external work items to test cases, requirements, and bugs
* synchronizing bugs with JIRA
* receiving inbound updates from JIRA through webhooks

### JIRA integration

JIRA integration keeps bug data aligned between Test Manager and JIRA.

When configured:

* bugs created in Test Manager create matching JIRA issues
* updates in Test Manager update the linked JIRA issue
* inbound JIRA webhooks can push updates back to Test Manager

Open [JIRA synchronization](/test-context-manager-documentation/bug-tracking/creating-a-bug/jira-synchronization) for the sync workflow.

### Linked work items

Linked work items connect product artifacts across systems.

You can use them to:

* connect requirements to related external issues
* connect test cases to planning or delivery work
* connect bugs to the broader implementation context

This linkage improves reporting and end-to-end traceability.

### Before you configure integrations

Confirm these items first:

* the target project and issue mappings are defined
* the required access and permissions are available
* webhook configuration is ready if you need inbound sync

### Where integrations show up in Test Manager

Integration data appears in key workflows:

* [Bug lifecycle](/test-context-manager-documentation/bug-tracking/creating-a-bug/bug-lifecycle)
* [Traceability](/test-context-manager-documentation/requirements/creating-a-requirement/traceability)
* [Traceability report](/test-context-manager-documentation/reports-and-analytics/generating-a-report/traceability-report)

### Best practices

* keep project mappings stable
* sync bugs from execution workflows where context is richest
* use linked work items consistently across requirements and defects


# Agent Workspace

Use our agents to plan faster, clean up duplicate coverage, and generate test cases without leaving your current workflow.

### Before you start

1. Sign in with your credentials.
2. Select your project from the project picker at the top of the page.
3. Confirm that your project already contains test cases before using the Cleaner Agent or Planner Agent.

The agents only work within the project you select.

The Cleaner Agent and Planner Agent rely on existing test case data. If your project is empty, start with the Author Agent.

### Where to find the agents

TCM Agents open as slide-in panels on the right side of the screen.

They appear on top of your current page, so you can keep your place while you work. You do not need to navigate to a separate area of Test Context Manager.

* **Author Agent** — open it from the **Test Cases** page toolbar using **✦ AI Author**
* **Cleaner Agent** — open it from the **Test Cases** page toolbar using **✦ AI Cleaner**
* **Planner Agent** — open it from the **Test Plans** page toolbar using **✦ AI Planner**

Each button appears in the top-right toolbar of its page and uses the sparkle icon.

### Next step

Read [Agents overview](/agent-workspace-documentation/getting-started/overview) to understand what each agent does and when to use it.


# Overview

Understand what each TCM Agent does and when to use it.

## Agents overview

TCM Agents are built-in AI helpers inside Test Context Manager.

They make everyday test management work faster. Instead of searching through thousands of test cases manually, you describe what you need in plain English. The right agent then handles planning, cleanup, or test case generation for you.

Each agent has one job and stays focused on it.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FHIPva0k4CzxFm58MQqqO%2FScreenshot%202026-07-16%20at%203.26.59%E2%80%AFPM.png?alt=media&amp;token=38c8a0d0-1bb2-424f-99a7-3bdd9ee2c527" alt=""><figcaption></figcaption></figure>

### What each agent does

#### Planner Agent

Use the Planner Agent when you need a ready-to-use list of relevant test cases.

It takes a feature name, flow, or user journey and returns the test cases that matter most for that scope.

Read [Planner Agent](/agent-workspace-documentation/planner-agent/overview).

#### Cleaner Agent

Use the Cleaner Agent to keep your repository clean and usable.

It finds duplicate and near-duplicate test cases. It then recommends what to keep, merge, or delete.

Read [Cleaner Agent](/agent-workspace-documentation/cleaner-agent/overview).

#### Author Agent

Use the Author Agent when you need to create new test cases.

It helps turn requirements, flows, or feature details into structured test cases you can review and add to the repository.

Read [Author Agent](/agent-workspace-documentation/author-agent/overview).

### Why it matters

Test repositories grow quickly.

New test cases are added every sprint. Similar cases are often created by different teams. Older cases can stay in the repository long after their original requirement changes or disappears.

TCM Agents simplify the workflows teams already run in Test Context Manager. They reduce hours of manual searching and cross-referencing to a short conversation.

They also keep each organization's test data isolated, so one team's repository never mixes with another's.

### Who this workspace is for

This guide is for teams who use TCM Agents in day-to-day QA and release workflows, including:

* QA leads building release test plans
* Test engineers maintaining lean, high-signal suites
* QA managers improving coverage quality across projects
* Teams expanding and maintaining test coverage inside TCM

### What to expect from this guide

Use this guide to understand when to use each agent, what input to provide, and how to act on the results.

The rest of the workspace walks through each agent in more detail.

Next, read [Getting started](/agent-workspace-documentation) to learn how to access the agents and start using them.

For common workflows and support guidance, also read [Common workflows](/agent-workspace-documentation/common-workflows), [Best practices](/agent-workspace-documentation/best-practices), and [FAQ and troubleshooting](/agent-workspace-documentation/faq-and-troubleshooting).


# Overview

Generate, review, and save AI-created test cases for a feature or flow.

## Author Agent

Author Agent helps you generate structured test cases for a feature, flow, or requirement.

Use it when you want to build test coverage faster, review suggested cases before saving them, and add new cases directly to TCM.

### Open Author Agent

Open **Test Cases** from the sidebar.

In the top-right toolbar, click **✦ AI Author**.

A drawer opens from the right side of the page. The drawer header shows **AI Test Case Generator**.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FkdhcefJvapM8kNnFf92W%2FScreenshot%202026-07-16%20at%203.42.03%E2%80%AFPM.png?alt=media&amp;token=cfb07ef6-bb10-4df2-8192-0179615ee420" alt=""><figcaption></figcaption></figure>

### Knowledge Corpus

Knowledge Base stores the context Author Agent uses to generate accurate, context-aware test cases. Add screenshots, Figma frames, or documents so the agent understands your product before it generates test cases.\
\
If your project has no Knowledge Base data, Author Agent shows a warning banner in the chat panel: **No Knowledge Base data**, with a prompt to add your app requirements, user stories, or design docs.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FPn53EUmWNHEZjSXLzUHR%2FScreenshot%202026-07-13%20at%205.07.05%E2%80%AFPM.png?alt=media&amp;token=b9422202-db8d-4d97-aab7-750455125603" alt=""><figcaption></figcaption></figure>

Click **+ Add sources to Knowledge Base →** to open the Knowledge Base drawer.

**Source types:**

* **Images & Screenshots** — product screenshots or design images (PNG, JPG, WebP, up to 100 MB each, multiple files supported)
* **Figma** — live frames pulled directly from a connected Figma file
* **Other Docs** — requirement docs, specs, or PRDs (PDF, DOCX, up to 100 MB each)<br>

**Add images or screenshots**

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2Fi4AGZLk39dqc2DAfOWoS%2FScreenshot%202026-07-14%20at%206.24.22%E2%80%AFAM.png?alt=media&amp;token=1bd15ba1-d4df-42a7-a879-f349864ce834" alt=""><figcaption></figcaption></figure>

1. Open the **Images & Screenshots** tab.
2. Drag and drop files onto the upload area, or click **Browse files**.
3. After upload, you'll see **"X images uploaded — Select which to annotate."** All uploaded images are selected by default; use **Deselect all** or **+ Add more** to adjust the batch.
4. Click **Annotate (X) →** to start processing.

While annotation runs, each file shows its status in order: **Done**, a live percentage, or **Waiting**.

**Review detected elements**

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FO9gj1V5sIWEZx9XIBaz0%2FScreenshot%202026-07-14%20at%206.28.11%E2%80%AFAM.png?alt=media&amp;token=a7683654-9e94-424b-83a2-a0cf37a7afc9" alt=""><figcaption></figcaption></figure>

Once annotation finishes, each image opens in a three-panel review view:

* Left: thumbnail strip to navigate between files
* Center: the image itself
* Right: a table of detected elements — **Element Name** and **Type** (Text, Icon, Button, Image, Input)

From here you can:

* Click **+ Element** to manually add an element the auto-detection missed
* Remove individual elements using the trash icon in their row
* Click **Remove** (top right) to discard the whole file
* Click **Add to Knowledge Base →** to save the current file, or **Add all (X)** to save every file in the batch
*

```
<figure><img src="/files/jVITRsPKFNQExdGjIJ7j" alt=""><figcaption></figcaption></figure>
```

If a file has already been saved, this button changes to **Update Knowledge Base**, so you can push edits to an existing source.

**Connect a Figma file**

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FsefII2DflsJ7jpvHFjMH%2FScreenshot%202026-07-14%20at%207.21.34%E2%80%AFAM.png?alt=media&amp;token=42e4eeaa-a494-4681-a306-8cee93934837" alt=""><figcaption></figcaption></figure>

1. Open the **Figma** tab.
2. Paste the **Figma file URL**.
3. Paste your **Personal access token** (get this from Figma → Account Settings → Personal Access Tokens).
4. Click **Extract Frames →**.

Every frame is pulled from the file. From there, review and annotate frames the same way as uploaded images — each frame goes through element detection, and you can edit, add, or remove elements before saving.

**Add other docs**

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FyGfPdjTlPxq6nTqKcBO5%2FScreenshot%202026-07-14%20at%206.35.27%E2%80%AFAM.png?alt=media&amp;token=e14a78dd-398e-4f6b-8c1b-8e30f113e973" alt=""><figcaption></figcaption></figure>

1. Open the **Other Docs** tab.
2. Drag and drop a file, or click **Browse files**.
3. Supported formats: PDF, DOCX, up to 100 MB each.

Unlike images and Figma frames, documents don't go through element annotation — they're added straight to the Knowledge Base and marked **In Knowledge Base** once uploaded.

**Manage existing sources**

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FsfT8UFrLYbEdlGaB1N1p%2FScreenshot%202026-07-14%20at%206.37.22%E2%80%AFAM.png?alt=media&amp;token=f0e1b481-a093-475d-9eb6-be421bb5856f" alt=""><figcaption></figcaption></figure>

Every source you've added appears under **Already in Knowledge Base**, showing its name, file size, and detected element count (for images/frames).

Each row has:

* **Edit** — reopen the file to adjust its saved elements
* **Delete** — remove the source from the Knowledge Base entirely

The drawer footer always shows a running total, e.g. **Knowledge Base: 12 sources**, broken down by type (e.g. **11 images**, **1 doc**).

### Generate test cases

Author Agent guides you through a short setup before it starts generating test cases.

#### 1. Choose test case types

Start by selecting one or more test case types.

You can choose from:

* **Functional** — core product behavior
* **Edge** — boundary conditions and unusual inputs
* **Automation** — atomic, machine-executable steps

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FEod7StIPsEHvGxLu6Dam%2FScreenshot%202026-07-17%20at%202.49.06%E2%80%AFPM.png?alt=media&amp;token=1c6e25fb-b4b6-412f-be65-57c4459ab3fa" alt=""><figcaption></figcaption></figure>

After you select at least one type, click **Continue with X type(s) →**.

You can select multiple types in a single run.

If you need help choosing, read [Author Agent test case types](broken://spaces/MhLDAQDUuKnEzEkcw9Ya/pages/SvBiLkRbcDfcAoDGF6QJ).

#### Functional

Use **Functional** test cases for high-level, human-readable coverage.

Choose this type when you want to verify that a feature behaves as expected from a user point of view.

Functional test cases work well for day-to-day manual review and broad feature validation.

#### Automation

Use **Automation** test cases when you want steps broken into small, atomic actions.

Choose this type when you need cleaner handoff into automation design or script creation.

These outputs stay human-readable. They are not executable scripts.

#### Edge

Use **Edge** test cases to cover boundary conditions and extreme inputs.

Choose this type when you want to test how the app behaves at the limits of supported input or usage.

This is useful for validating graceful handling of unusual but important scenarios.

#### 2. Choose polarity

Next, choose the kind of scenarios you want:

* **Positive** for expected successful flows
* **Negative** for invalid input, failure paths, and error handling

You can choose one or both depending on the coverage you need, then click **Continue**.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2F2B886mxkBQSgOBA2chLH%2FScreenshot%202026-07-02%20at%2012.48.42%E2%80%AFPM.png?alt=media&amp;token=f651333f-464f-45a4-850b-09a1cd5fe646" alt="" width="375"><figcaption></figcaption></figure>

#### 3. Enter a feature name

Enter the feature, flow, or user journey you want to cover.

Examples include `Login`, `Checkout`, and `Password Reset`.

When the field is complete, click **Search & Preview Modules →** to start generation.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FpOw62qb1qdh1qxCQNo7Z%2FScreenshot%202026-07-02%20at%2012.49.21%E2%80%AFPM.png?alt=media&amp;token=4a856c0c-8150-4822-89dc-63a64c7fa045" alt="" width="375"><figcaption></figcaption></figure>

### Review generated test cases

When generation finishes, Author Agent returns a set of suggested test cases for your request.

Each test case appears as a card with a title, a checkbox, and metadata tags.

Selected test cases are checked by default, so you can move quickly into review and save.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2Fl5jpDwuL2oPyOnWH8FEW%2FScreenshot%202026-07-17%20at%203.35.48%E2%80%AFPM.png?alt=media&amp;token=ed42666c-33fa-4b6d-9bd4-908692873985" alt=""><figcaption></figcaption></figure>

### Open and edit a test case

Click any generated test case card to open its detail panel.

The detail view slides in from the left and includes:

* title
* description
* preconditions
* ordered test steps
* supporting metadata such as status, priority, type, labels, people, and timeline

Use **Edit** to update the content before saving.

You can save your edits or cancel to discard them.

When you finish reviewing, close the panel using the back arrow or **X**.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FW8RMCSv6vMQBn9eGZ3Wh%2FScreenshot%202026-07-17%20at%203.37.47%E2%80%AFPM.png?alt=media&amp;token=0c465c48-ad1a-4c4c-a504-735a2ce977ac" alt=""><figcaption></figcaption></figure>

### Save test cases&#x20;

At the bottom of the drawer, the **Add to Repository** area shows how many test cases are selected.

Select the cases you want to keep, then click **Add 'x' Test Cases to Repository**.

After the save completes, the new test cases appear in **Test Cases** with an **AI Generated** badge.

If nothing is selected, you need to select at least one test case before saving.

### Resume previous work

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2Fvtt4vKnl1e9kpAQEzW2P%2FScreenshot%202026-07-15%20at%203.26.06%E2%80%AFPM.png?alt=media&amp;token=30170387-8139-4794-9d35-ea1304e00606" alt=""><figcaption></figcaption></figure>

Use **Past Sessions** in the drawer header to reopen earlier conversations.

Each saved session shows its message count and timestamp.

Select a session to continue where you left off.

To start over, click **New Session**. This clears the current conversation and returns you to the first setup step.

### Tips for better results

* Add Knowledge Base sources for more accurate, context-aware output.
* Use clear feature or journey names such as `Login` or `Checkout`.
* Start with **Functional** if you are unsure which type to use.


# Overview

Find relevant existing test cases and turn them into a test plan.

## Planner Agent

Planner Agent helps you build a test plan from the test cases already in your project.

Use it to find the most relevant existing coverage for a feature, release area, or user journey, then add the selected test cases to a new or existing plan.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FE9u4PFqywm4jcsCjDpNf%2FScreenshot%202026-07-02%20at%201.00.19%E2%80%AFPM.png?alt=media&amp;token=00645b9d-0d8f-48b5-8788-7908c4d8c2fe" alt=""><figcaption></figcaption></figure>

### Before you start

Your project must already contain test cases.

Planner Agent searches your current project and uses the test cases it finds to build the plan.

### Open Planner Agent

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FzEvkwNAWImVJMXf34umf%2FScreenshot%202026-07-02%20at%201.00.25%E2%80%AFPM.png?alt=media&amp;token=70fe320e-8b14-4216-a65f-b56ef3357b60" alt=""><figcaption></figcaption></figure>

Open **Test Plans** from the sidebar.

In the top-right toolbar, click **✦ AI Planner**.

A drawer opens from the right side of the page. The drawer header shows **Test Plan Agent**.

### Find relevant test cases

In the chat input, describe the feature, flow, release scope, or area you want to cover.

Examples include `Payment checkout flow`, `UPI payments`, or `Login`.

When you send the request, Planner Agent searches your repository and returns the most relevant test cases.

The results appear as selectable test case cards.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FMtqOCy7UYEN0y3WV4csE%2FScreenshot%202026-07-02%20at%201.01.06%E2%80%AFPM.png?alt=media&amp;token=ff3680e0-9a2f-420c-9e4c-964b1d66e9d9" alt=""><figcaption></figcaption></figure>

### Set the number of results

Use the result limit control next to the send button to choose how many test cases Planner Agent should return.

The default is **20**.

Increase or reduce the limit before sending a new search if you want a broader or narrower result set.

### Review the results

Planner Agent returns matching test cases as cards with titles and checkboxes.

Selected test cases are checked by default so you can move quickly into plan creation.

If you want more detail, click any test case card to open its full detail view.

### Open and edit a test case

Click any result card to open the detail panel.

From there, you can review:

* title
* description
* preconditions
* test steps
* supporting metadata

Use **Edit** to update the test case before you add it to a plan.

### Create a new test plan

After reviewing the results, keep the test cases you want selected.

Then click **Create new plan**.

In the plan creation window, enter the required details such as name, status, and version.

When you save, the new plan is created with the selected test cases already linked.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2F9vgF8Dn8Qk4rLa3Gdozd%2FScreenshot%202026-07-02%20at%201.02.09%E2%80%AFPM.png?alt=media&amp;token=14368955-c03b-436d-917c-f18dd6cca592" alt=""><figcaption></figcaption></figure>

### Add test cases to an existing plan

If you already have a plan, click **Add to existing plan** instead.

Search for the plan by name, select it, and confirm.

Planner Agent adds the selected test cases to that plan.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FcnEA0wgOZmot938E4fhJ%2FScreenshot%202026-07-02%20at%201.02.22%E2%80%AFPM.png?alt=media&amp;token=c2232756-9f4c-4fa1-94cc-d74e7736652a" alt=""><figcaption></figcaption></figure>

### Resume previous work

Use **Past Sessions** in the drawer header to reopen earlier conversations.

Select a previous session to continue where you left off.

To start over, click **New Session**.

### If you do not see the results you expect

Planner Agent may return fewer results when:

* the current project does not contain relevant test cases
* the request is too broad or too vague
* the result limit is set too low

If needed, rewrite the request using a clearer feature or journey name.

### Next step

Read [Planner Agent search tips](/agent-workspace-documentation/planner-agent/planner-agent-search-tips) to learn how Planner Agent interprets queries, expands related terms, and handles empty results.


# Planner Agent search tips

Understand query behavior, result limits, and how to get better matches.

## Planner Agent search tips

Planner Agent uses meaning-based search to find relevant test cases.

It does not rely only on exact keyword matches.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FpzkUVss4lv0pqzJ7rkfT%2FScreenshot%202026-07-02%20at%201.09.27%E2%80%AFPM.png?alt=media&amp;token=c4b94b09-695e-4f60-92d6-68ca62bb9fea" alt="" width="375"><figcaption></figcaption></figure>

### How search works

When you describe a feature or journey, Planner Agent looks for related terminology and matching test coverage in your current project.

This helps it find useful results even when your wording differs from the wording used in existing test cases.

For example, a request for `Login` may also match related authentication flows.

A request for `Fund Transfer` may also match related transfer methods already described in the repository.

### Choose a better query

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FVUJaonu69xPRE3NgZegW%2FScreenshot%202026-07-16%20at%2010.35.26%E2%80%AFAM.png?alt=media&amp;token=d7196261-82be-4fb3-9d25-81ae60a6feda" alt=""><figcaption></figcaption></figure>

Use a clear feature, journey, or release area.

Good examples include:

* `UPI payments`
* `Payment checkout flow`
* `Password reset`

Avoid vague prompts such as `yes`, `ok`, or short follow-up messages without enough context.

### Result limits

Planner Agent lets you choose how many test cases to return before you run the search.

Use a lower number when you want a focused shortlist.

Use a higher number when you want broader plan coverage.

If the results feel too narrow, raise the limit and search again.

### No-result searches

If nothing relevant is found, Planner Agent returns zero results instead of inventing test cases.

This usually means one of these things is true:

* the current project does not contain matching coverage
* the search should be rewritten with a clearer feature or journey name
* the search is being run in the wrong project

### Common pitfalls

* Do not combine multiple unrelated requests into one search if you want separate result sets.
* Do not assume a missing result means the test case does not exist. It may be stored in a different project.
* Do not expect Planner Agent to create new test cases. It only finds and organizes existing ones.

### Next step

Return to [Planner Agent](/agent-workspace-documentation/planner-agent/overview) for the end-to-end workflow.


# Overview

Find duplicate and near-duplicate test cases, then decide what to keep, merge, or remove.

## Cleaner Agent

Cleaner Agent helps you reduce duplicate coverage in your test repository.

Use it to find repeated or highly similar test cases, review grouped results, and decide what to keep, merge, or remove.

### Before you start

Your project must already contain test cases.

If the project is empty, Cleaner Agent will not find anything to compare.

### Open Cleaner Agent

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FYOi2FtpRqtd4wU9uQhPi%2FScreenshot%202026-07-16%20at%2010.04.29%E2%80%AFAM.png?alt=media&amp;token=383d5aed-acf6-41f6-8ea2-41ed49b7bfbd" alt=""><figcaption></figcaption></figure>

Open **Test Cases** from the sidebar.

In the top-right toolbar, click **✦ AI Cleaner**.

A drawer opens from the right side of the page.

### Start a scan

At the bottom of the drawer, enter the journey you want to scan.

To scan the full repository, enter `scan all`.

You can also choose how the scan runs:

* **Semantic** — finds near-duplicates and similar intent
* **Exact** — finds word-for-word matches

In **Semantic** mode, you can also set a similarity threshold.

When you are ready, send your request.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FBIdbwdQ5DNCnW5lHDbGT%2FScreenshot%202026-07-17%20at%205.31.37%E2%80%AFPM.png?alt=media&amp;token=754c7aec-f7a6-4ae5-9f1b-8b8370675469" alt=""><figcaption></figcaption></figure>

### Review duplicate groups

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FFPbvoS8H81to2JZHF5jV%2FScreenshot%202026-07-17%20at%204.16.04%E2%80%AFPM.png?alt=media&amp;token=b7ca898e-836a-4447-a1d2-def46bbade64" alt=""><figcaption></figcaption></figure>

When the scan finishes, Cleaner Agent opens a results panel on the left.

Each result appears as a group of similar test cases.

Open a group to review:

* why the test cases were grouped together
* which test case should stay
* which test cases may be merged or removed
* the similarity score for each related case

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FFujRG5Bg8z991f7WMyJg%2FScreenshot%202026-07-16%20at%2010.12.11%E2%80%AFAM.png?alt=media&amp;token=11bc56ee-eae9-42c8-bb80-99b2216cc0ab" alt=""><figcaption></figcaption></figure>

One test case is marked as the primary version for the group.

### Take action on results

From a result group, you can take action directly.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FNG5d8KjtWW7QQHhW38Wu%2FScreenshot%202026-07-17%20at%204.07.27%E2%80%AFPM.png?alt=media&amp;token=c60ecfa4-1929-43c7-bc4b-f0e4d0c35e8e" alt=""><figcaption></figcaption></figure>

#### Delete a duplicate

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2Fz3hgx3HJMlQkTGrakzn3%2FScreenshot%202026-07-16%20at%2010.16.30%E2%80%AFAM.png?alt=media&amp;token=65e791eb-5107-43cb-928b-cccb00150f79" alt=""><figcaption></figcaption></figure>

Delete a test case when it adds no value beyond the primary version.

After deletion, the case is removed from the group and no longer appears in **Test Cases**.

#### Mark as not duplicate

Use **Not Duplicate** when a grouped case should remain separate.

This removes it from the duplicate group without deleting it.

#### Merge a group

Use **Merge** when multiple test cases contain useful details worth combining.

Cleaner Agent opens a merged draft that combines the best content from the group. Review it, then save it as a new test case.

#### Edit a test case

Open any test case from the results view to update its title, steps, or other details before you decide what to do with it.

### Filter and explore results

Use the filter field at the top of the results panel to narrow groups by title.

You can also ask follow-up questions in the chat, such as which journey has the most duplicates or how many exact duplicates are in the project.

### If no results appear

Cleaner Agent may return no groups when:

* the project has too few test cases to compare
* the selected journey has little or no matching content
* the threshold is set too high for near-duplicates to qualify

If needed, lower the threshold or expand the scan to a broader scope.

### Next step

Read [Cleaner Agent scan modes](/agent-workspace-documentation/cleaner-agent/cleaner-agent-scan-modes) to understand the difference between Semantic and Exact scans, similarity thresholds, and result labels.


# Cleaner Agent scan modes

Understand scan types, thresholds, and how to read cleanup recommendations.

## Cleaner Agent scan modes

Cleaner Agent supports two scan modes.

Choose the mode that matches how strict you want duplicate detection to be.

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FPGOPnlI3ljzMwG0Jqt3P%2FScreenshot%202026-07-02%20at%2012.56.07%E2%80%AFPM.png?alt=media&amp;token=04da1911-d383-4732-aefb-8d29007c78a8" alt="" width="375"><figcaption></figcaption></figure>

### Semantic scans

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2FBnl3M7lAdqVTGVv8n48j%2FScreenshot%202026-07-15%20at%203.03.54%E2%80%AFPM.png?alt=media&amp;token=2962b956-9089-4594-bb83-010847d30636" alt=""><figcaption></figcaption></figure>

Use **Semantic** when you want to find near-duplicates, not just identical wording.

This mode compares intent and similarity across test cases. It works best when different teams describe the same flow in slightly different ways.

Semantic mode also lets you set a similarity threshold.

Lower thresholds return broader matches. Higher thresholds return fewer, stricter matches.

If you set the threshold very high, near-duplicates may no longer appear in results.

### Exact scans

Use **Exact** when you want to find cases that match word for word.

This mode is stricter and usually faster.

It works well when you want to clean up direct copies or repeated imports.

### Scan scope

<figure><img src="https://3993399468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMhLDAQDUuKnEzEkcw9Ya%2Fuploads%2F5w8TXM4nBYeb9ZdU3boj%2FScreenshot%202026-07-16%20at%2010.20.04%E2%80%AFAM.png?alt=media&amp;token=17617cbc-46bd-43c3-83e5-4dd0e538019f" alt=""><figcaption></figcaption></figure>

You can scan either:

* a specific journey or folder
* the full repository with `scan all`

A journey scan only compares test cases in that scope.

A full scan compares the entire project.

### Read cleanup recommendations

Each duplicate group includes a recommendation for every test case.

#### Keep

**Keep** marks the best version to retain.

This is usually the most complete or most useful test case in the group.

#### Delete

**Delete** marks a test case as redundant.

Use this when the case adds no unique value once the primary version is kept.

#### Review

**Review** means the test case is similar, but still contains something worth preserving.

In most cases, you should merge that useful detail into the primary version before deleting the original.

### When to merge instead of delete

Choose **Merge** when multiple test cases cover the same flow but each one adds useful detail.

This is common when one version has stronger preconditions and another has better step coverage.

### Common pitfalls

* Do not delete a case marked **Review** until you confirm its unique detail is preserved.
* Do not expect **Exact** mode to find similar wording or shared intent.
* Do not assume a no-result scan means the repository is clean. The scope or threshold may be too narrow.

### Next step

Return to [Cleaner Agent](/agent-workspace-documentation/cleaner-agent/overview) for the end-to-end workflow.


# Common workflows

Common ways teams use Author Agent, Cleaner Agent, and Planner Agent together.

## Common workflows

Use these workflows to get consistent results from the agent workspace.

### Build a release test plan

Use [Planner Agent](/agent-workspace-documentation/planner-agent/overview) to search one feature, flow, or release area at a time.

Review the returned test cases, then add them to a new plan or an existing plan.

Because search always runs inside your current project, plan one project at a time.

### Clean up duplicate coverage

Use [Cleaner Agent](/agent-workspace-documentation/cleaner-agent/overview) to reduce duplicate or overlapping test cases.

For large repositories, start with one journey at a time.

Review each result group carefully. Merge useful details first, then delete only the cases that are truly redundant.

### Fill coverage gaps

If [Planner Agent](/agent-workspace-documentation/planner-agent/overview) does not return enough relevant coverage, switch to [Author Agent](/agent-workspace-documentation/author-agent/overview) to generate new test cases.

Review the generated cases, save the ones you want, then return to planning if needed.

### Resume earlier work

Use **Past Sessions** to reopen earlier work in **Author Agent**, **Cleaner Agent**, or **Planner Agent**.

Use **New Session** when you want to start a separate task with a clean conversation.

### Move between agents

Each agent works independently.

Results do not move automatically from one agent to another.

If you switch drawers, rerun the search or restate the context for that agent.


# Best practices

Get better results from Author Agent, Cleaner Agent, and Planner Agent.

## Best practices

### Describe features naturally

Use the language your team uses in the app or workflow under test.

A clear request such as `Verify UPI payment flow including VPA entry and PIN` works better than a short keyword list.

### Keep each request focused

Search or generate for one feature, journey, or release area at a time.

Focused requests are easier to review and usually return better results.

### Start cleanup with Semantic mode

Use **Semantic** mode first when you want to find both exact duplicates and near-duplicates.

Use **Exact** mode when you want to confirm direct copies.

### Scan large repositories in smaller scopes

For large repositories, run **Cleaner Agent** one journey at a time.

This makes the results easier to review and act on.

### Review before you delete or merge

Treat recommendations as a starting point.

Before you delete a test case, confirm that any unique detail has been preserved.

### Add Knowledge Base sources for better authoring

[Author Agent](/agent-workspace-documentation/author-agent/overview) works best when your project includes relevant Knowledge Base sources.

Add requirements, flows, or supporting documents if you want more accurate generated coverage.

### Reuse sessions deliberately

Use one session for one task when possible.

This keeps your planning, cleanup, and authoring history easier to revisit later.

### Check the current project before you start

All agent results are scoped to the project you selected at the top of Test Case Manager.

If results look incomplete, confirm that you are working in the intended project.


# FAQ and troubleshooting

Solve common issues when searching, generating, or cleaning up test cases.

## FAQ and troubleshooting

<details>

<summary>Planner Agent found 0 test cases</summary>

This usually means the current project does not contain matching test cases, or the request is too broad.

Try a clearer feature or journey name such as `Login`, `UPI payments`, or `Payment checkout flow`.

If the result still looks wrong, confirm that you are in the correct project.

</details>

<details>

<summary>Cleaner Agent found no groups</summary>

This usually means there are too few test cases in scope, or the selected journey does not contain enough similar cases to compare.

Try scanning a broader area or the full repository.

If you are using **Semantic** mode, lower the similarity threshold and run the scan again.

</details>

<details>

<summary>A duplicate I expected was not flagged</summary>

In **Semantic** mode, the threshold may be too high for that match.

Lower the threshold if the test cases are similar but worded differently.

Use **Exact** mode only when you expect a word-for-word match.

</details>

<details>

<summary>I cannot find a saved session</summary>

Session history is specific to the current agent and your signed-in user.

Confirm that you are checking the right agent and working in the same account.

</details>

<details>

<summary>The agent asked for more detail</summary>

Use a clear feature, journey, or scope instead of a short reply.

For example, enter `Checkout`, `Password reset`, or `scan all` instead of `yes` or `ok`.

</details>

<details>

<summary>I switched agents and my previous results are gone</summary>

Each agent keeps its own conversation context.

If you switch agents, run a new search or restate the task in that drawer.

</details>

<details>

<summary>I see an access or authorization error</summary>

Your sign-in session may have expired, or your account may no longer have access to the selected project.

Sign in again, then confirm that the correct project is selected.

</details>


# Administration Control Plane

Centralized governance for enterprise Mozark environments.

The Administration Control Plane is the admin workspace for Mozark Enterprise.

Use it to manage structure, access, infrastructure, integrations, and plan usage from one place.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FBhSMgRUisZ0kDpWPy8to%2FScreenshot%202026-07-02%20at%2012.21.06%E2%80%AFPM.png?alt=media&amp;token=a352767a-629a-40a8-8df5-69d2857f22a9" alt=""><figcaption></figcaption></figure>

### What you can do

* create and manage organizations, applications, and projects
* assign users, roles, and access scope
* govern devices, pools, integrations, and usage limits

### How the hierarchy works

1. Organizations separate business ownership.
2. Applications group products under test.
3. Projects isolate execution, access, and collaboration.

### Explore the Control Plane

* [Dashboard and usage](/administration-control-plane/dashboard-and-usage) — review resource totals, subscription status, and plan usage
* [Organizations](/administration-control-plane/organizations) — manage business entities and default workspaces
* [Applications](/administration-control-plane/applications) — group products under test inside an organization
* [Projects](/administration-control-plane/projects) — create team-specific workspaces for delivery and execution
* [Infrastructure](/administration-control-plane/infrastructure) — control devices, pools, and project mappings
* [User management and roles](/administration-control-plane/user-management-and-roles) — invite users and assign role-based access
* [Integrations and API access](/administration-control-plane/integrations-and-api-access) — manage API keys, webhooks, and external connections
* [Security and governance](/administration-control-plane/security-and-governance) — review authentication, authorization, and audit controls
* [Frequently asked questions](/administration-control-plane/frequently-asked-questions) — get quick answers for rollout and onboarding


# Dashboard and usage

Monitor resource counts, subscription status, and plan consumption across the control plane.

The dashboard shows resource totals and plan consumption for the selected organization.

Use it to review setup, track usage, and act on plan limits.

### Resource summary

#### Applications

Shows the total number of applications in the selected organization.

Use it to confirm product coverage and ownership.

#### Projects

Shows the total number of projects in the selected organization.

Projects are the execution workspaces for teams and releases.

#### Users

Shows the number of users with access to the organization.

This includes admins, contributors, and read-only members.

#### Integrations

Shows the configured external connections.

This can include CI/CD tools, ALM systems, chat platforms, and internal services.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FMYYCFBGJeRvLafc0zQ8V%2FScreenshot%202026-07-02%20at%2012.22.44%E2%80%AFPM.png?alt=media&amp;token=ca292818-08b5-4e26-be67-cb98a3f8fbdc" alt=""><figcaption></figcaption></figure>

### Upgrade your plan

Admins can start a plan upgrade from the dashboard.

New entitlements appear after provisioning completes.


# Organizations

Manage business entities, default workspaces, and organization-level resource visibility.

Organizations are the top-level business entity in Mozark.

Use them to separate teams, departments, subsidiaries, or customer groups.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FXih99WkFOEIlkNauvxGR%2FScreenshot%202026-07-02%20at%2012.25.07%E2%80%AFPM.png?alt=media&amp;token=1c5ac6ab-1a74-4dc0-b768-26986f7fc252" alt=""><figcaption></figcaption></figure>

### Create an organization

Create an organization with these fields:

| Field       | Description           |
| ----------- | --------------------- |
| Name        | Organization name     |
| Description | Optional details      |
| Logo        | Organization branding |
| Metadata    | Custom attributes     |

### Organization status

#### Active

The organization is available for day-to-day work.

Users can access resources and create applications and projects.

#### Archived

The organization remains available for audit history.

Archived organizations are read-only.

You cannot create resources or assign infrastructure.

### Default organization

Mark one organization as the default workspace.

This speeds up onboarding and reduces navigation steps.

### Resource summary

Each organization shows a high-level resource summary.

Review:

* applications
* projects
* users
* recent updates

### Common actions

Admins can:

* edit organization details
* set the default organization
* archive an organization

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2F6UhA9TqH5N3afsMrNJ0J%2FScreenshot%202026-07-02%20at%2012.27.14%E2%80%AFPM.png?alt=media&amp;token=ea6961da-4277-4ce3-a4b7-95d1b51d2514" alt=""><figcaption></figcaption></figure>


# Applications

Organize products under test and manage their lifecycle inside an organization.

Applications group products under test inside an organization.

Use them to keep ownership, reporting, and project structure aligned.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FWmF1EfEWqClKU4WvqIJt%2FScreenshot%202026-07-02%20at%2012.27.49%E2%80%AFPM.png?alt=media&amp;token=27cb4b5c-3f47-438a-8ec0-b08347962319" alt=""><figcaption></figcaption></figure>

### Create an application

Every application belongs to one organization.

| Field        | Description         |
| ------------ | ------------------- |
| Name         | Application name    |
| Description  | Optional details    |
| Organization | Parent organization |

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FlIb8DAvpznK2A8zegSuW%2FScreenshot%202026-07-02%20at%2012.29.29%E2%80%AFPM.png?alt=media&amp;token=b0c1775c-c413-4ab6-a0e5-e0e496cf9383" alt=""><figcaption></figcaption></figure>

### Application status

#### Active

The application is available for active testing work.

#### Default

The application is the primary application for its organization.

#### Archived

The application is retired from active workflows.

Historical data remains available.

### Common actions

Admins can:

* edit application details and metadata
* create projects under the application
* set the default application
* archive the application

### Project structure

Create projects under an application to isolate teams, releases, or product areas.

This keeps execution scope and ownership clear.


# Projects

Create isolated execution workspaces and control collaboration at the project level.

Projects are isolated workspaces for execution and collaboration.

Use them to separate teams, releases, modules, or environments.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FX9Wt7drPiMCsNMwtnC8s%2FScreenshot%202026-07-02%20at%2012.30.11%E2%80%AFPM.png?alt=media&amp;token=02d56133-d7ee-4bf6-968c-d220c130b351" alt=""><figcaption></figcaption></figure>

### Create a project

| Field       | Description        |
| ----------- | ------------------ |
| Name        | Project name       |
| Application | Parent application |
| Description | Optional details   |

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FvLRsFSjXlOfaH2uOMcWu%2FScreenshot%202026-07-02%20at%2012.30.18%E2%80%AFPM.png?alt=media&amp;token=521fbf27-638c-4de2-9ab8-d8c878a685ad" alt=""><figcaption></figcaption></figure>

### Project status

#### Active

The project is available for active work.

#### Default

The project is the primary project for application workflows.

#### Archived

The project is no longer used for active work.

Historical context remains available.

### Access and collaboration

Assign users directly to a project.

Project assignments control:

* visibility
* infrastructure access
* collaboration permissions

### Common actions

Admins can:

* update project details and metadata
* change ownership and configuration
* archive the project when work ends

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FCi00QBvfqxomxvY263OT%2FScreenshot%202026-07-02%20at%2012.30.31%E2%80%AFPM.png?alt=media&amp;token=b88f2f22-4d2c-4c9e-8fff-50757fbb1b98" alt=""><figcaption></figcaption></figure>


# Infrastructure

Govern devices, pools, and project mappings for controlled test execution.

Infrastructure controls which testing resources each project can use.

Use it to manage devices, build pools, and map resources safely.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2F1PUNG8q8rmbV7cum0J1D%2FScreenshot%202026-07-02%20at%2012.31.07%E2%80%AFPM.png?alt=media&amp;token=a42e7308-a711-4ece-9c01-5718af2723fe" alt=""><figcaption></figcaption></figure>

### Devices

Devices are individual testing targets.

Examples include Samsung Galaxy S24, Google Pixel 9, iPhone 16, and iPad Pro.

#### Device details

Each device record shows:

* platform
* OS version
* availability
* owner
* assignment status

### Device pools

Device pools group multiple devices into one managed resource.

Use pools to simplify allocation and reuse across teams.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FGerPs4QwYAGx2Ev15OI2%2FScreenshot%202026-07-02%20at%2012.31.57%E2%80%AFPM.png?alt=media&amp;token=f2394a09-8add-4dad-9719-fa1e3db995c4" alt=""><figcaption></figcaption></figure>

#### Pool scope

Assign a pool at the:

* organization level
* application level
* project level

### Project mappings

Mappings define which projects can use a device or device pool.

Each mapping connects one project to one target resource.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2Fdt3hiRXZ51ajTMEBZ2z1%2FScreenshot%202026-07-02%20at%2012.31.32%E2%80%AFPM.png?alt=media&amp;token=947c447b-608d-4bb6-94c1-29ff79e18dd4" alt=""><figcaption></figcaption></figure>

#### Create a mapping

Each mapping requires:

* a project
* a target type
* a device or pool

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2F5gBeyUrqJja5tRhQ9jhh%2FScreenshot%202026-07-02%20at%2012.32.07%E2%80%AFPM.png?alt=media&amp;token=d7ad003e-9dc5-440c-a3c0-5f36d730fba4" alt=""><figcaption></figcaption></figure>

### Access behavior

Mapped infrastructure appears inside the project workspace.

Users cannot use devices or pools without an explicit mapping.


# User management and roles

Invite users, track membership, and enforce role-based access control.

Use this page to invite users, track invitations, and assign roles.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FRiEFcpDGhvBDZMWdIXuN%2FScreenshot%202026-07-02%20at%2012.32.44%E2%80%AFPM.png?alt=media&amp;token=976ed86f-77e2-48b4-bb01-ef5699aa6460" alt=""><figcaption></figcaption></figure>

### Invite users

To invite users to your organization, click **Invite User**.

Enter one or more email addresses in the dialog.

Separate multiple email addresses with commas.

Then assign a role and send the invitation.

Each invited user receives an email invitation.

They can accept it by signing in or creating an account.

```
user1@company.com, user2@company.com, user3@company.com
```

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2F8rcsNtKVbHvpJ83HJLCl%2FScreenshot%202026-07-02%20at%2012.32.51%E2%80%AFPM.png?alt=media&amp;token=ef9c370e-beff-49f2-8a23-20a3d631a80a" alt=""><figcaption></figcaption></figure>

### Invitation status

#### Pending

The invitation has been sent and is waiting for acceptance.

#### Accepted

The user has joined successfully.

#### Expired

The invitation is no longer valid.

Send a new invitation to restore access.

### Roles

#### Organization admin (`Org.Admin`)

Full organization-level admin access.

Organization admin can:

* manage organizations, applications, and projects
* invite users and assign permissions
* manage integrations and infrastructure
* manage billing and usage
* generate API keys

#### Organization user (`Org.User`)

Standard contributor access.

Organization user can:

* create resources
* modify owned resources
* run testing workflows
* access assigned infrastructure

Organization user cannot manage organization settings, invitations, integrations, or billing.

#### Organization member (`Org.Member`)

Read-only stakeholder access.

Organization member can:

* view assigned resources
* access reports
* participate in reviews

Organization member cannot create resources, modify resources, or manage access.


# Integrations and API access

Connect Mozark to external systems with API keys, webhooks, and supported integrations.

Use this page to connect Mozark with external systems and automation workflows.

### API keys

API keys enable secure programmatic access.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FMfuTIQZpj9lwmacdMiVl%2FScreenshot%202026-07-02%20at%2012.34.19%E2%80%AFPM.png?alt=media&amp;token=92250fe7-331b-4e3b-9f49-ae438fdb8877" alt=""><figcaption></figcaption></figure>

#### Create an API key

| Field       | Description     |
| ----------- | --------------- |
| Name        | Key label       |
| Expiry date | Expiration date |

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FjmtJigR0VG2DIxzDSEly%2FScreenshot%202026-07-02%20at%2012.33.57%E2%80%AFPM.png?alt=media&amp;token=c6b0b47c-bb34-4627-87bf-6e445704a012" alt=""><figcaption></figcaption></figure>

#### Key management best practices

* store keys in a secret manager
* rotate keys regularly
* scope access to the minimum required
* set an expiry date

#### Revoke a key

Revocation takes effect immediately.

A revoked key stops working and cannot be restored.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FiZ438wYsONx5AhHWw6WP%2FScreenshot%202026-07-02%20at%2012.34.33%E2%80%AFPM.png?alt=media&amp;token=bde2664e-c764-4a95-84eb-5cf143dbd8ad" alt=""><figcaption></figcaption></figure>

### Supported integrations

#### CI/CD

* Jenkins
* GitHub Actions
* GitLab CI
* Azure Pipelines

#### ALM

* Jira
* Azure DevOps

#### Communication

* Slack
* Microsoft Teams

#### Identity

* SAML
* SCIM
* OAuth

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FiHL6uZmXEuMBYGHoVdTF%2FScreenshot%202026-07-02%20at%2012.34.48%E2%80%AFPM.png?alt=media&amp;token=e3ac95dd-9a9d-4e07-a22f-edf8a65075c2" alt=""><figcaption></figcaption></figure>

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2F34SR1NQe2yYEa3hZ4EnS%2FScreenshot%202026-07-02%20at%2012.35.00%E2%80%AFPM.png?alt=media&amp;token=f0cd60d9-e1ea-454f-8eec-a32f464b6787" alt=""><figcaption></figcaption></figure>

### Webhooks

Webhooks send event data to external systems.

Common events include test completion, build execution, project creation, and invitation acceptance.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FA6XPNkefwFZxSn7jHOtV%2FScreenshot%202026-07-02%20at%2012.35.23%E2%80%AFPM.png?alt=media&amp;token=fe7b0191-af3e-45b5-8686-c736a9988237" alt=""><figcaption></figcaption></figure>

### MCP integrations

Use the MCP area to manage Model Context Protocol servers.

You can register servers, manage credentials, control tool exposure, and review AI agent activity.

<figure><img src="https://141518431-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE2usr3UxTCpAVSZBlkfy%2Fuploads%2FdCKv0h0tHqFdr5C1rWMK%2FScreenshot%202026-07-02%20at%2012.35.33%E2%80%AFPM.png?alt=media&amp;token=fec5bec3-ba69-4f43-a9e9-6efafa3c4e60" alt=""><figcaption></figcaption></figure>


# Frequently asked questions

Customer-facing answers to common questions about the Administration Control Plane.

The Administration Control Plane gives enterprise teams one place to manage structure, access, infrastructure, integrations, and usage.

Use this page for quick answers during evaluation, onboarding, and rollout.

<details>

<summary>What is the Administration Control Plane?</summary>

It is the centralized admin workspace for Mozark Enterprise.

You use it to manage organizations, applications, projects, users, infrastructure, integrations, and plan usage from one place.

</details>

<details>

<summary>Who should use it?</summary>

It is designed for teams that need centralized control and clear governance.

Typical users include platform owners, IT administrators, QA leaders, and operations teams.

</details>

<details>

<summary>How is the hierarchy structured?</summary>

The model has three levels:

* organizations define business ownership
* applications group products under test
* projects isolate execution and collaboration

See [Organizations](/administration-control-plane/organizations), [Applications](/administration-control-plane/applications), and [Projects](/administration-control-plane/projects).

</details>

<details>

<summary>How does access control work?</summary>

Access is controlled through roles and scoped assignments.

Admins manage invitations, roles, and access across the Control Plane.

See [User management and roles](/administration-control-plane/user-management-and-roles) and [Security and governance](/administration-control-plane/security-and-governance).

</details>

<details>

<summary>Do users get device access automatically?</summary>

No.

Device access is assigned explicitly through devices, pools, and project mappings.

This keeps shared test environments controlled and auditable.

See [Infrastructure](/administration-control-plane/infrastructure).

</details>

<details>

<summary>Can it support multiple teams or business units?</summary>

Yes.

You can separate ownership at the organization level while keeping governance centralized.

This works well for multi-team and multi-organization environments.

</details>

<details>

<summary>Where do I track plan usage and limits?</summary>

Use [Dashboard and usage](/administration-control-plane/dashboard-and-usage).

It shows subscription status, metered usage, and plan limits in one view.

</details>

<details>

<summary>Does it support integrations and API access?</summary>

Yes.

You can manage API keys, webhooks, identity connections, and external integrations from the Control Plane.

See [Integrations and API access](/administration-control-plane/integrations-and-api-access).

</details>


# Security and governance

Apply enterprise controls for authentication, authorization, auditability, and operating model design.

The Control Plane includes enterprise controls for authentication, authorization, and auditing.

Use this page to define a safe operating model for large teams.

### Authentication

Supported sign-in methods include:

* email and password
* SSO
* SAML
* OAuth

### Authorization

Role-based access is enforced at the:

* organization level
* application level
* project level
* infrastructure level

### Audit trail

Administrative actions are logged for review and compliance.

Common events include:

* user invitations
* role changes
* infrastructure assignments
* API key creation
* resource archival

### Recommended operating model

#### Structure resources clearly

Use a predictable hierarchy for ownership and reporting.

```
Organization
├── Application
│   ├── Project A
│   ├── Project B
│   └── Project C
└── Application
    ├── Project X
    └── Project Y
```

#### Limit admin access

Keep admin roles limited to governance owners.

Assign contributors at the project level.

Use member access for stakeholders who only need visibility.

#### Map infrastructure explicitly

Use shared pools for common testing.

Reserve dedicated devices for regulated or high-priority workloads.

Keep project mappings explicit for auditability.


# Mozark MCP Docs

Use Mozark from any MCP-compatible AI assistant.

Connect your AI assistant to Mozark. Then manage tests, generate coverage, and automate devices in plain language.

### Start here

{% content-ref url="/spaces/sKHRrJ2t9qZCDuT5wRkG/pages/b39573e9959875bb91df14c9732688daefc2242b" %}
[Overview](/mcp/mozark-mcp-docs/overview)
{% endcontent-ref %}

{% content-ref url="/spaces/sKHRrJ2t9qZCDuT5wRkG/pages/00ccc7bc83adffba3acdfbb761b159ccffeb0dbe" %}
[Getting started](/mcp/mozark-mcp-docs/getting-started)
{% endcontent-ref %}

{% content-ref url="/spaces/sKHRrJ2t9qZCDuT5wRkG/pages/4105eac809335fb228026c81048696b81b251e79" %}
[Guides](/mcp/mozark-mcp-docs/guides)
{% endcontent-ref %}


# Overview

What the Mozark MCP server does.

The **Mozark MCP Server** connects AI assistants such as Claude, Cursor, VS Code Copilot and Codex to your Mozark workspace using the open [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

Once connected, you can talk to your assistant in plain English and it will use Mozark on your behalf:

> *"Generate negative functional test cases for the checkout flow and save them to the Payments folder."*
>
> *"Run TR-12 on a free Pixel 7 with screen recording on and record step results."*
>
> *"Find duplicate test cases in this project and show me what you'd merge."*

{% hint style="info" %}
**New to MCP?** Think of it as a universal plug. Your AI assistant is the client, Mozark is the server, and the "tools" are the actions the assistant is allowed to take — list devices, create a test case, run a keyword on a phone, and so on. You never call tools yourself; you just describe what you want.
{% endhint %}

## What you can do

| Area                               | What the assistant can do                                                                                                                                      |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Test Case Management (TCM)**     | Create, search, update and organise test cases, folders, requirements, test plans, test runs and bugs.                                                         |
| **AI test generation**             | Generate functional, edge-case or automation test cases from your app screenshots and requirement documents, then save them with AI-provenance tags.           |
| **Knowledge base**                 | Upload screenshots, PRDs, BRDs and user stories so generated tests are grounded in your real app.                                                              |
| **Real-device execution (Optics)** | Execute a test case step-by-step on a real Android or iOS device, verify each step visually, record results into a test run and export a reusable YAML script. |
| **Device automation (Appium)**     | Start raw Appium sessions on Mozark cloud devices — install your APK/IPA, find and tap elements, take screenshots, pull logs and HAR files.                    |
| **Admin Control Panel (ACP)**      | Look up your organisations, projects, apps, users, roles, plan entitlements and usage.                                                                         |

## Navigate the documentation

* **Getting started** — connect your client, sign in, and set your working context in five minutes.
* **Guides** — task-based walkthroughs for the most common workflows.
* **Reference** — every tool grouped by category, with example prompts.
* **Troubleshooting & FAQ** — common errors and how to fix them.

{% content-ref url="/spaces/sKHRrJ2t9qZCDuT5wRkG/pages/00ccc7bc83adffba3acdfbb761b159ccffeb0dbe" %}
[Getting started](/mcp/mozark-mcp-docs/getting-started)
{% endcontent-ref %}




---

[Next Page](https://docs.mozark.ai/llms-full.txt/1)