# Tutorial: Your First Mobile Test

{% hint style="info" %}
**Who is this for?** Testers and SDETs new to mobile testing in ContextQA. You will upload an app, create a test case with AI, run it on a real device, and review the results — the same workflow as web testing, adapted for mobile.
{% endhint %}

Mobile testing in ContextQA runs on a cloud-hosted farm of physical Android and iOS devices. Instead of pointing to a URL, you upload an APK or IPA, select a device, and describe the test in plain English. The AI generates steps, executes them on the real device, and captures video, screenshots, and AI logs for every run.

In this tutorial you will:

1. Upload an Android APK to ContextQA
2. Create a mobile test case using the AI assistant
3. Select a device and execute the test
4. Review per-step results, video, and AI logs

**End result:** A passing mobile test case that logs into your Android app on a real device, with a full evidence package — video recording, per-step screenshots, and AI confidence logs.

> **Note:** This tutorial uses an Android APK. The workflow for iOS is identical except you upload an IPA file and must first upload a provisioning profile. See [Prerequisites](/mobile-testing/prerequisites.md) for iOS-specific requirements.

## Prerequisites

* A ContextQA account with at least one workspace ([sign up](https://accounts.contextqa.com/onboard))
* An Android `.apk` file for the app you want to test (a debug build targeting API level 21 or higher)
* A clear idea of one user flow to automate (for example, login, search, or form submission)
* Familiarity with [creating web test cases](/web-testing/creating-test-cases.md) — mobile testing follows the same concepts with a different entry point

***

## Step 1: Upload your APK

Before you can run a mobile test, ContextQA needs your app binary stored in the workspace.

1. In the left sidebar, click the **Test Development** icon.
2. Click the **Uploads** tab.
3. Click the **Upload** button in the top-right area.
4. Select your `.apk` file from your local filesystem.
5. Rename the file to something descriptive — for example, `myapp-v1.2-debug.apk`. Including the version number makes it easier to manage multiple builds later.
6. Click **Upload** to confirm.

ContextQA validates the file, detects it as an Android binary, and adds it to the uploads list.

**Verify it worked:** The uploads list shows your file with an Android platform icon, a **Completed** status, and the file size.

{% hint style="info" %}
**Tip:** You can upload multiple versions of the same app over time. Open the file details panel and click **Upload New Version** to add a newer build without losing the previous one. See [Uploading apps](/mobile-testing/uploading-apps.md) for version management details.
{% endhint %}

***

## Step 2: Create a mobile test case with AI

1. Navigate back to **Test Development** and click the **+** button to create a new test case.
2. Select **Start with AI Assistant**.
3. When prompted for the target platform, select **Mobile Application**.

   Selecting Mobile Application changes the test case context — instead of entering a URL, you will configure a device and app build when running the test.
4. Enter a plain-English description of the user flow you want to test. Be specific about the actions and verifications. For example:

   ```
   Open the app and log in with username doctor@example.com and
   password Test1234. Verify that the Dashboard screen loads and
   the welcome message is visible.
   ```

   **Tips for writing effective mobile test prompts:**

   * Name the exact fields, buttons, and screen labels as they appear in your app
   * Use natural gesture language when needed: "swipe left on the card", "scroll down to the footer", "long press the message"
   * Include at least one verification step ("verify", "confirm", "check that")
   * Keep each test focused on a single user flow
5. Click **Generate & Execute Test Case**.

***

## Step 3: Select a device and run the test

After clicking **Generate & Execute Test Case**, a device configuration dialog appears.

1. Select the platform: **Android**.
2. Open the **App Build** dropdown and select the APK you uploaded in Step 1.
3. Select the target device from the available device list. For example, **Pixel 7 — Android 14**.

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>If the <strong>App Build</strong> dropdown is empty, you have not uploaded an APK yet. Click the <strong>Go to Upload Page</strong> link in the dialog to navigate to the uploads section and complete Step 1.</p></div>
4. Review the concurrency indicators at the top of the dialog:

   | Indicator                | Meaning                                         |
   | ------------------------ | ----------------------------------------------- |
   | **Parallel X/Y** (green) | X tests running out of Y available device slots |
   | **Queued X/Y** (orange)  | X tests waiting in queue                        |

   If all parallel slots are occupied, the button label changes to **Skip and continue**. Your test queues and starts automatically when a slot frees up.
5. Click **Start Execution**.

ContextQA installs the app on the selected device and begins executing the AI-generated steps. The left panel shows a real-time execution log with per-step status updates. The right panel displays a live view of the device screen.

**Verify it worked:** Steps turn green as they pass. A typical 5–8 step login test completes in under 60 seconds.

***

## Step 4: Review the generated test steps

When execution completes, click **Back to Test Case**.

The AI-generated prompt has been converted into a structured Spark script — ContextQA's internal step format. Each step is visible and editable in the step editor.

Review the steps to confirm they match your intent:

| Step | Action                                       |
| ---- | -------------------------------------------- |
| 1    | Navigate to the app's login screen           |
| 2    | Type `doctor@example.com` in the Email field |
| 3    | Type `Test1234` in the Password field        |
| 4    | Tap the **Sign In** button                   |
| 5    | Verify that the Dashboard screen loads       |
| 6    | Verify that the welcome message is visible   |

If any step does not match your intent, click the step to edit its description. You can also reorder, delete, or add steps before running again.

***

## Step 5: Review execution results

Navigate to the **Run History** page for the test case. Click the most recent execution to open the detailed results.

### AI logs

The **AI Logs** section provides the most detailed view of what happened:

* **Per-step status** — pass or fail indicator for each step
* **Screenshots** — captured at the exact moment each step executed
* **AI confidence scores** — how confidently the AI identified each UI element
* **Assertion results** — expected versus actual values for verification steps

### Video recording

Click the **Video** tab to watch a full playback of the device session. Use this to:

* Confirm the app navigated through the correct screens
* Spot timing or animation issues not visible in screenshots
* See the full flow in sequence, which helps diagnose failures caused by earlier steps

### What to check

| Result                              | What it means                                                                                |
| ----------------------------------- | -------------------------------------------------------------------------------------------- |
| All steps pass                      | Your mobile test case is working — the login flow on this device is verified                 |
| A step fails on element interaction | The AI could not find the expected element — check the screenshot to see what was on screen  |
| A step fails on verification        | The expected text or screen did not appear — the app may have navigated to a different state |

***

## Summary

You built and ran your first mobile test in five steps:

1. **Uploaded an APK** to ContextQA's workspace via the Uploads section
2. **Created a mobile test case** using the AI assistant with a plain-English prompt
3. **Selected a device** from the cloud device farm and started execution
4. **Reviewed the generated steps** in the step editor to confirm accuracy
5. **Inspected the results** — per-step screenshots, AI logs, and video recording

One test case now validates a mobile login flow on a real Android device, with a full evidence package captured automatically.

## Next steps

* **Test on iOS:** Upload an IPA file and a provisioning profile, then follow the same workflow. See [Prerequisites](/mobile-testing/prerequisites.md) for iOS-specific signing requirements.
* **Add more gestures:** Create test cases that use swipe, scroll, long press, pinch, and zoom. Write natural gesture language in your prompts — the AI maps them to the correct mobile actions. See [Supported gestures](/mobile-testing/creating-mobile-tests.md#supported-gestures).
* **Run across multiple devices:** Create a test plan with several device/OS entries to validate your app on Android 13, Android 14, iOS 16, and iOS 17 in a single orchestrated run. See [Mobile test plans](/mobile-testing/mobile-test-plans.md).
* **Schedule nightly regression:** Add your mobile test cases to a test suite, attach it to a test plan, and configure a daily schedule. See [Mobile test plans — scheduling](/mobile-testing/mobile-test-plans.md#scheduling-automated-runs).
* **Combine with data-driven testing:** Use a test data profile to run the same login test with multiple user roles — one test case, four credential sets, four independent results. See [Tutorial: Data-driven testing](/web-testing/data-driven-testing-tutorial.md).

## Related pages

* [Mobile Testing Overview](/mobile-testing/mobile-testing.md) — capabilities and key concepts for mobile testing
* [Prerequisites](/mobile-testing/prerequisites.md) — APK/IPA requirements, iOS provisioning profiles, device farm access
* [Uploading Apps](/mobile-testing/uploading-apps.md) — upload workflow, version management, file size limits
* [Creating Mobile Tests](/mobile-testing/creating-mobile-tests.md) — full reference for test creation, gestures, and execution
* [Mobile Test Plans](/mobile-testing/mobile-test-plans.md) — multi-device plans, concurrency, environments, scheduling
* [Quickstart Guide](/getting-started/quickstart.md) — your first web test in five minutes

{% hint style="info" %}
**Test your Android and iOS apps on real devices — no code required.** [**Start Free Trial →**](https://app.contextqa.com/register) — Or [**Book a Demo →**](https://contextqa.com/book-a-demo/) to see mobile testing with your app.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

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

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

```
GET https://learning.contextqa.com/mobile-testing/mobile-testing-tutorial.md?ask=<question>
```

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

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