xray-formatter

library2.1.5jsnpmunverified

A Cucumber formatter for Xray Jira plugin that generates test execution reports in Xray JSON format and optionally uploads results directly to Jira. Current version 2.1.5, stable with minor updates. Supports capturing test results from Cucumber scenarios tagged with Jira issue keys, including automatic status updates (PASS/FAIL/TODO) and handling of Scenario Outlines to prevent false positives. Differentiates from generic formatters by direct Jira integration and CLI tools (xray-upload, xray-clear, xray-extract, xray-import).

testing

npm install xray-formatter

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · XRAY-FORMATTER

xray-formatter

testingjavascriptv2.1.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

xray-formatter

✓ configure in Cucumber config as format: 'xray-formatter:reports/xray.json'

✗ import * as xform from 'xray-formatter'

This package is a Cucumber formatter, not a library. It must be configured in your Cucumber config file (e.g., .cucumber-rc.js) under the 'format' option.

jiraOptions

✓ set in formatOptions.jiraOptions in Cucumber config

✗ require('xray-formatter').jiraOptions = {...}

jiraOptions is not imported; it's a config object passed to the formatter via formatOptions in Cucumber config file.

CLI commands (xray-upload, xray-clear, xray-extract, xray-import)

✓ npx xray-upload ...

✗ require('xray-formatter').upload()

CLI commands are run via npx or adding to package.json scripts. They are not exported JS functions.

Configure xray-formatter as Cucumber formatter with Jira integration, using environment variables for sensitive data.

// .cucumber-rc.js module.exports = { default: { format: [ 'xray-formatter:reports/xray.json', ], formatOptions: { jiraOptions: { regexp: /(PC-\d+)/, report: './reports/xray.json', endpoint: process.env.JIRA_ENDPOINT ?? '', token: process.env.JIRA_TOKEN ?? '', execution: process.env.JIRA_EXECUTION ?? '', }, }, }, };

Debug

Known issues

gotchaThe formatter uses the first Jira tag found; if multiple tags, other tags are ignored.

fix

Ensure each scenario has exactly one Jira tag or order desired tag first.

affects: >=0.0.0

gotchaScenario Outline examples: the formatter will not change a test status from FAIL to PASS to avoid false positives; requires manual reset or resetTests option.

fix

Set tests to 'TODO' manually or add 'resetTests: true' in jiraOptions.

affects: >=0.0.0

gotchaOptions 'endpoint', 'token', and 'execution' are required for automatic upload. If missing, results are only saved to file.

fix

Provide all three options or omit them if only file output is needed.

affects: >=0.0.0

gotchaRegular expression must capture Jira ID as first group. Incorrect regex leads to empty test key errors.

fix

Test regex with sample tags; ensure first capturing group matches the ID (e.g., /(PC-\d+)/).

affects: >=0.0.0

Errors

Common errors & fixes

Error: No jiraOptions.regexp provided. Cannot extract test key.

Missing regexp option in jiraOptions.

fix

Add 'regexp: /(YOUR-TAG-PREFIX-\d+)/' to formatOptions.jiraOptions.

Error: options.endpoint, options.token, and options.execution must be provided when uploading results

Missing required options for automatic upload.

fix

Set endpoint, token, and execution in jiraOptions.

TypeError: Cannot read property '0' of null

Regular expression does not match any tag or returns null.

fix

Check that tags follow pattern matched by regex; adjust regex if needed.

Upgrade

Version history

2.1.5latest on npm

Audit

Dependencies

@cucumber/cucumberoptionalpeer dependency for Cucumber formatter interface

Agent activity

24 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/VolhaValasevich/xray-formatter ↗

packagexray-formatter ↗

homepagehttps://github.com/VolhaValasevich/xray-formatter#readme ↗