@qawolf/ci-sdk
Advanced tools
This package provides a TypeScript (CSM and ESM compatible) SDK to interact with the QA Wolf Customer-facing API.
It exposes several functions associated with different endpoints, which are detailed in the table of contents 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.
Notify us of a successful deployment to trigger a run.
💡 For GitHub Actions Users: If you're using GitHub Actions, we strongly recommend using our GitHub Action. The GitHub Action provides simpler configuration and automatic information extraction.
⚠️ Important: A run is only created if there is a matching trigger in your QA Wolf configuration. The deployment notification alone doesn't guarantee a run will be created.
import { type DeployConfig, makeQaWolfSdk } from "@qawolf/ci-sdk";
// Example for GitHub repositories
const deployConfig: GitHubDeployConfig = {
branch: undefined,
commitUrl: undefined,
deduplicationKey: undefined,
// Required only if the target trigger requires matching a deployment type
deploymentType: "staging", // e.g., "production", "staging", "qa"
deploymentUrl: undefined,
// Specify GitHub as hosting service
hostingService: "GitHub",
// Optional: Include pull request number for PR testing
// See Notify Preview Deployment (Pull Request / Merge Request Testing) section
pullRequestNumber: 123,
// Recommended: Include repository information
repository: {
name: "your-repo",
owner: "your-org",
},
sha: undefined,
variables: undefined,
};
// Example for GitLab repositories
const deployConfig: GitLabDeployConfig = {
branch: undefined,
commitUrl: undefined,
deduplicationKey: undefined,
// Required only if the target trigger requires matching a deployment type
deploymentType: "staging", // e.g., "production", "staging", "qa"
deploymentUrl: undefined,
// Specify GitLab as hosting service
hostingService: "GitLab",
// Optional: Include merge request number for MR testing
// See Notify Preview Deployment (Pull Request / Merge Request Testing) section
mergeRequestNumber: 123,
// Recommended: Include repository information
repository: {
name: "your-repo",
namespace: "your-group",
},
};
// General Example
// Edit this to your needs.
const deployConfig: DeployConfig = {
branch: undefined,
commitUrl: undefined,
deduplicationKey: undefined,
// Required only if the target trigger requires matching a deployment type
deploymentType: "staging", // e.g., "production", "staging", "qa"
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.
})();
⚠️ Important: PR/MR testing functionality must be activated by QA Wolf. Please reach out to your QA Wolf representative to enable this feature and help with the setup.
Once enabled, to use PR/MR testing functionality:
For GitHub repositories:
hostingService: "GitHub", repository information, and pullRequestNumber while notifying a deployment as described in the Notify Deployment sectionFor GitLab repositories:
hostingService: "GitLab", repository information, and mergeRequestNumber while notifying a deployment as described in the Notify Deployment sectionimport { 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);
},
// Optional: Defaults to false. When set to true, the polling operation
// will abort when the run is superseded.
abortOnSuperseded: false,
});
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.
})();
import { type DeployConfig, makeQaWolfSdk } from "@qawolf/ci-sdk";
import fs from "fs/promises";
import path from "path";
const { generateSignedUrlForTempTeamStorage, attemptNotifyDeploy } =
makeQaWolfSdk({
apiKey: "qawolf_xxxxx",
});
(async () => {
const playgroundFileLocation = await uploadRunArtifact("");
if (playgroundFileLocation) {
const deployConfig: DeployConfig = {
branch: undefined,
commitUrl: undefined,
deduplicationKey: undefined,
deploymentType: undefined,
deploymentUrl: undefined,
hostingService: undefined,
sha: undefined,
variables: {
RUN_INPUT_PATH: playgroundFileLocation,
},
};
const result = await attemptNotifyDeploy(deployConfig);
if (result.outcome !== "success") {
// Fail the job.
process.exit(1);
}
const runId = result.runId;
}
})();
async function uploadRunArtifact(filePath: string): Promise<string> {
const fileName = path.basename(filePath);
const signedUrlResponse = await generateSignedUrlForTempTeamStorage({
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 "";
}
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 },
);
This package follows the SemVer versioning scheme. Additional notes:
^ range operator for this package, as it will not introduce breaking changes and guarantee an up-to-date API usage version.experimental_vcsBranchTesting and experimental_testPreview. See how to migrate in Notify Preview Deployment (Pull Request / Merge Request Testing) section.eventId on errorsenvironmentId on attemptNotifyDeploydeployConfig in attemptNotifyDeploy.duplicate_suite_id in attemptNotifyDeploy response.baseEnvironmentsMapping optional in notifyVCSBranchBuildDeployed and notifyVCSBranchMergeCompleted.baseVcsBranch when requesting VCS branch testing and VCS branch merge completion.pollCiGreenlightStatus: bug data fields are now available in the "underReview" run stage.pollCiGreenlightStatus: new otherBlockingBugsInEnvironment response
field. Some runs with a subset of workflows in environment will not reproduce
blocking bugs in this environment. You can now see these other blocking bugs
with this field.abortOnSuperseded option to pollCiGreenlightStatus to allow for aborting the polling operation when the run is superseded.generateSignedUrlForRunInputsExecutablesStorage function to generate a signed url used to upload files to the Run Inputs Executables bucket.generateSignedUrlForTempTeamStorage fails.generateSignedUrlForTempTeamStorage function to be used in customer's CI pipeline.experimental_testPreview and experimental_removeEnvironment. These methods will be removed in an upcoming release.fetch calls to 60 seconds.@qawolf/ci-utils, and move the LogDriver interface to it.experimental_vcsBranchTesting. These
features are not available to customers nor documented yet, but will be advertised
in a near future.fetch is not defined. This would be the case for
setups with a NodeJS version < 18..js extension in some built files.experimental_testPreview and experimental_deleteEnvironment methods.failReason, abortReason and httpStatus fields added to the attemptNotifyDeploy
function result object to provide more context on why the operation failed or was aborted.pollTimeout parameter for pollCiGreenlightStatus to allow for a custom
timeout in milliseconds for the polling operation. It now defaults to two hours.abortReason and httpStatus fields added to the PollCiGreenlightStatus type
with "aborted" outcome to provide more context on why the poll was aborted.DeployConfig.hostingService type to match API requirements.LogDriver interface for easy integration with GHA
core interface.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.BREAKING CHANGES:
attemptDeploy to attemptNotifyDeploy .Initial release.
/api/deploy_success/api/v0/ci-greenlight/[root-run-id]FAQs
A simple SDK for interacting with QAWolf in CI scripts.
The npm package @qawolf/ci-sdk receives a total of 7,405 weekly downloads. As such, @qawolf/ci-sdk popularity was classified as popular.
We found that @qawolf/ci-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.