# Uploading Apps (APK & IPA)

{% hint style="info" %}
**Who is this for?** SDETs and QA managers who need to upload Android APK or iOS IPA files to ContextQA before running mobile tests on the device farm.
{% endhint %}

ContextQA stores your app binaries centrally in the **Uploads** section of Test Development. Once uploaded, an app build can be referenced by any test case or test plan in the workspace — there is no need to re-upload the same binary for each test.

## Supported File Types

| File Type | Platform | Notes                                                          |
| --------- | -------- | -------------------------------------------------------------- |
| `.apk`    | Android  | Universal APK; App Bundles (`.aab`) are not supported directly |
| `.ipa`    | iOS      | Ad-hoc or enterprise signed; App Store IPAs will not install   |

In addition to mobile app files, the Uploads section also accepts Excel documents (`.xlsx`, `.xls`) for data-driven testing. The platform auto-detects the file type on upload.

## Upload Workflow

### Step 1 — Navigate to Uploads

Go to **Test Development** from the main workspace navigation, then click on the **Uploads** tab. This section displays all previously uploaded files alongside their type and upload date.

### Step 2 — Initiate the Upload

Click the **Upload** button in the top-right area of the Uploads section. A file picker dialog opens.

### Step 3 — Select Your File

Choose your `.apk` or `.ipa` file from your local filesystem. The platform accepts a single file per upload operation.

### Step 4 — Rename the File (Optional)

Before confirming, you can rename the file to something descriptive. Using a name that includes the app name and version makes it easier to manage multiple builds over time. For example: `clinic-app-v2.4.1-debug.apk` or `myapp-adhoc-20250315.ipa`.

### Step 5 — Confirm the Upload

Click **Upload** to complete the process. ContextQA:

1. Validates the file extension and structure
2. Auto-detects the platform type (Android or iOS) and displays it alongside the entry
3. Stores the file securely in the workspace's storage

The uploaded file appears immediately in the Uploads list.

## File Size Limits

ContextQA supports app binaries up to **500 MB** per upload. If your binary exceeds this limit:

* For Android: Use ProGuard/R8 to shrink the APK, or produce a size-optimized APK from an App Bundle using `bundletool` with a specific ABI filter
* For iOS: Strip unused architectures and assets before packaging the IPA

## Using an Uploaded App in a Test Case

When creating or executing a mobile test case, a device configuration dialog prompts you to select the app build:

1. In the device configuration panel, open the **App Build** dropdown.
2. Select the app by the name you gave it during upload.
3. The platform will install that specific binary on the selected device before test execution begins.

## Using an Uploaded App in a Test Plan

When adding a device configuration to a test plan, the same **App Build** dropdown appears in the machine/device setup dialog. Each device entry in a test plan can reference a different app build — for example, you might run an older build on one device configuration and the latest build on another.

## Managing Uploaded App Versions

### Viewing Uploads

All uploads are listed in **Test Development → Uploads** with the following columns:

| Column            | Description                                                                            |
| ----------------- | -------------------------------------------------------------------------------------- |
| **Name**          | File name with a platform icon (Android or iOS). Click to open the File Details panel. |
| **File Path**     | The latest version name and a copy-path icon.                                          |
| **Last Modified** | Date the upload was last updated. Sortable.                                            |
| **Folder Size**   | Total size across all versions (human-readable, e.g., "1.5 MB").                       |
| **Status**        | Upload status of the latest version (Completed, In Progress, or Failed).               |

### File Details Panel

Click any upload name to open the **File Details** side panel. This panel shows:

* **File header** — File name, platform icon, folder size, and last modified date.
* **File settings** — Versioning and overwrite toggles (see below).
* **Default version** — The version marked as default, with its date, uploader name, and file size.
* **Upload New Version** button — Upload a new version of the same app binary.
* **Version History** tab — Browse all versions with pagination.
* **Audit History** tab — View a log of changes made to this upload.
* **Copy Path** and **Delete File** action buttons.

### Version Management

ContextQA supports built-in version management for uploaded files. Each upload can store multiple versions, with controls for which version is used by default.

#### Versioning and Overwrite Settings

Two toggles in the File Details panel control how new uploads behave:

| Toggle                      | Description                                                                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Versioning**              | When enabled (default), uploading a file with the same name creates a new version. When disabled, new uploads replace the existing file. |
| **Overwrite existing file** | Automatically set based on the Versioning toggle. When Versioning is on, Overwrite is off (and vice versa).                              |

> **Note**: When versioning is disabled, an info message appears: "Versioning is disabled for this file. Same-name uploads cannot create new versions."

#### Version History

The **Version History** tab in the File Details panel lists all versions of the upload. Each version entry shows:

* **Version name** — Editable inline (click the edit icon to rename).
* **Default badge** — Indicates which version is currently set as the default.
* **Date** — When the version was uploaded.
* **Uploader name** — The team member who uploaded this version.
* **File size** — Size of the individual version file.

Use the three-dot menu on each version row for these actions:

| Action               | Description                                               |
| -------------------- | --------------------------------------------------------- |
| **Set as Default**   | Mark this version as the default used in test executions. |
| **Unset as Default** | Remove the default designation from this version.         |
| **Download**         | Download this specific version to your local machine.     |

#### Uploading a New Version

1. Open the File Details panel for the upload.
2. Click **Upload New Version**.
3. Select the new file from your local filesystem.
4. A progress bar appears during upload. Once complete, the new version appears in the Version History list.

### Copying the App Reference

Click the **Copy Path** button in the File Details panel (or the copy icon in the uploads list) to copy the file path of the selected version to your clipboard. This identifier can be pasted into environment configuration or shared with team members who need to reference the same build.

### Deleting an Upload or Version

* **Delete a specific version** — In the File Details panel, select a version row, then click **Delete File**.
* **Delete the entire upload** — In the File Details panel with no version selected, click **Delete Folder**.

> **Warning**: Deleting a build or version that is currently referenced by an active test case or test plan causes those tests to fail at execution time when the platform attempts to install the app. Confirm that no active test plans or scheduled runs reference it before deleting. Replace references with a newer build first, then delete the old one.

## Referencing Uploads via MCP

You can query the list of available uploads programmatically using the ContextQA MCP server. The `get_test_cases` and `get_environments` tools provide context on how builds are associated. For device and build selection during programmatic test execution:

```python
# MCP tool call — list available test devices to match with an uploaded build
get_test_devices(query="android")

# MCP tool call — execute a test case (device + app build are configured on the test case itself)
execute_test_case(test_case_id=1234)
```

When executing test plans programmatically, the device and app build configuration is stored on the test plan object and applied automatically:

```python
# MCP tool call — run a test plan (device configurations, including app builds, are pre-set)
execute_test_plan(test_plan_id=56)
```

## Next Steps

With your app binary uploaded, you are ready to create test cases that target it. See [Creating Mobile Tests](https://learning.contextqa.com/mobile-testing/creating-mobile-tests) for the full test creation and execution workflow.

{% hint style="info" %}
**Test iOS and Android in parallel — same workflow as web.** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See ContextQA automate mobile testing for your iOS and Android apps.
{% endhint %}