@qytera/xray-client
v4.0.0TypeScript
A typesafe HTTP client for the Xray API.
0/weekUpdated 10 months agoMITUnpacked: 1.2 MB
Published by dev@qytera.de
npm install @qytera/xray-client
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
- [x] GET /rest/raven/1.0/api/test
- [x] GET /rest/raven/1.0/api/settings/teststatuses
- [x] GET /rest/raven/1.0/api/test/{key}/testruns
- [x] GET /rest/raven/1.0/api/test/{key}/preconditions
- [x] GET /rest/raven/1.0/api/test/{key}/testsets
- [x] GET /rest/raven/1.0/api/test/{key}/testexecutions
- [x] GET /rest/raven/1.0/api/test/{key}/testplans
- Test Steps
- [x] GET /rest/raven/1.0/api/settings/teststepstatuses
- [x] GET /rest/raven/1.0/api/test/{testKey}/step
- [x] GET /rest/raven/1.0/api/test/{testKey}/step/{id}
- [x] PUT /rest/raven/1.0/api/test/{testKey}/step
- [x] POST /rest/raven/1.0/api/test/{testKey}/step/{id}
- [x] DELETE /rest/raven/1.0/api/test/{testKey}/step/{id}
- [x] GET /rest/raven/1.0/api/test/{testKey}/step/{id}/attachment
- [x] 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
- [x] 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}
- [x] 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
- [x] 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
- [x] GET /rest/raven/1.0/api/testrun/{id}/
- [x] GET /rest/raven/1.0/api/testrun/
- [x] 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}
- [x] GET /rest/raven/1.0/api/testrun/{id}/attachment
- [x] POST /rest/raven/1.0/api/testrun/{id}/attachment
- [x] DELETE /rest/raven/1.0/api/testrun/{id}/attachment
- [x] 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
- [x] POST /rest/raven/1.0/api/import/execution
- [x] 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
- [x] GET /rest/raven/2.0/api/test/{testKey}/steps
- [x] POST /rest/raven/2.0/api/test/{testKey}/steps
- [x] GET /rest/raven/2.0/api/test/{testKey}/steps/{stepId}
- [x] PUT /rest/raven/2.0/api/test/{testKey}/steps/{stepId}
- [x] DELETE /rest/raven/2.0/api/test/{testKey}/steps/{stepId}
- [x] GET /rest/raven/2.0/api/test/{testKey}/steps/{stepId}/attachments
- [x] DELETE /rest/raven/2.0/api/test/{testKey}/steps/{stepId}/attachment/{attachmentId}
- Test Run
- [x] GET /rest/raven/2.0/api/testrun
- [x] GET /rest/raven/2.0/api/testrun/{id}
- [x] 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
- [x] POST /rest/raven/2.0/api/import/execution
- [x] POST /rest/raven/2.0/api/import/execution/multipart
- Dataset
- [x] GET /rest/raven/2.0/api/dataset/export
- [x] 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
- [x] POST /api/v1/import/execution
- [x] 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
- [x] GET /api/v1/attachments/{attachmentId}
- [x] POST /api/v1/attachments
- v2
- Exporting Cucumber Tests
- [ ] GET /api/v2/export/cucumber
- Exporting Datasets
- [x] GET /api/v2/dataset/export
- Import Execution Results
- [x] POST /api/v2/import/execution
- [x] 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
- [x] GET /api/v2/attachments/{attachmentId}
- [x] POST /api/v2/attachments
- GraphQL
- query
- [ ] getFolder
- [ ] getTest
- [ ] getTests
- [ ] getExpandedTest
- [ ] getExpandedTests
- [ ] getCoverableIssue
- [ ] getCoverableIssues
- [ ] getPrecondition
- [ ] getPreconditions
- [ ] getTestSet
- [ ] getTestSets
- [x] getTestPlan
- [x] getTestPlans
- [x] getTestExecution
- [x] getTestExecutions
- [x] getTestRun
- [ ] getTestRunById
- [x] 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
- [x] addEvidenceToTestRun
- [x] removeEvidenceFromTestRun
- [ ] updateTestRunStep
- [ ] addEvidenceToTestRunStep
- [ ] removeEvidenceFromTestRunStep
- [ ] addDefectsToTestRunStep
- [ ] removeDefectsFromTestRunStep
- [ ] updateTestRunStepComment
- [ ] updateTestRunStepStatus
- [ ] updateTestRunExampleStatus
- [ ] updateIterationStatus
- [ ] setTestRunTimer
Installation
Xray Server
``bash`
npm install @qytera/xray-client
Xray Cloud
If you don't intend to use the GraphQL endpoints:
`bash`
npm install @qytera/xray-client
With GraphQL support:
`bash`
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
`ts
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
`ts
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:
`graphql`
{
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:
`ts`
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 a per-request basis:
`ts
// 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:
>
> `sh`
> npm install undici@$(node -e "console.log(process.versions.undici)")
>
`ts
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:
`ts
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:
`ts
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.