How Can You Create an XRAY JSON Report with AskUI?

July 8, 2025

The image features a tablet displaying a bar chart on the right side, with data increasing over time, symbolizing reports or progress. On the left side, a maroon background contains white text that reads: "Create XRAY JSON Report And Upload it via API." Above the text is a rounded rectangle with the word "Academy." The design highlights learning content focused on generating and uploading XRAY JSON reports through an API.

To integrate UI test results directly into Jira XRAY, you can use the AskUIXRayStepReporter. This reporter creates XRAY-compatible JSON files, including step-level results and screenshots, for seamless quality tracking.

What Are the Prerequisites for Using the AskUI XRAY Reporter?

To follow this guide, make sure you have:

AskUI installed on Windows, Linux, or macOS.
Access to your Jira/XRAY server with REST API enabled.
API credentials: CLIENT_ID, CLIENT_SECRET, JIRA_SERVER_URL, and your PROJECT_KEY stored as environment variables (for CI/CD).

How Do You Enable the AskUIXRayStepReporter in Your Tests?

By default, AskUI uses an Allure reporter. To switch to XRAY reporting:‍

1. Edit your helper/askui-helper.ts file:

import { UiControlClient } from 'askui';
import { AskUIXRayStepReporter } from '@askui/askui-reporters';

let aui: UiControlClient;
jest.setTimeout(60 * 1000 * 60);

let xRayReporter: AskUIXRayStepReporter;

beforeAll(async () => {
  xRayReporter = new AskUIXRayStepReporter({
    // withScreenshots: 'always',
  });
  aui = await UiControlClient.build({ reporter: xRayReporter });
  await aui.connect();
});

beforeEach(async () => {
  xRayReporter.createNewTestEntry(global.testName);
});

afterEach(async () => {
  xRayReporter.finishTestEntry(global.testStatus);
});

afterAll(async () => {
  await xRayReporter.writeReport();
  aui.disconnect();
});

export { aui };

‍

2. Activate the special Jest environment in your jest.config.ts to capture the it block names as test keys:

import type { Config } from '@jest/types';

const config: Config.InitialOptions = {
  preset: 'ts-jest',
  testEnvironment: '@askui/askui-jest-xray-environment',
  setupFilesAfterEnv: ['./helpers/askui-helper.ts'],
  reporters: ["default"]
};

export default config;

What Does a Generated XRAY JSON Report Look Like?

The XRAY JSON file maps each Jest it block to a test case. It also includes step statuses and base64-encoded screenshots.

Example snippet:

{
  "tests": [
    {
      "testKey": "TEST1",
      "start": "2025-07-08T12:17:05.998Z",
      "steps": [
        {
          "status": "PASS",
          "evidences": [
            {
              "data": "iVBORw0KGgoAAAANSUhEUgA...",
              "filename": "before.png",
              "contentType": "image/png"
            }
          ]
        }
      ],
      "finish": "2025-07-08T12:17:10.852Z",
      "status": "FAIL"
    }
  ]
}

👉 You can configure screenshots to be taken on fail only or always.

How Do You Upload the JSON Report to XRAY via REST API?

Use XRAY’s REST API to push your results. In CI/CD (like GitLab), you might:

Run your tests and generate xray-report/report.json.
Obtain an auth token from Jira.
POST your report to XRAY.

Example job flow in GitLab:

transfer-report-to-xray-job:
  script:
    - export TOKEN=$(curl -X POST "$JIRA_SERVER_URL" -d ...)
    - curl -X POST "$JIRA_SERVER_URL/rest/raven/1.0/import/execution"
      -H "Authorization: Bearer $TOKEN"
      -F "file=@xray-report/report.json"

What Are the Key Benefits for QA Teams?

End-to-end visibility: Link UI automation with manual test cases in XRAY.
Detailed evidence: Each step can include screenshots, improving audit and defect discussions.
CI/CD integration: Automate quality gates in pipelines.

Frequently Asked Questions (FAQ)

Can I use this with Allure too?

Yes. AskUI supports multiple reporters. Configure either Allure or AskUIXRayStepReporter in your helper file.

Will screenshots slow down my tests?

Minimal. But you can toggle screenshots to fail-only or always based on your QA needs.

Related Resources

Conclusion: A Smarter Way to Manage Test Evidence in Jira

The AskUIXRayStepReporter closes the gap between UI automation and Jira XRAY’s manual testing workflows. It ensures your team gets reliable, visual documentation — directly inside your existing QA hub.

For a full sample project with all configuration files, visit our AskUI XRAY example repo on GitHub.

Youyoung Seo