cypress-jira-xray

A Node.js toolkit for synchronizing Cucumber-based Cypress tests with Jira Xray Cloud, with additional migration/import utilities for TestRigor and TestRail.

This project is designed for teams who:

• Author tests in .feature files
• Run Cypress in CI
• Migrate existing automated or manual test assets into Jira/Xray
• Import TestRigor YAML tests as Jira/Xray Test issues
• Import TestRail cases as Jira/Xray Generic Tests
• Use Jira Xray Cloud for test management
• Want deterministic, automatable workflows (no manual UI steps)

What This Solves

Jira Xray Cloud provides APIs, but not opinionated workflows.

This tool fills that gap by providing:

• Automated import of .feature files as Xray Tests
• Automated creation and priming of Xray Test Plans
• Automated import of Cucumber JSON execution results
• Migration/import workflows for TestRigor YAML tests
• Migration/import workflows for TestRail case exports
• Consistent behavior across local dev, CI, and GitHub Actions
• A single config source of truth for Jira + Xray

Core Capabilities

Feature & Test Management

• Import .feature files into Xray
• Auto-tag scenarios with @TEST_* keys
• Fetch feature files from Xray
• Detect and reuse existing Test issues

Test Plan Automation

• Prime a Test Plan from local feature files
• Add or remove Tests from a Test Plan
• Safe handling of already-linked Tests

Execution Reporting

• Import Cucumber JSON results
• Create Test Executions automatically
• Optionally transition execution issues

Migration & Import Utilities

• Import TestRigor YAML tests into Jira/Xray as Test issues
• Import TestRail case exports into Jira/Xray as Generic Tests
• Preserve TestRail hierarchy context with optional section-map labels
• Organize imported TestRail tests into Xray Test Repository folders

Jira Utilities

Additional CLI utilities for managing Jira issues in bulk.

Current utilities include:

• Set the Account field for multiple Jira issues
• Set the Parent field for multiple Jira issues
• Interactive account selection
• Support for CLI flags
• Accept Jira issue keys as comma, space, or newline separated input

Architecture Overview

The package is intentionally layered:

Gateways

Low-level Jira & Xray API wrappers.

Services

Business logic such as batch updates, transitions, and resolution.

Controllers

Task-level orchestration such as priming plans and importing executions.

Factory

Centralized config validation + gateway instantiation

CLI / Cypress Plugin

Thin interfaces that execute the same core logic.

Installation

npm install --save-dev cypress-jira-xray

Requirements

• Node.js 18+
• Jira Cloud
• Xray Cloud
• Cypress 14+ for Cypress plugin/reporting workflows
• Cucumber .feature files for feature import and test plan priming
• Cucumber JSON execution output for Cypress execution reporting
• TestRigor YAML exports for TestRigor migration workflows
• TestRail case exports for TestRail migration workflows

Usage with Cypress

See full configuration examples in the repository:

./examples/cypress-jira-xray.config.js

The package does not automatically load .env files when used as a Cypress plugin.

Your Cypress project is responsible for loading environment variables (for example via dotenv in cypress.config.{js,ts} or your test runner).

Note: The standalone CLI (bin/cli.js) does call require('dotenv').config(), so variables from a local .env file are available when running commands directly from the terminal.

Example:

JIRA_API_TOKEN=xxxxxxxx
XRAY_CLIENT_ID=xxxxxxxx
XRAY_CLIENT_SECRET=xxxxxxxx
XRAY_TEST_PLAN_KEY=MB-12345

CLI

$ npx cypress-jira-xray


|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|| Welcome to the Cypress-Jira-Xray Integration Tool
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|     1: Import Feature(s)
|     2: Import Execution Run
|     3: Get a feature from Jira Xray
|     4: Get a Test from Jira Xray
|     5: Prime a test plan
|     6: Set Account for Jira Issues
|     7: Set Parent for Jira Issues
|     8: Import TestRigor YAML Tests to Jira/Xray
|     9: Import TestRail Cases to Jira/Xray
|   ------------------------------------
|   (*): Quit
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

CLI Commands

1: Import Feature Files

Imports local .feature files into Jira Xray as Test issues.

npx cypress-jira-xray import-feature

2: Import Execution Results

Imports Cucumber JSON execution results into Xray.

npx cypress-jira-xray import-execution --plan MB-12345

3: Fetch Feature Files from Xray

Downloads feature files stored in Jira Xray.

npx cypress-jira-xray get-feature

4: Fetch a Test from Xray

Downloads a single Xray test by Jira issue key.

npx cypress-jira-xray get-test

5: Prime Test Plan

Adds all tests referenced in local feature files to a Jira Xray Test Plan.

npx cypress-jira-xray prime --plan MB-12345 --dir cypress/integration/cucumber

6: Set Account for Jira Issues

Updates the Account field for multiple Jira issues.

7: Set Parent for Jira Issues

Updates the Parent field for multiple Jira issues.

8: Import TestRigor YAML Tests

Imports TestRigor YAML test definitions into Jira/Xray as Test issues.

npx cypress-jira-xray import-testrigor-yaml --dir ./testRigor/testcases

9: Import TestRail Cases

Imports TestRail case exports into Jira/Xray as Generic Tests.

npx cypress-jira-xray import-testrail-cases --input ./TestrailCases.json

10: Organize Imported TestRail Tests

Organizes imported TestRail tests into Xray Test Repository folders.

npx cypress-jira-xray organize-testrail-repository --input ./TestrailCases.json

Interactive Usage

npx cypress-jira-xray

Non-interactive Usage

Using account name

npx cypress-jira-xray set-account \
--issues MB-12345,MB-12346 \
--account "Core Product Development"

Using numeric account ID

npx cypress-jira-xray set-account \
--issues MB-12345,MB-12346 \
--account 17

Setting Account [Core Product Development] for 2 issue(s)...
Updated MB-12345
Updated MB-12346
✅  Account update completed.

Testing

npm test

TestRail Section Map Support (Optional)

When importing TestRail test cases into Jira/Xray, the importer can optionally generate labels based on the original TestRail folder / section hierarchy.

Example generated label:

testrail-path-Marketing>GiftCertificates>ServiceCertificates

This helps preserve the original organizational structure from TestRail and can later be used for:

• Xray Test Repository folder organization
• Test Set generation
• Jira JQL filtering
• Migration traceability
• QA team transition from TestRail → Xray

Exporting TestRail Sections

The importer supports providing a TestRail Sections JSON export file.

TestRail API endpoint:

/api/v2/get_sections/${PROJECT_ID}&suite_id=${SUITE_ID}

Example:

https://yourcompany.testrail.io/index.php?/api/v2/get_sections/1&suite_id=1

IMPORTANT: Pagination

TestRail paginates section results.

Default limit:

250 sections

The API response includes pagination links:

"_links": {
    "next": "/api/v2/get_sections/1&suite_id=1&limit=250&offset=250",
    "prev": null
}

If _links.next exists, additional section pages must also be fetched and merged.

Failure to include all section pages may result in:

• incomplete hierarchy resolution
• missing parent sections
• incorrect generated path labels

Saving the Section Map File

Save the combined JSON response as a file such as:

./TestrailSectionMap.json

CLI Usage

When using the interactive CLI:

npx cypress-jira-xray

The importer will prompt for:

Enter TestRail Section Map file path

Press ENTER to use the default:

./TestrailSectionMap.json

Optional Feature

The Section Map file is NOT required.

Imports will still function normally without it.

However, without the Section Map file:

• hierarchy-based labels will not be generated
• original TestRail folder structure cannot be reconstructed automatically

Example labels generated when provided:

testrail-path-Marketing>GiftCertificates>ServiceCertificates
testrail-path-Schedule>BookAppointment
testrail-path-CRM>SOAPNotes

License

MIT