> 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/mobile-test-plans.md).
# Mobile Test Plans
## Quick answer
A **test suite** groups related mobile cases. A **test plan** combines suites with machine or device configuration, execution settings, and scheduling. Stabilize individual cases first, then promote them into a suite and plan.
[Watch the mobile suites and test plans walkthrough](https://drive.google.com/file/d/1nS5FIKuOMw2oHlaWSan2n-J6WpYy-YYi/preview).
## Create a mobile test suite
1. Open **Plans**. The Test Suites page lists suite name, platform, case count, latest result, dates, folder, and actions.
2. Select **Create Test Suite**.
3. Enter a goal-based **Suite Name**, such as `Mobile — Authentication smoke`.
4. Optionally select a folder, prerequisites, and labels.
5. Expand the configuration options if needed.
6. Under **Select Target Platform**, choose **Mobile**.
7. Add a description explaining the scope and exclusion criteria.
8. Select **Add Test Cases**, choose the intended mobile cases, and finish creation.
Use **Skip & create empty** only when you intentionally want to populate the suite later.
## Decide how to organize suites
Use one primary organizing dimension per suite:
| Strategy | Example | Best for |
| -------- | ----------------------------- | ---------------------------- |
| Feature | `Mobile — Authentication` | Ownership and failure triage |
| Risk | `Mobile — Release smoke` | Fast release gates |
| Platform | `Android — Regression` | Platform-specific behavior |
| Cadence | `Mobile — Nightly regression` | Scheduled execution |
Avoid one oversized suite that mixes unrelated features, platforms, and release gates.
## Create a test plan
1. Open **Plans → Test Plans**.
2. Select **New Test Plan**.
3. In **Create Test Plan**, enter the name, labels, and description.
4. Configure dashboard visibility and notifications as required.
5. Choose the viewport and resolution appropriate for the plan.
6. Select **Next**.
7. In **Test Machines & Suites Selection**, select **Add Test Suites**.
8. Find and add the mobile suite.
9. Select the suite, then select **Add Machine/Device**.
10. Configure the compatible device and app build required by the mobile suite.
11. Continue to **Test Plan Settings**, review the configuration, and create the plan.
The current plan wizard has three stages: **Create Test Plan**, **Test Machines & Suites Selection**, and **Test Plan Settings**.
### Map Android and iOS suites explicitly
For a combined mobile release plan, map each suite to a compatible device and build:
| Suite | Device configuration | App build |
| ------------------------- | --------------------------------------- | ------------- |
| `Android — Release smoke` | Supported Android device, such as Pixel | Candidate APK |
| `iOS — Release smoke` | Supported iOS device, such as iPhone | Candidate IPA |
A single Mobile suite can contain cross-platform intent, but separate Android and iOS suites make platform ownership, build selection, and failure triage clearer when behavior differs. Add both suites to one plan when stakeholders need a combined release report.
{% hint style="info" %}
**Business use case:** Run the Android and iOS release smoke suites together while preserving the exact build and device used for each platform's evidence.
{% endhint %}
## Run or schedule the plan
The Test Plans list provides actions for:
* **Run** — start an on-demand execution.
* **Schedule** — configure recurring execution.
* **Reports** — open results when a run exists.
* **Clone** — copy a plan as a starting point for another configuration.
Before running, confirm that every mobile suite has an appropriate device and completed app build.
The Schedules view supports one-time and recurring cadences, including hourly, daily, weekly, monthly, and yearly schedules. Confirm the displayed next-run time and workspace timezone before activating a schedule.
## Review plan results
Use the report to compare outcomes by suite, test case, and configured device. For a failure, capture:
* Plan and run name
* Suite and test-case ID
* Platform, device, and app build
* Failed step and expected result
* Screenshot, logs, and available video
## Maintenance recommendations
* Include platform and purpose in suite and plan names.
* Keep smoke and full-regression plans separate.
* Update the app build deliberately; do not silently replace a build used for release evidence.
* Remove flaky cases from release gates until the failure cause is understood.
* Review scheduled plans after device-support or build-distribution changes.
## Frequently asked questions
Should Android and iOS use one suite?
Use one suite when the test intent and expected behavior are the same. Split them when steps, permissions, labels, or expected outcomes differ by platform.
Why is Add Machine/Device disabled?
Add at least one test suite first, then select the suite that needs a machine or device configuration.
Why is Reports unavailable?
Reports is disabled when the plan has no completed run. Run the plan first, then return to the Test Plans list.
What should a mobile release plan contain?
Include stable cases for the supported platform/device matrix, the exact candidate build, clear pass criteria, and notifications for the people responsible for release decisions.
## Related documentation
[Mobile testing overview](/mobile-testing/mobile-testing.md) · [Create and run a mobile test](/mobile-testing/creating-mobile-tests.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/mobile-test-plans.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.