SDK Reference

npm install @qawolf/ci-sdk

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

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

import { detectProviderDeploymentId, makeQaWolfSdk } from "@qawolf/ci-sdk";

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

const detected = detectProviderDeploymentId();
if (detected.outcome !== "detected") process.exit(1);

const result = await deployment.reportStatus({
  workspaceId: process.env.QAWOLF_WORKSPACE_ID,
  providerDeploymentId: detected.id,
  status: "success",
  environment: { name: "staging" },
  deployTarget: "https://staging.example.com",
  metadata: {
    commitSha: process.env.GIT_COMMIT,
    ref: process.env.GIT_BRANCH,
  },
});

if (result.outcome !== "reported") process.exit(1);
console.log(result.deployment.url);

import { detectProviderDeploymentId } from "@qawolf/ci-sdk";

const detected = detectProviderDeploymentId();
if (detected.outcome !== "detected") process.exit(1);
// detected.ci is "jenkins", detected.id is the value of BUILD_TAG

const report = await deployment.reportStatus({ /* ... */ status: "success" });
if (report.outcome !== "reported") process.exit(1);

const verdict = await deployment.waitForVerdict({
  deploymentId: report.deployment.id,
  timeout: 45 * 60 * 1000,
});

process.exit(["passed", "not-tested"].includes(verdict.outcome) ? 0 : 1);

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

if (pullRequestWasMerged) {
  const result = await environment.promote({
    environmentId: `preview/pr-${pullRequestNumber}`,
    workspaceId: process.env.QAWOLF_WORKSPACE_ID,
  });
  if (result.outcome !== "requested") process.exit(1);
  console.log(result.promotion.id, result.promotion.status); // "pending"
} else {
  const result = await environment.terminate({
    environmentId: `preview/pr-${pullRequestNumber}`,
    workspaceId: process.env.QAWOLF_WORKSPACE_ID,
  });
  if (result.outcome !== "terminated") process.exit(1);
}

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

const result = await promotion.get({ promotionId });
if (result.outcome !== "found") process.exit(1);
console.log(result.promotion.status);

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

const result = await uploadBuild({
  filePath: "app/build/outputs/apk/release/app-release.apk",
  environment: { name: "staging" },
  branch: process.env.GIT_BRANCH,
  commitSha: process.env.GIT_COMMIT,
  workspaceId: process.env.QAWOLF_WORKSPACE_ID,
});

if (result.outcome !== "uploaded") process.exit(1);
console.log(result.build.id, result.build.appId, result.build.version);

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

const result = await notifyTerminatedEphemeralEnvironment({
  environmentAlias: "preview/pr-42",
  workspaceId: process.env.QAWOLF_WORKSPACE_ID,
});

if (result.outcome !== "success") process.exit(1);

import fs from "fs/promises";

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

const signed = await generateSignedUrlForRunInputsExecutablesStorage({
  destinationFilePath: "app-staging.apk",
  workspaceId: process.env.QAWOLF_WORKSPACE_ID,
});

if (!signed.success || !signed.uploadUrl || !signed.interactiveRunFileLocation) {
  throw new Error("No upload URL received from QA Wolf");
}

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

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

const result = await attemptNotifyDeploy({
  branch: process.env.GIT_BRANCH,
  sha: process.env.GIT_COMMIT,
  deploymentType: "staging",
  hostingService: "GitHub",
  repository: { name: "web", owner: "acme" },
  commitUrl: undefined,
  deduplicationKey: undefined,
  deploymentUrl: undefined,
  pullRequestNumber: undefined,
  variables: undefined,
});

if (result.outcome === "skipped") process.exit(0);
if (result.outcome !== "success") process.exit(1);
const runId = result.runId;

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

const { outcome } = await pollCiGreenlightStatus({
  runId,
  onRunStageChanged: (current, previous) => {
    console.log(current.runStage, previous?.runStage);
  },
});

if (outcome !== "success") process.exit(1);

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

for await (const iteration of makePollCiGreenlightStatusIterator({ runId })) {
  if (iteration.isAborted) {
    console.error(`Poll aborted: ${iteration.abortReason}`);
    process.exit(1);
  }

  const { status } = iteration;
  switch (status.runStage) {
    case "initializing":
    case "underReview":
      break;
    case "completed":
      if (!status.greenlight) process.exit(1);
      process.exit(0);
    case "canceled":
      process.exit(1);
    default:
      status.runStage satisfies never;
      throw new Error(`Unexpected run stage: ${status.runStage}`);
  }
}