Mobile build testing

QA Wolf runs flows against a real build of your app — an .apk or .aab for Android, an .ipa for iOS. Your pipeline uploads each new build and notifies QA Wolf, which triggers a run against it.

How it works

Upload the build artifact

Your pipeline sends the build to QA Wolf and gets back a path identifying it.

Notify QA Wolf of the deployment

Your pipeline passes that path to QA Wolf as RUN_INPUT_PATH, which starts a run against the new build.

During setup you can upload builds without triggering runs.

QA Wolf must enable mobile triggers for your workspace before any of this starts a run. Until then, uploads and deploy notifications both succeed and no flows run, with no error. Ask your QA Wolf representative to enable them, and expect to confirm which environments you want to test, whether PR testing is enabled, your naming conventions, and the upload method you chose.

Requirements

A QA Wolf API key — Workspace Settings → Integrations → API Access — stored in your CI system as QAWOLF_API_KEY.
Naming conventions agreed for your build artifacts. See Name your build artifacts.

Name your build artifacts

QA Wolf parses the artifact name to determine which environment to run against, and whether the build belongs to a pull request. Provide the basename only — QA Wolf applies the file extension automatically. Static environments. Use the same basename for every build of that environment.

<prefix>-<environment-name>

Example: app-staging PR environments. Only applies if PR testing is enabled.

<prefix>-<org>-<repo>-pr<number>

Example: app-myorg-myrepo-pr123

Upload a build artifact

Fastlane
GitHub Actions
Node.js
Webhooks

Add the QA Wolf Fastlane plugin to your project, then call upload_to_qawolf in the lane that builds your app.Example:

lane :qawolf do
  # Your existing build step

  upload_to_qawolf(
    executable_file_basename: "app-staging"
  )
end

Add the upload action after the step that produces the artifact.Example:

- name: Upload mobile build to QA Wolf
  id: upload-run-input
  uses: qawolf/upload-run-inputs-executable-action@v1
  with:
    qawolf-api-key: ${{ secrets.QAWOLF_API_KEY }}
    input-file-path: ./path/to/build.apk
    executable-file-basename: app-staging

Full workflow, including PR testing:

name: Deploy and Notify QA Wolf
on: pull_request
jobs:
  ...
  notify:
    needs: deploy-preview-environment
    name: Trigger QA Wolf PR testing
    runs-on: ubuntu-latest
    steps:
    ...
      # Upload the run input file
      - name: Upload Run Input
        id: upload-run-inputs-executable
        uses: qawolf/upload-run-inputs-executable-action@v1
        with:
          qawolf-api-key: "${{ secrets.QAWOLF_API_KEY }}"
          input-file-path: "path/to/file.apk"
      - name: Notify QA Wolf of deployment
        uses: qawolf/notify-qawolf-on-deploy-action@v1
        env:
          ...
          # Use the output in the RUN_INPUT_PATH environmental variable
          RUN_INPUT_PATH: "${{ steps.upload-run-inputs-executable.outputs.destination-file-path }}"
          ...
        with: ...

For CI systems other than GitHub Actions or Fastlane that can run Node.js 18 or later.

npm install @qawolf/ci-sdk

Example:

import { makeQaWolfSdk } from "@qawolf/ci-sdk";
import fs from "fs/promises";

const sdk = makeQaWolfSdk({ apiKey: process.env.QAWOLF_API_KEY });

const signedUrl = await sdk.generateSignedUrlForRunInputsExecutablesStorage({
  destinationFilePath: "app-staging",
});

await fetch(signedUrl.uploadUrl, {
  method: "PUT",
  body: await fs.readFile("./path/to/build.apk"),
  headers: { "Content-Type": "application/octet-stream" },
});

const executablePath = signedUrl.playgroundFileLocation;

Full implementation, including the deploy notification:

import { type DeployConfig, makeQaWolfSdk } from "@qawolf/ci-sdk";
import fs from "fs/promises";
import path from "path";

const { generateSignedUrlForRunInputsExecutablesStorage, attemptNotifyDeploy } =
  makeQaWolfSdk({
    apiKey: process.env.QAWOLF_API_KEY,
  });

(async () => {
  const playgroundFileLocation = await uploadRunArtifact("/FileLocation");

  if (playgroundFileLocation) {
    const deployConfig: DeployConfig = {
      branch: undefined,
      commitUrl: undefined,
      deduplicationKey: undefined,
      deploymentType: undefined,
      deploymentUrl: undefined,
      ephemeralEnvironment: undefined,
      hostingService: undefined,
      sha: undefined,
      variables: {
        RUN_INPUT_PATH: playgroundFileLocation,
      },
    };

    const result = await attemptNotifyDeploy(deployConfig);
    if (result.outcome !== "success") {
      process.exit(1);
    }
    const runId = result.runId;
  }
})();

async function uploadRunArtifact(filePath: string): Promise<string> {
  const fileName = path.basename(filePath);

  const signedUrlResponse = await generateSignedUrlForRunInputsExecutablesStorage({
    destinationFilePath: fileName,
  });

  if (
    signedUrlResponse?.success &&
    signedUrlResponse.playgroundFileLocation &&
    signedUrlResponse.uploadUrl
  ) {
    const fileBuffer = await fs.readFile(filePath);
    const url = signedUrlResponse.uploadUrl;

    try {
      const response = await fetch(url, {
        method: "PUT",
        body: fileBuffer,
        headers: {
          "Content-Type": "application/octet-stream",
        },
      });

      if (!response.ok) {
        return "";
      }
    } catch (error) {
      return "";
    }

    return signedUrlResponse.playgroundFileLocation;
  }
  return "";
}

For CI systems that can’t run Node.js — ArgoCD, locked-down runners, minimal containers. Requires only HTTP requests.

Generate a signed URL

curl "https://app.qawolf.com/api/v0/run-inputs-executables-signed-urls?file=app-staging" \
  -H "Authorization: Bearer $QAWOLF_API_KEY"

On success, you’ll receive:

{
  "fileLocation": "$TEAM_ID/app-staging",
  "playgroundFileLocation": "app-staging",
  "signedUrl": "https://..."
}

Copy the playgroundFileLocation value for the notify step.

Upload the file

curl -X PUT \
  --header "Content-Type: application/octet-stream" \
  --data-binary @./path/to/build.apk \
  "$SIGNED_URL"

See v0/run-inputs-executables-signed-urls for the full request and response reference, including error codes.

These examples upload an Android .apk. iOS works identically — point the same steps at your .ipa.

Trigger a test run

Pass the path from the upload step as RUN_INPUT_PATH. Set the deployment type to the label QA Wolf configured for your workspace, such as staging, or omit it if your workspace has no label.

Fastlane
GitHub Actions
Node.js
Webhooks

The Fastlane plugin takes the name of the environment variable holding the path, not the path itself.Example:

notify_deploy_qawolf(
  executable_environment_key: "RUN_INPUT_PATH"
)

Example:

- name: Notify QA Wolf of deployment
  uses: qawolf/notify-qawolf-on-deploy-action@v1
  with:
    qawolf-api-key: ${{ secrets.QAWOLF_API_KEY }}
    deployment-type: staging
    variables: >
      { "RUN_INPUT_PATH": "${{ steps.upload-run-input.outputs.destination-file-path }}" }

Example:

await sdk.attemptNotifyDeploy({
  deploymentType: "staging",
  variables: {
    RUN_INPUT_PATH: executablePath,
  },
});

Example:

curl -X POST https://app.qawolf.com/api/webhooks/deploy_success \
  -H "Authorization: Bearer $QAWOLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_type": "staging",
    "variables": {
      "RUN_INPUT_PATH": "<playgroundFileLocation>"
    }
  }'

A 200 response doesn’t guarantee a run was created. Inspect the response body to confirm. See webhooks/deploy_success for full response details.

RUN_INPUT_PATH accepts either form of the path. An absolute path is used as-is; a bare filename resolves against the uploads directory on the runner.

Use the build in a flow

QA Wolf uses the most recent upload automatically. To point a flow at a specific build, see App resolution for Android or iOS.

Verify the integration

Run the CI job that builds your app.

Confirm the upload step completes successfully.

Confirm the deploy notification step runs without errors.

Once mobile triggers are enabled, check the Runs tab for the triggered run.

Troubleshooting

Uploads succeed, but no runs start — mobile triggers may not be enabled for your workspace yet.
The artifact isn’t found during a run — verify the basename matches your naming conventions, and that RUN_INPUT_PATH carries the path returned by the upload step.
Authentication errors — verify QAWOLF_API_KEY is set correctly in the CI job.
The wrong environment is tested — verify the deployment type matches the value configured for your workspace.
The job fails before the QA Wolf steps — verify the build step completes and produces the artifact you expect.

CI/CD

VPN

Test Management Systems

Issue Trackers

How it works

Requirements

Name your build artifacts

Upload a build artifact

Trigger a test run

Use the build in a flow

Verify the integration

Troubleshooting

​How it works

​Requirements

​Name your build artifacts

​Upload a build artifact

​Trigger a test run

​Use the build in a flow

​Verify the integration

​Troubleshooting

​Related

How it works

Requirements

Name your build artifacts

Upload a build artifact

Trigger a test run

Use the build in a flow

Verify the integration

Troubleshooting

Related