@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

ℹ️ See the API documentation page for this endpoint.

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

// Edit this to your needs.
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

ℹ️ See the API documentation page for this endpoint.

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/1b170576efea411fa785842a71e7c99e 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.
})();

Example: pull request testing

:warning: This section is not covered by SemVer and will change.

const details: {
  baseEnvironmentId: string | undefined;
  branch: string;
  commitUrl: string;
  deploymentUrl: string | undefined;
  pr: { number: number; title: string } | undefined;
  qaWolfTeamId: string;
  // company/repository
  repoFullName: string;
  sha: string;
  variables: { [key: string]: string };
} = {};
const result = await sdk.experimental_testPreview(details);
if (result.outcome !== "success") {
  console.error(result);
  throw Error("Creating a test failed");
}

Then, after the PR has been closed:

await sdk.experimental_removeEnvironment({ branch: "" });

Requirements

This packages will work out of the box with NodeJS ≥ 18. If you are using an older NodeJS version, you will need to pass a fetch polyfill function to makeQaWolfSdk. We recommend undici for this purpose, see below snippet:

import { fetch } from "undici";

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

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 section below.
• 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.

Changelog

v0.15.5

• Throw a runtime error when fetch is not defined. This would be the case for setups with a NodeJS version < 18.

v0.15.4

• Fix broken ESM build due to lacking .js extension in some built files.

v0.15.0

• New experimental_testPreview and experimental_deleteEnvironment methods.

v0.14.0

• New failReason, abortReason and httpStatus fields added to the attemptNotifyDeploy function result object to provide more context on why the operation failed or was aborted.
• Exported missing TypeScript typings describing result objects and fields for both functions.

v0.13.0

• New pollTimeout parameter for pollCiGreenlightStatus to allow for a custom timeout in milliseconds for the polling operation. It now defaults to two hours.
• New abortReason and httpStatus fields added to the PollCiGreenlightStatus type with "aborted" outcome to provide more context on why the poll was aborted.

v0.12.1

• Export dependencies types from root module.
• Refine DeployConfig.hostingService type to match API requirements.
• Fix inaccessible changelog file from NPM.

v0.12.0

• Define a more restrictive LogDriver interface for easy integration with GHA core interface.

v0.11.0

• Support reproducedBugs field from CI-greenlight API.

:warning: These are the last breaking changes brought to the 0.x major version. These are being introduced while the SDK hasn't been advertised to the public yet. Future changes will follow the SemVer versioning scheme.

BREAKING CHANGES:

• pollCiGreenlightStatus and attemptNotifyDeploy now return a "result" object with an outcome field that can be either "success", "failed" or "aborted", instead of exiting the process with a non-zero code. This will provide more flexibility to the user to decide how to handle the outcome.

v0.10.3

BREAKING CHANGES:

• Renamed attemptDeploy to attemptNotifyDeploy .

v0.10.2

• Avoid logging dots after URL names in the logs. Dots can confuse terminal URL detection.

v0.10.1

• Fix TypeScript types visibility.

v0.10.0

Initial release.

Supported Endpoints

• /api/deploy_success
• /api/v0/ci-greenlight/[root-run-id]