For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Discord
DocsAPI Reference
DocsAPI Reference
  • Get Started
    • Welcome
    • Introduction
    • Quick Start
  • Run
    • Run Videos
    • Run Mode
    • Viewport Size
    • Preparation Test
    • Pull Request Testing
    • Production Monitoring
    • Group Webhooks
    • Run Troubleshooting
  • Auth
    • Test Credentials
    • API Keys
    • Agent Mail Inboxes
    • HTTP Basic Auth
    • Auth Troubleshooting
  • Mobile
    • Overview
    • App Uploads
    • Expo EAS
    • GitHub Actions
  • Integrations
    • Vercel
    • Coolify
    • Custom Infrastructure
    • Slack
    • Discord
  • Guides
    • Testing Staging Environment
  • CLI
    • Getting Started
    • Local Development
    • Agentic Usage
  • AI
    • LLMs
LogoLogo
Discord
On this page
  • Prerequisites
  • Required environment variables
  • Instructions for AI agents
  • Configure an iOS Simulator build
  • Add the EAS workflow
  • GitHub PR comments and checks
  • Example repository
  • Troubleshooting
  • The build is not a simulator app
  • TesterArmy warns that GitHub integration is not configured / TesterArmy cannot create a PR comment
  • Related docs
Mobile

Expo EAS

||View as Markdown|
Was this page helpful?
Edit this page
Previous

App Uploads

Next

GitHub Actions

Built with

Run TesterArmy mobile tests from Expo EAS workflows by uploading the EAS iOS Simulator build and triggering a remote test group.

Prerequisites

Before you set it up, make sure you have already:

  • Created mobile project (can be without uploaded app)
  • Created at least one mobile test

Also make sure that you have configured Expo EAS with Github

Required environment variables

Environment variableDescription
TESTERARMY_API_KEYAPI key for TesterArmy
TESTERARMY_PROJECT_IDProject ID for project you want to run tests on
TESTERARMY_GROUP_IDGroup ID for group you want to run tests on

These values can be found in the TesterArmy Dashboard:

  • API key - Profile → API Keys
  • Project ID - Project Settings
  • Group ID - Test Tab, then click on three dots on the group you want to run tests on and copy the ID

Set TESTERARMY_API_KEY as an EAS secret or sensitive environment variable. Do not commit it, and do not expose it through an EXPO_PUBLIC_* environment variable.

Instructions for AI agents

Below you will find instructions for AI agent to set up EAS integration with TesterArmy for you.

Setup Expo EAS integration with TesterArmy
You are working in an Expo app repository. Add TesterArmy mobile testing through Expo EAS workflows. Before editing files: * Inspect the existing `eas.json`, `.eas/workflows`, `package.json`, and package manager lockfile. * Do not overwrite an existing EAS workflow. Create a new workflow file or make the smallest safe edit. * Do not hard-code secrets, API keys, project IDs, or group IDs in committed files. * Use the repository’s existing package manager style when adding commands. Implement this setup: 1. Ensure `eas.json` has an iOS Simulator build profile for TesterArmy. Prefer the profile name `testerarmy-ios-simulator`. If the project already has a simulator build profile, reuse it and keep the workflow profile name in sync. 2. The build profile must set `ios.simulator` to `true`. TesterArmy needs a `.app` simulator build, not an `.ipa` device build. 3. Create `.eas/workflows/testerarmy-mobile-tests.yml` if it does not already exist. 4. The workflow should support `push` to `main`, `pull_request` to `main`, and `workflow_dispatch`. 5. The workflow should read these values from EAS environment variables: * `TESTERARMY_API_KEY` * `TESTERARMY_PROJECT_ID` * `TESTERARMY_GROUP_ID` 6. The workflow should build the iOS Simulator app with EAS. 7. The workflow should download the build artifact with `eas/download_build`. 8. The workflow should upload the downloaded `.app` artifact with `npx --yes testerarmy@latest upload-app`. 9. The workflow should run the saved TesterArmy group with the uploaded app ID. 10. The workflow should pass commit SHA for GitHub check reporting when the EAS/GitHub context provides it. 11. The workflow should pass PR number only when the workflow is running for a pull request. 12. The workflow should delete the uploaded app after the run. Use this workflow as the baseline and adapt it to the repository if needed: ```yaml name: TesterArmy Mobile Tests on: push: branches: - main pull_request: branches: - main workflow_dispatch: {} jobs: build_ios: name: Build iOS Simulator app type: build environment: preview params: platform: ios profile: testerarmy-ios-simulator upload_app: name: Upload app to TesterArmy needs: [build_ios] environment: preview outputs: app_id: ${{ fromJSON(steps.upload_app.outputs.upload_result).uploadedAppId }} steps: - uses: eas/checkout - uses: eas/download_build id: download_build with: build_id: ${{ needs.build_ios.outputs.build_id }} extensions: - app - name: Upload app id: upload_app run: | set -euo pipefail APP_PATH="${{ steps.download_build.outputs.artifact_path }}" mkdir -p .testerarmy npx --yes testerarmy@latest upload-app \ --app-path "$APP_PATH" \ --project "$TESTERARMY_PROJECT_ID" \ --output .testerarmy/upload.json set-output upload_result "$(tr -d '\n' < .testerarmy/upload.json)" run_tests: name: Run TesterArmy tests needs: [upload_app] environment: preview steps: - uses: eas/checkout - name: Run tests run: | set -euo pipefail APP_ID="${{ needs.upload_app.outputs.app_id }}" COMMIT_SHA="${{ github.sha }}" EVENT_NAME="${{ github.event_name }}" PR_NUMBER="${{ github.event.pull_request.number || '' }}" TIMEOUT_MS="1800000" POLL_INTERVAL_SECONDS="10" mkdir -p .testerarmy args=( ci --group "$TESTERARMY_GROUP_ID" --project "$TESTERARMY_PROJECT_ID" --app-id "$APP_ID" --commit-sha "$COMMIT_SHA" --timeout "$TIMEOUT_MS" --poll-interval-seconds "$POLL_INTERVAL_SECONDS" --output .testerarmy/ci-result.json --delete-app-after-run ) if [ "$EVENT_NAME" = "pull_request" ] && [ -n "$PR_NUMBER" ]; then args+=(--pr-number "$PR_NUMBER") fi npx --yes testerarmy@latest "${args[@]}" ``` Use these command shapes: ```bash npx --yes testerarmy@latest upload-app \ --app-path "$APP_PATH" \ --project "$PROJECT_ID" \ --output .testerarmy/upload.json ``` ```bash npx --yes testerarmy@latest ci \ --group "$GROUP_ID" \ --project "$PROJECT_ID" \ --app-id "$APP_ID" \ --commit-sha "$COMMIT_SHA" \ --timeout "$TIMEOUT_MS" \ --poll-interval-seconds "$POLL_INTERVAL_SECONDS" \ --output .testerarmy/ci-result.json ``` If a PR number is available, append: ```bash --pr-number "$PR_NUMBER" ``` If cleanup is enabled, append: ```bash --delete-app-after-run ``` After editing: * Show the user which files changed. * Tell the user to configure `TESTERARMY_API_KEY`, `TESTERARMY_PROJECT_ID`, and `TESTERARMY_GROUP_ID` in their EAS environment. * Tell the user which EAS workflow command to run. * Do not run the real TesterArmy CLI or EAS build unless the user explicitly asks you to. Finish by summarizing the files changed and the manual test command.

Configure an iOS Simulator build

TesterArmy requires an iOS Simulator build profile in EAS. Add the following snippet to your eas.json file:

eas.json
1{
2  "build": {
3    "testerarmy-ios-simulator": {
4      "ios": {
5        "simulator": true
6      }
7    }
8  }
9}

Add the EAS workflow

Basic
Fingerprint + Repack

Here is an example workflow file that:

  1. Builds the app for iOS Simulator
  2. Uploads the app to TesterArmy
  3. Runs the tests
  4. Deletes the app from TesterArmy, after the tests are completed
.eas/workflows/testerarmy-mobile-tests.yml
1name: TesterArmy Mobile Tests
2
3on:
4  push:
5    branches:
6      - main
7  pull_request:
8    branches:
9      - main
10  workflow_dispatch: {}
11
12jobs:
13  build_ios:
14    name: Build iOS Simulator app
15    type: build
16    environment: preview
17    params:
18      platform: ios
19      profile: testerarmy-ios-simulator
20
21  upload_app:
22    name: Upload app to TesterArmy
23    needs: [build_ios]
24    environment: preview
25    outputs:
26      app_id: ${{ fromJSON(steps.upload_app.outputs.upload_result).uploadedAppId }}
27    steps:
28      - uses: eas/checkout
29
30      - uses: eas/download_build
31        id: download_build
32        with:
33          build_id: ${{ needs.build_ios.outputs.build_id }}
34          extensions:
35            - app
36
37      - name: Upload app
38        id: upload_app
39        run: |
40          set -euo pipefail
41
42          APP_PATH="${{ steps.download_build.outputs.artifact_path }}"
43
44          mkdir -p .testerarmy
45
46          npx --yes testerarmy@latest upload-app \
47            --app-path "$APP_PATH" \
48            --project "$TESTERARMY_PROJECT_ID" \
49            --output .testerarmy/upload.json
50
51          set-output upload_result "$(tr -d '\n' < .testerarmy/upload.json)"
52
53  run_tests:
54    name: Run TesterArmy tests
55    needs: [upload_app]
56    environment: preview
57    steps:
58      - uses: eas/checkout
59
60      - name: Run tests
61        run: |
62          set -euo pipefail
63
64          APP_ID="${{ needs.upload_app.outputs.app_id }}"
65          COMMIT_SHA="${{ github.sha }}"
66          EVENT_NAME="${{ github.event_name }}"
67          PR_NUMBER="${{ github.event.pull_request.number || '' }}"
68          TIMEOUT_MS="1800000"
69          POLL_INTERVAL_SECONDS="10"
70
71          mkdir -p .testerarmy
72
73          args=(
74            ci
75            --group "$TESTERARMY_GROUP_ID"
76            --project "$TESTERARMY_PROJECT_ID"
77            --app-id "$APP_ID"
78            --commit-sha "$COMMIT_SHA"
79            --timeout "$TIMEOUT_MS"
80            --poll-interval-seconds "$POLL_INTERVAL_SECONDS"
81            --output .testerarmy/ci-result.json
82            --delete-app-after-run
83          )
84
85          if [ "$EVENT_NAME" = "pull_request" ] && [ -n "$PR_NUMBER" ]; then
86            args+=(--pr-number "$PR_NUMBER")
87          fi
88
89          npx --yes testerarmy@latest "${args[@]}"

GitHub PR comments and checks

When your workflow is triggered by a pull request, TesterArmy will create a GitHub check and comment on the PR.

When workflow is triggered by a commit (eg. on push to main), TesterArmy will create a GitHub check on the commit.

To enable this, you need to configure your TesterArmy project with your GitHub repository. You can do it in Integrations Tab in project.

Example repository

You can find a working example repository here.

Troubleshooting

The build is not a simulator app

TesterArmy requires an iOS Simulator build to run tests. If you are using a physical device build, you need to build a simulator build first.

Ensure you are building release build - not debug build.

TesterArmy warns that GitHub integration is not configured / TesterArmy cannot create a PR comment

If you are seeing this error, it means that your TesterArmy project has no GitHub integration configured. You can configure it in Integrations Tab in project.

Related docs

  • App Uploads
  • GitHub Actions