@qawolf/ci-sdk

QAWolf CI SDK

:warning: This is an experimental package. Please report any issues you encounter to your support channel. It should still provide a better experience than using our internal GraphQL API directly.

This package provides a TypeScript (CSM and ESM compatible) SDK to interact with the QAWolf Customer-facing API.

It exposes two functions associated with the two central endpoints, showcased in the examples below.

Note that these functions do not throw. They yield a result object that contains the outcome of the operation. This outcome should be scrutinized to determine the status of your CI/CD step/job/action.

Example: Trigger Run on Deployment

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

// Edit this to your needs.
// See documentation here: https://qawolf.notion.site/cfe5a209256448a5bcd825bcf2d87e34
const deployConfig: DeployConfig = {
  branch: undefined,
  commitUrl: undefined,
  deduplicationKey: undefined,
  deploymentType: undefined,
  deploymentUrl: undefined,
  hostingService: undefined,
  sha: undefined,
  variables: undefined,
};

const { attemptNotifyDeploy } = makeQaWolfSdk({
  apiKey: "qawolf_xxxxx",
});

(async () => {
  const result = await attemptNotifyDeploy(deployConfig);
  if (result.outcome !== "success") {
    // Fail the job.
    process.exit(1);
  }
  const runId = result.runId;
  // Store the runId as an output of the job to be used in a CI-greenlight job.
  // This will depend on the CI platform you are using.
})();

Example: Poll for CI Greenlight Status

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

const { pollCiGreenlightStatus } = makeQaWolfSdk({
  apiKey: "qawolf_xxxxx",
});

(async () => {
  // Retrieve runId from the previous job.
  const { outcome } = await pollCiGreenlightStatus({
    runId,
    // Optional: Callback to be called when the run stage changes.
    // See https://qawolf.notion.site/dc42843313c246c8bf2a3a314ceb2c61 for
    // documentation on these run stages.
    onRunStageChanged: (current, previous) => {
      console.log(current, previous);
    },
  });
  if (outcome !== "success") {
    // Fail the job.
    // This will depend on the CI platform you are using.
    // You can also distinguish between "failed" and "aborted" outcomes.
    // Only "failed" outcome indicates bugs were found.
    process.exit(1);
  }
  // Continue CI.
})();

Versioning

This package follows the SemVer versioning scheme. Additional notes:

• Versions below 1.0.0 still follow this scheme.
• We recommend depending on the ^ range operator for this package, as it will not introduce breaking changes and guarantee an up-to-date API usage version.
• We will provide a changelog for each release, which will be available in the CHANGELOG.md file.
• This package major version will be bumped when an API breaking change is introduced. This won't happen too often, and we will reach out to you and give advance notice when it does.
• Only top-level exports are considered part of the public API and covered by SemVer.
• Addition of new fields in the API response types are not considered breaking changes.
• Logs and debug messages are not considered part of the public API and can change at any time.