> For the complete documentation index, see [llms.txt](https://docs.mozark.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mozark.ai/no-code-studio/getting-started/author-your-first-test.md).
# 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.
{% 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:
| 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.
## 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.
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.
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.
## 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.
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**.)
{% 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**.
* 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.
---
# 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
If you need additional information that is not directly available in this page, you can query the documentation 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/no-code-studio/getting-started/author-your-first-test.md?ask=&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.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
