Working with CI/CD

Reflect Suite Execution API: Trigger Tests with Specific Mobile Builds

This endpoint allows you to run all tests in a suite against a specific uploaded mobile app build.It’s typically used immediately after uploading a new .apk or .ipa via the Reflect Uploads API - enabling full end-to-end regression testing of your latest compiled mobile app directly from your CI/CD pipeline.

Overview

In a CI/CD workflow, you can:

  1. Upload a new mobile build file via https://uploads-api.reflect.run.

  2. Trigger test execution on Reflect using that uploaded build’s ID via this endpoint.

This enhancement ensures that users can dynamically select which build file to use when executing an existing mobile test suite, without needing manual updates in the Reflect web app.

  1. Upload Your Build to Reflect Grid

    (Prerequisite from the previous API documentation)

    Endpoint: POST https://uploads-api.reflect.run/v1/mobile/builds?name=<build-name>

    Result: Returns a build file ID (e.g., 61f23ce6-64bd-4b90-b9fa-00c265297646).You’ll use this build file ID in the next step.

  2. Trigger Test Suite Execution with Specific Build

    Method: POST

    URL: https://api.reflect.run/v1/suites/<suite-slug-or-id>/executions

Path Parameter

  • suite-slug-or-id (required):

    The identifier of the suite you want to execute.

    • Example: "triggerviaapi".

    • You can find this value in the Reflect web app or by calling the GET /v1/suites endpoint.

Headers

Header

Description

Required

X-API-KEY

Your Reflect API key

✅

Content-Type

Must be application/json

✅

Request Body

mobileAppOverrides object defines which app build file(s) should be used when executing the suite.

  • Key. The app name originally assigned within the Reflect web app (must match exactly).

  • Value. The build file ID returned from the Uploads API.

Example JSON

{
  "mobileAppOverrides": {
    "app-release.apk": "61f23ce6-64bd-4b90-b9fa-00c265297646"
  }
}

In this example:

  • "app-release.apk" is the existing app name in Reflect (as configured in your test suite’s mobile run settings).

  • "61f23ce6-64bd-4b90-b9fa-00c265297646" is the ID of the newly uploaded build you want to run tests against.

If your CI/CD process compiles a new version (e.g., staging-app-release.apk), you just upload that file, grab its build ID, and pass it as the value for the "app-release.apk" key.

Example cURL Command

curl -X POST \
  -H "X-API-KEY: JE8lSj86s240XZxHRmOSTaJ9FDJ1CNXwa53YRfKq" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "mobileAppOverrides": {
      "app-release.apk": "61f23ce6-64bd-4b90-b9fa-00c265297646"
    }
  }' \
  "https://api.reflect.run/v1/suites/triggerviaapi/executions"

Example Response (202 Accepted)

{
  "executionId": "8b5c2d62-d721-47c8-965d-331ac1b002c1",
  "suite": "triggerviaapi",
  "status": "queued",
  "startedAt": null
}

Once triggered, Reflect queues the test run and executes it using the specified uploaded build.You can poll for status or view progress directly in the Reflect web app.

Typical CI/CD Flow

Example: GitHub Actions

jobs:
  regression-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Upload latest mobile build to Reflect
        id: upload
        run: |
          BUILD_NAME="staging-app-release.apk"
          FILE="build/app/outputs/flutter-apk/app-release.apk"
          UPLOAD_RESPONSE=$(curl -s -X POST \
            -H "X-API-KEY: ${{ secrets.REFLECT_API_KEY }}" \
            -H "Content-Type: application/octet-stream" \
            --data-binary "@$FILE" \
            "https://uploads-api.reflect.run/v1/mobile/builds?name=$BUILD_NAME")
          echo "UPLOAD_RESPONSE=$UPLOAD_RESPONSE"
          echo "BUILD_ID=$(echo $UPLOAD_RESPONSE | jq -r .id)" >> $GITHUB_ENV

      - name: Trigger regression suite
        run: |
          curl -X POST \
            -H "X-API-KEY: ${{ secrets.REFLECT_API_KEY }}" \
            -H "Content-Type: application/json" \
            --data-binary "{\"mobileAppOverrides\":{\"app-release.apk\":\"${BUILD_ID}\"}}" \
            "https://api.reflect.run/v1/suites/triggerviaapi/executions"

Common Use Cases

  • Automatically trigger full regression tests after a new mobile build completes.

  • Run the same test suite across multiple environments or branches by dynamically referencing new builds.

  • Integrate Reflect’s execution pipeline directly into your continuous delivery workflow.

In this section:
© 2025
Publication date: