Node.js Xray Client

This project provides TypeScript clients to users that want to interact with the API of Xray. Supports Xray server and Xray cloud.

Warning

The client is at a very early stage of development and may not cover all Xray interactions. Please refer to the roadmaps for full lists of supported endpoints.

Xray server roadmap

---

Based on: https://docs.getxray.app/display/XRAY/REST+API

• v1
  • Tests
    • GET /rest/raven/1.0/api/test
    • GET /rest/raven/1.0/api/settings/teststatuses
    • GET /rest/raven/1.0/api/test/{key}/testruns
    • GET /rest/raven/1.0/api/test/{key}/preconditions
    • GET /rest/raven/1.0/api/test/{key}/testsets
    • GET /rest/raven/1.0/api/test/{key}/testexecutions
    • GET /rest/raven/1.0/api/test/{key}/testplans
    • Test Steps
      • GET /rest/raven/1.0/api/settings/teststepstatuses
      • GET /rest/raven/1.0/api/test/{testKey}/step
      • GET /rest/raven/1.0/api/test/{testKey}/step/{id}
      • PUT /rest/raven/1.0/api/test/{testKey}/step
      • POST /rest/raven/1.0/api/test/{testKey}/step/{id}
      • DELETE /rest/raven/1.0/api/test/{testKey}/step/{id}
      • GET /rest/raven/1.0/api/test/{testKey}/step/{id}/attachment
      • DELETE /rest/raven/1.0/api/test/{testKey}/step/{id}/attachment/{attachmentID}
  • Pre-Conditions
    • GET /rest/raven/1.0/api/precondition/{preConditionKey}/test
    • POST /rest/raven/1.0/api/precondition/{preConditionKey}/test
    • DELETE /rest/raven/1.0/api/precondition/{preConditionKey}/test/{testKey}
  • Test Sets
    • GET /rest/raven/1.0/api/testset/{testSetKey}/test
    • POST /rest/raven/1.0/api/testset/{testSetKey}/test
    • DELETE /rest/raven/1.0/api/testset/{testSetKey}/test/{testKey}
  • Test Plans
    • GET /rest/raven/1.0/api/testplan/{testPlanKey}/test
    • POST /rest/raven/1.0/api/testplan/{testPlanKey}/test
    • DELETE /rest/raven/1.0/api/testplan/{testPlanKey}/test/{testKey}
    • GET /rest/raven/1.0/api/testplan/{testPlanKey}/testexecution
    • POST /rest/raven/1.0/api/testplan/{testPlanKey}/testexecution
    • DELETE /rest/raven/1.0/api/testplan/{testPlanKey}/testexecution/{testExecKey}
  • Test Executions
    • GET /rest/raven/1.0/api/testexec/{testExecKey}/test
    • POST /rest/raven/1.0/api/testexec/{testExecKey}/test
    • DELETE /rest/raven/1.0/api/testexec/{testExecKey}/test/{testKey}
  • Test Runs
    • GET /rest/raven/1.0/api/testrun/{id}/
    • GET /rest/raven/1.0/api/testrun/
    • PUT /rest/raven/1.0/api/testrun/{id}/
    • GET /rest/raven/1.0/api/testrun/{id}/status
    • PUT /rest/raven/1.0/api/testrun/{id}/status
    • GET /rest/raven/1.0/api/testrun/{id}/defect
    • POST /rest/raven/1.0/api/testrun/{id}/defect
    • DELETE /rest/raven/1.0/api/testrun/{id}/defect/{issueIdOrKey}
    • GET /rest/raven/1.0/api/testrun/{id}/attachment
    • POST /rest/raven/1.0/api/testrun/{id}/attachment
    • DELETE /rest/raven/1.0/api/testrun/{id}/attachment
    • DELETE /rest/raven/1.0/api/testrun/{id}/attachment/{attachmentid}
    • GET /rest/raven/1.0/api/testrun/{id}/comment
    • PUT /rest/raven/1.0/api/testrun/{id}/comment
    • GET /rest/raven/1.0/api/testrun/{id}/example
    • GET /rest/raven/1.0/api/testrun/{id}/step
    • GET /rest/raven/1.0/api/testrun/{id}/assignee
    • PUT /rest/raven/1.0/api/testrun/{id}/assignee
    • Test Examples
      • GET /rest/raven/1.0/api/testrun/{id}/example/{exampleIndex}
      • PUT /rest/raven/1.0/api/testrun/{id}/example/{exampleIndex}
    • Test Step Results
      • GET /rest/raven/1.0/api/testrun/{id}/step/{stepResultId}/
      • PUT /rest/raven/1.0/api/testrun/{id}/step/{stepResultId}/
      • GET /rest/raven/1.0/api/testrun/{id}/step/{stepResultId}/status
      • PUT /rest/raven/1.0/api/testrun/{id}/step/{stepResultId}/status
      • GET /rest/raven/1.0/api/testrun/{id}/step/{stepResultId}/attachment
      • POST /rest/raven/1.0/api/testrun/{id}/step/{stepResultId}/attachment
      • DELETE /rest/raven/1.0/api/testrun/{id}/step/{stepResultId}/attachment
      • DELETE /rest/raven/1.0/api/testrun/{id}/step/{stepResultId}/attachment/{attachmentid}
  • Test Repository
    • GET /rest/raven/1.0/api/testrepository/{projectKey}/folders
    • GET /rest/raven/1.0/api/testrepository/{projectKey}/folders/{folderId}/tests
    • PUT /rest/raven/1.0/api/testrepository/{projectKey}/folders/{folderId}/tests
    • GET /rest/raven/1.0/api/testrepository/{projectKey}/folders/{folderId}
    • POST /rest/raven/1.0/api/testrepository/{projectKey}/folders/{folderId}
    • PUT /rest/raven/1.0/api/testrepository/{projectKey}/folders/{folderId}
    • DELETE /rest/raven/1.0/api/testrepository/{projectKey}/folders/{folderId}
  • Import Execution Results
    • POST /rest/raven/1.0/api/import/execution
    • POST /rest/raven/1.0/api/import/execution/multipart
    • POST /rest/raven/1.0/api/import/execution/cucumber
    • POST /rest/raven/1.0/api/import/execution/cucumber/multipart
    • POST /rest/raven/1.0/api/import/execution/behave
    • POST /rest/raven/1.0/api/import/execution/behave/multipart
    • POST /rest/raven/1.0/api/import/execution/junit
    • POST /rest/raven/1.0/api/import/execution/junit/multipart
    • POST /rest/raven/1.0/api/import/execution/testng
    • POST /rest/raven/1.0/api/import/execution/testng/multipart
    • POST /rest/raven/1.0/api/import/execution/nunit
    • POST /rest/raven/1.0/api/import/execution/nunit/multipart
    • POST /rest/raven/1.0/api/import/execution/xunit
    • POST /rest/raven/1.0/api/import/execution/xunit/multipart
    • POST /rest/raven/1.0/api/import/execution/robot
    • POST /rest/raven/1.0/api/import/execution/robot/multipart
    • POST /rest/raven/1.0/api/import/execution/bundle
  • Export Execution Results
    • GET /rest/raven/1.0/api/testruns
    • GET /rest/raven/1.0/api/execution/result (deprecated)
  • Importing Cucumber Tests
    • POST /rest/raven/1.0/api/import/feature
  • Exporting Cucumber Tests
    • GET /rest/raven/1.0/api/export/test
  • Settings
    • GET /rest/raven/1.0/api/settings/teststatuses
    • GET /rest/raven/1.0/api/settings/teststepstatuses
• v2
  • Test Step
    • GET /rest/raven/2.0/api/test/{testKey}/steps
    • POST /rest/raven/2.0/api/test/{testKey}/steps
    • GET /rest/raven/2.0/api/test/{testKey}/steps/{stepId}
    • PUT /rest/raven/2.0/api/test/{testKey}/steps/{stepId}
    • DELETE /rest/raven/2.0/api/test/{testKey}/steps/{stepId}
    • GET /rest/raven/2.0/api/test/{testKey}/steps/{stepId}/attachments
    • DELETE /rest/raven/2.0/api/test/{testKey}/steps/{stepId}/attachment/{attachmentId}
  • Test Run
    • GET /rest/raven/2.0/api/testrun
    • GET /rest/raven/2.0/api/testrun/{id}
    • PUT /rest/raven/2.0/api/testrun/{id}
    • GET /rest/raven/2.0/api/testrun/{id}/customfield/{customFieldId}
    • PUT /rest/raven/2.0/api/testrun/{id}/customfield/{customFieldId}
    • GET /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}
    • PUT /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}
    • GET /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}/step
    • GET /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}/step/{stepResultId}
    • PUT /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}/step/{stepResultId}
    • GET /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}/step/{stepResultId}/status
    • PUT /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}/step/{stepResultId}/status
    • GET /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}/step/{stepResultId}/attachment
    • POST /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}/step/{stepResultId}/attachment
    • DELETE /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}/step/{stepResultId}/attachment
    • DELETE /rest/raven/2.0/api/testrun/{id}/iteration/{iterationId}/step/{stepResultId}/attachment/{attachmentId}
    • GET /testruns
  • Test Run Status
    • PUT /rest/raven/2.0/api/testrunstatus/reset
  • Requirement Status
    • PUT /rest/raven/2.0/api/requirementstatus/reset
  • Project
    • GET /rest/raven/2.0/api/project/{id}/settings/customfields/testruns
    • GET /rest/raven/2.0/api/project/{id}/settings/customfields/teststeps
  • External Apps
    • GET /rest/raven/2.0/api/xraylicense
  • Import
    • POST /rest/raven/2.0/api/import/execution
    • POST /rest/raven/2.0/api/import/execution/multipart
  • Dataset
    • GET /rest/raven/2.0/api/dataset/export
    • POST /rest/raven/2.0/api/dataset/import
  • Test Repository
    • GET /rest/raven/2.0/api/testrepository/{projectKey}/folders/{folderId}

Xray cloud roadmap

---

Based on: https://docs.getxray.app/display/XRAYCLOUD/REST+API

• v1
  • Exporting Cucumber Tests
    • GET /api/v1/export/cucumber
  • Import Execution Results
    • POST /api/v1/import/execution
    • POST /api/v1/import/execution/multipart
    • POST /api/v1/import/execution/cucumber
    • POST /api/v1/import/execution/cucumber/multipart
    • POST /api/v1/import/execution/junit
    • POST /api/v1/import/execution/junit/multipart
    • POST /api/v1/import/execution/nunit
    • POST /api/v1/import/execution/nunit/multipart
    • POST /api/v1/import/execution/xunit
    • POST /api/v1/import/execution/xunit/multipart
    • POST /api/v1/import/execution/testng
    • POST /api/v1/import/execution/testng/multipart
    • POST /api/v1/import/execution/robot
    • POST /api/v1/import/execution/robot/multipart
    • POST /api/v1/import/execution/behave
    • POST /api/v1/import/execution/behave/multipart
  • Importing Tests
    • POST /api/v1/import/test/bulk
    • GET /api/v1/import/test/bulk/{jobId}/status
  • Importing Cucumber Tests
    • POST /api/v1/import/feature
  • Backup
    • POST /api/v1/backup
    • GET /api/v1/backup/{jobId}/status
    • GET /api/v1/backup/file
    • GET /api/v1/backup/file/attachment
  • Attachments
    • GET /api/v1/attachments/{attachmentId}
    • POST /api/v1/attachments
• v2
  • Exporting Cucumber Tests
    • GET /api/v2/export/cucumber
  • Exporting Datasets
    • GET /api/v2/dataset/export
  • Import Execution Results
    • POST /api/v2/import/execution
    • POST /api/v2/import/execution/multipart
    • POST /api/v2/import/execution/cucumber
    • POST /api/v2/import/execution/cucumber/multipart
    • POST /api/v2/import/execution/junit
    • POST /api/v2/import/execution/junit/multipart
    • POST /api/v2/import/execution/nunit
    • POST /api/v2/import/execution/nunit/multipart
    • POST /api/v2/import/execution/xunit
    • POST /api/v2/import/execution/xunit/multipart
    • POST /api/v2/import/execution/testng
    • POST /api/v2/import/execution/testng/multipart
    • POST /api/v2/import/execution/robot
    • POST /api/v2/import/execution/robot/multipart
    • POST /api/v2/import/execution/behave
    • POST /api/v2/import/execution/behave/multipart
  • Importing Tests
    • POST /api/v2/import/test/bulk
    • GET /api/v2/import/test/bulk/{jobId}/status
  • Importing Cucumber Tests
    • POST /api/v2/import/feature
  • Backup
    • POST /api/v2/backup
    • GET /api/v2/backup/{jobId}/status
    • GET /api/v2/backup/file
    • GET /api/v2/backup/file/attachment
  • Attachments
    • GET /api/v2/attachments/{attachmentId}
    • POST /api/v2/attachments
• GraphQL
  • query
    • getFolder
    • getTest
    • getTests
    • getExpandedTest
    • getExpandedTests
    • getCoverableIssue
    • getCoverableIssues
    • getPrecondition
    • getPreconditions
    • getTestSet
    • getTestSets
    • getTestPlan
    • getTestPlans
    • getTestExecution
    • getTestExecutions
    • getTestRun
    • getTestRunById
    • getTestRuns
    • getTestRunsById
    • getStatus
    • getStatuses
    • getStepStatus
    • getStepStatuses
    • getProjectSettings
    • getIssueLinkTypes
  • mutation
    • createFolder
    • deleteFolder
    • renameFolder
    • moveFolder
    • addTestsToFolder
    • addIssuesToFolder
    • removeTestsFromFolder
    • removeIssuesFromFolder
    • createTest
    • updateTestType
    • updateUnstructuredTestDefinition
    • updateGherkinTestDefinition
    • deleteTest
    • addTestStep
    • updateTestStep
    • removeTestStep
    • removeAllTestSteps
    • addPreconditionToTest
    • removePreconditionFromTest
    • updateTestFolder
    • updatePreconditionFolder
    • addTestSetsToTest
    • removeTestSetsFromTest
    • addTestPlansToTest
    • removeTestPlansFromTest
    • addTestExecutionsToTest
    • removeTestExecutionsFromTest
    • createPrecondition
    • updatePrecondition
    • deletePrecondition
    • addTestsToPrecondition
    • removeTestsFromPrecondition
    • createTestSet
    • deleteTestSet
    • addTestsToTestSet
    • removeTestsFromTestSet
    • createTestPlan
    • deleteTestPlan
    • addTestsToTestPlan
    • removeTestsFromTestPlan
    • addTestExecutionsToTestPlan
    • removeTestExecutionsFromTestPlan
    • createTestExecution
    • deleteTestExecution
    • addTestsToTestExecution
    • removeTestsFromTestExecution
    • addTestEnvironmentsToTestExecution
    • removeTestEnvironmentsFromTestExecution
    • resetTestRun
    • updateTestRunStatus
    • updateTestRunComment
    • updateTestRun
    • addDefectsToTestRun
    • removeDefectsFromTestRun
    • addEvidenceToTestRun
    • removeEvidenceFromTestRun
    • updateTestRunStep
    • addEvidenceToTestRunStep
    • removeEvidenceFromTestRunStep
    • addDefectsToTestRunStep
    • removeDefectsFromTestRunStep
    • updateTestRunStepComment
    • updateTestRunStepStatus
    • updateTestRunExampleStatus
    • updateIterationStatus
    • setTestRunTimer

Installation

Xray Server

npm install @qytera/xray-client

Xray Cloud

If you don't intend to use the GraphQL endpoints:

npm install @qytera/xray-client

With GraphQL support:

npm install @qytera/xray-client graphql graphql-tag

Usage

Simply create a client instance for your Xray setup and start using the fully typed endpoints available.

Xray Server

import { XrayClientServer } from "@qytera/xray-client";

// PAT authentication.
export const serverClient = new XrayClientServer({
  credentials: {
    token: "jira-token",
  },
  url: "https://jira.company.com",
});

// Basic authentication.
export const serverClient = new XrayClientServer({
  credentials: {
    username: "jira-username",
    password: "jira-password",
  },
  url: "https://jira.company.com",
});

const csvData = await serverClient.dataset.export({ testIssueKey: "PRJ-123" });
const testRun = await serverClient.testRun.getTestRun({
  testExecIssueKey: "PRJ-456",
  testIssueKey: "PRJ-123",
});
// ... other endpoints

Xray Cloud

import { XrayClientCloud } from "@qytera/xray-client";

// Xray cloud authentication.
export const cloudClient = new XrayClientCloud({
  credentials: {
    clientId: "xray-client-id",
    clientSecret: "xray-client-secret",
    path: "/api/v2/authenticate",
  },
  url: "https://xray.cloud.getxray.app",
});

const csvData = await cloudClient.dataset.export({ testIssueKey: "PRJ-123" });
// ... other endpoints

The GraphQL query and mutation endpoints are also available. For example, consider the following getTestRuns query:

{
  getTestRuns(limit: 100, testExecIssueIds: ["XCN-2"]) {
    total
    limit
    start
    results {
      test {
        jira(fields: ["key"])
      }
    }
  }
}

It can easily be mapped to the following code snippet using the library:

const testRuns = await cloudClient.graphql.getTestRuns(
  { limit: 100, testExecIssueIds: ["XCN-2"] },
  (testRunResults) => [
    testRunResults.total,
    testRunResults.limit,
    testRunResults.start,
    testRunResults.results((testRun) => [
      testRun.test((test) => [
        test.jira({ fields: ["key"] })
      ])
    ]),
  ]
);

Version Specification

Xray server and Xray cloud both have versioned API endpoints with slightly different behaviour. By default, the clients access the latest documented version available for each endpoint.

You can switch between versions on an endpoint basis:

// Xray server:
const evidence = await serverClient.testRun.evidence.getEvidence("12345"); // 2.0 endpoint
const evidence = await serverClient.testRun.evidence.v1.getEvidence("12345"); // 1.0 endpoint

// Xray cloud:
const attachment = await cloudClient.attachment.addAttachment("my-file.txt"); // v2 endpoint
const attachment = await cloudClient.attachment.v1.addAttachment("my-file.txt"); // v1 endpoint

Custom HTTP Agents

The clients can use custom HTTP agents in the form of custom fetch implementations. The recommended approach is to use undici, which is already included in Node.js but is not exposed.

Note

Make sure to install the version of undici that comes with the installed version of Node.js to avoid version conflicts and typing issues:

npm install undici@$(node -e "console.log(process.versions.undici)")

import { ProxyAgent, fetch } from "undici";

const proxyAgent = new ProxyAgent({
  token: Buffer.from("username:password").toString("base64"),
  uri: "http://1.2.3.4:8765",
});

const configuration: ClientConfiguration = {
  fetch: (url, init) => {
    return fetch(url, { ...init, dispatcher: proxyAgent });
  },
  credentials: { /* ... */ },
  url: ...
};

Error Handling

Requests may result in HTTP error responses (e.g. 400 Bad Request, 403 Forbidden, 500 Internal Server Error) depending on the request configuration. The clients always throw errors when the actual response status does not match the expected status defined internally for each endpoint.

Note

Unfortunately, Xray's official documentation is not always precise about error response formats. The error responses also vary between Xray server/cloud and based on the Jira/Xray versions present. It is therefore impossible for the clients to directly model all error responses.

To handle response errors gracefully, use isResponseError to adapt possible outcomes to your Xray environment:

import { isResponseError } from "@qytera/xray-client";

try {
  const data = await client.import.execution.xray(/* ... */);
  // ...
} catch (error: unknown) {
  if (isResponseError(error)) {
    // access request/response data
    console.error("request failed:", error.request.url);
    console.error("request failed:", error.response.json.details);
  } else {
    // ...
  }
}

You can also easily define your own expected response error details and distinguish between them:

import { isResponseError } from "@qytera/xray-client";

try {
  const data = await client.import.execution.xray(/* ... */);
  // ...
} catch (error: unknown) {
  if (isResponseError(error, 400)) {
    console.error("Bad Request:", error.response.text);
  } else if (isResponseError<{ missingPermission: string }>(error, 403)) {
    console.error("Forbidden:", error.response.json.missingPermission);
  } else {
    console.error("Unexpected error:", error);
  }
}

Credits

This project was heavily inspired by jira.js.