Integrate a mobile build with the QA Wolf SDK

Use this guide if your CI system supports Node.js but is not GitHub Actions or Fastlane.

Make sure you have:

A CI pipeline that produces a mobile build artifact (APK, AAB, or IPA).
Node.js 18 or later available in your CI environment.
Admin access to your CI system’s secret or environment variable storage.
A QA Wolf API key.

Before mobile test runs can execute, QA Wolf must enable mobile triggers for your workspace. QA Wolf will handle this and may ask you for:

Which environments you want to test.
Whether PR testing is enabled.
The artifact naming conventions you are using.
The upload and trigger method you chose.

Until this step is complete, CI jobs can upload artifacts and send deployment notifications, but mobile test runs will not start automatically.

Install the CI SDK

Install the SDK in your CI job:

npm install @qawolf/ci-sdk

Find the QAWOLF_API_KEY

Open the Workspace name dropdown in QA Wolf and click Workspace Settings.

Choose Integrations.

Generate your QAWOLF_API_KEY by clicking the icon to the right of API Key under API Access.

Make sure the job has access to the QAWOLF_API_KEY environment variable.

Artifact naming conventions

Mobile build artifacts must follow consistent naming conventions so QA Wolf can correctly associate each build with the right environment and make failures easier to diagnose. The artifact name is used to identify:

Which environment the build belongs to.
Whether the build is tied to a pull request.
Which build was used for a given test run.

Static environments

Static environments are long-lived environments such as staging or release environments. Format

<prefix>-<environment-name>

Example

app-staging

Use the same basename every time a build is generated for the same environment.

PR (ephemeral) environments

PR environments are short-lived and tied to a specific pull request. These are only relevant if PR testing is enabled. Format

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

Example

app-myorg-myrepo-pr123

Including the organization, repository, and pull request number ensures each build can be traced back to the correct change and environment.

QA Wolf applies the file extension (.apk, .aab, or .ipa) automatically based on the uploaded artifact. You only need to provide the basename.

Upload a mobile build artifact

After your CI pipeline produces a mobile build artifact, upload it to QA Wolf using the SDK. Minimal example

Javascript

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

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

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

  const fileBuffer = await fs.readFile("./path/to/build.apk");

  await fetch(signedUrl.uploadUrl, {
    method: "PUT",
    body: fileBuffer,
    headers: {
      "Content-Type": "application/octet-stream",
    },
  });

  return `/home/wolf/run-inputs-executables/${signedUrl.playgroundFileLocation}`;
}

const executablePath = await uploadBuild();

If this step completes successfully, the artifact is uploaded and available for test runs. Full implementation The following example includes both artifact upload and deploy notification in a single script.

Javascript

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 "";
}

Trigger a test run

After uploading the artifact, notify QA Wolf that a new deployment is ready for testing.

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

The deployment type and environment key must match the values configured by QA Wolf for your workspace.

If mobile triggers have not yet been enabled, this step will complete without starting a test run.

Verify the integration

Run the CI job.

Verify that the artifact upload completes successfully.

Confirm that the deployment notification step runs without errors.

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

Troubleshooting and common issues

If uploads succeed but no runs start: Mobile triggers may not yet be enabled. Contact QA Wolf to complete platform configuration.
If the artifact is not found during execution: Verify that the artifact basename matches your naming conventions, and the returned path is used when triggering the run.
If you see authentication errors: Verify that QAWOLF_API_KEY is configured correctly in your CI environment.
If you encounter Node.js errors: Ensure Node.js 18 or later is available in the CI job.

CI/CD

VPN

Test Management Systems

Issue Trackers

Local execution

Integrate a mobile build with the QA Wolf SDK

Install the CI SDK

Find the QAWOLF_API_KEY

Artifact naming conventions

Static environments

PR (ephemeral) environments

Upload a mobile build artifact

Trigger a test run

Verify the integration

Troubleshooting and common issues

​Install the CI SDK

​Find the QAWOLF_API_KEY

​Artifact naming conventions

​Static environments

​PR (ephemeral) environments

​Upload a mobile build artifact

​Trigger a test run

​Verify the integration

​Troubleshooting and common issues

​Related

Install the CI SDK

Find the QAWOLF_API_KEY

Artifact naming conventions

Static environments

PR (ephemeral) environments

Upload a mobile build artifact

Trigger a test run

Verify the integration

Troubleshooting and common issues

Related