> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/mobile-testing/creating-mobile-tests.md).
# Creating Mobile Tests
## Quick answer
Go to **Test Cases → New Test Case → AI Assistance**, select **Mobile**, describe the flow, and continue. In the final configuration step, select **Android** or **iOS**, choose a device and app build, then select **Generate & Execute Test Case**.
[Watch the first mobile test walkthrough](https://drive.google.com/file/d/1jEH39OreAYE9eJYf3fpDFFek5wl4M-WO/preview).
## Create an AI-assisted mobile test
### 1. Choose the creation method
1. Open **Test Cases**.
2. Select **New Test Case**.
3. Choose **AI Assistance**.
The creation dialog also offers **Import Files**, **Record & Play**, and **Create manually**. This guide uses AI Assistance because it creates a test from a plain-English scenario.
### 2. Select Mobile
1. Under **Select Target Platform**, choose **Mobile**.
2. Optionally select a **Prerequisite** if another test must establish the app state first.
3. Describe the scenario in the text box.
Example:
```
Launch the sample app. Tap Sign in, enter the approved staging test
account, submit the form, and verify that the Dashboard heading appears.
```
### 3. Write a reliable prompt
Include:
* The starting screen or state
* Each important action in order
* The visible label of the target control
* Test data source or approved fictional value
* At least one expected result
Use mobile language such as **tap**, **swipe**, **scroll**, and **long press** when it matters. Keep one test focused on one user goal.
## Gesture-based mobile scenarios
Mobile journeys often depend on touch gestures that do not have a desktop click equivalent. Name the gesture, its target, its direction when relevant, and the visible outcome that proves it worked.
| Gesture | Example business scenario | What to verify |
| ---------- | --------------------------------------------- | --------------------------------------------------------- |
| **Tap** | Search for a restaurant or product | Results match the entered search term |
| **Swipe** | Move a promotional carousel to the next offer | The banner content or active pagination indicator changes |
| **Scroll** | Browse a long result or catalog list | New list items become visible |
| **Pinch** | Resize a product or food image | The image scale changes without distortion |
| **Zoom** | Inspect a delivery or tracking map | Map content scales and remains responsive |
Example prompt:
```
Open the Home screen. Tap the Search field, enter "Pizza", and verify
matching restaurants appear. Swipe the Featured banner left and verify the
next offer is visible. Scroll down the restaurant list. Open the first item,
pinch the product image, and verify its size changes.
```
Keep each gesture next to a visible verification. This makes a failure explain whether the interaction itself failed or the application did not update afterward.
[Watch the gesture-based mobile testing walkthrough](https://drive.google.com/file/d/1-2B2YsEDjeadues_CsWehVUutsPKdpTk/preview).
{% hint style="info" %}
**Business use case:** Validate carousels, infinite lists, product media, and maps on a real mobile device before a release—areas that a web-only click test cannot cover accurately.
{% endhint %}
### 4. Configure the run
Select **Generate & Execute Test Case** to open the third step.
1. Review the current **Parallel** and **Queued** counts.
2. Under **Select Platform**, choose **Android** or **iOS**.
3. Under **Select Device**, choose a compatible device.
4. Under **App Build**, choose the completed APK or IPA upload.
5. If **Desired Capabilities** appears, expand it and review the values supplied by the selected build. Capability names and types are read-only; `app_url` and `os_type` values are also protected.
6. Select **Generate & Execute Test Case**.
The action remains disabled until the required configuration is complete.
If the selected build has no required capability data, ContextQA displays **Required capabilities are missing in the selected build. Please re-upload your app.** The execution action remains disabled until you select or upload a valid build.
## Review the execution
During and after a run, use the evidence provided by the result screen to answer:
* Did the test use the intended platform, device, and build?
* Which steps passed or failed?
* What was visible when each significant action ran?
* Do the screenshots, logs, and available recording support the result?
If the generated steps do not match the prompt, edit the test before adding it to a regression suite.
## Organize mobile test cases
* Give each case a goal-based title, such as `Android — Sign in with valid account`.
* Add labels such as `mobile`, `android`, `ios`, `smoke`, or the feature name.
* Use the Test Cases filter to focus on **Mobile** records.
* Keep Android- and iOS-specific behavior in separate cases when expected results differ.
## Troubleshooting mobile execution
Why is Generate & Execute Test Case disabled?
Complete the required platform, device, and app-build fields. Also check for a missing-capabilities warning on the selected build. The dialog displays a warning when action is required.
Why did my platform change clear the device and build?
Device and App Build options are platform-specific. Switching between Android and iOS clears the previous selections so an incompatible device or build cannot be reused accidentally.
Why is App Build missing?
Confirm that a completed upload exists for the selected platform. Android requires an APK-type upload; iOS requires an IPA-type upload.
Why did the AI interact with the wrong control?
Make the prompt more specific. Use the exact visible label, identify the screen, and add an expected result immediately after the action. Then review and edit the generated steps before rerunning.
What should I capture when reporting a mobile failure?
Include the build, platform, device, failed step, expected result, actual result, and the relevant screenshot or recording timestamp.
For a complete walkthrough, see [Your first mobile test](/mobile-testing/mobile-testing-tutorial.md).
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://learning.contextqa.com/mobile-testing/creating-mobile-tests.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.