cypress-jira-xray

A Node.js + Cypress integration toolkit for synchronizing Cucumber-based Cypress tests with Jira Xray Cloud.

This project is designed for teams who:

• Author tests in .feature files
• Run Cypress in CI
• 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
• 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

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+
• Cypress 14+
• Jira Cloud
• Xray Cloud
• Cucumber .feature files
• Cucumber JSON execution output

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: Prime a test plan w/ all test keys from local feature files
|     5: Set Account for Jira Issues
|     6: Set Parent for Jira Issues
|   ------------------------------------
|   (*): 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: 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

5: Set Account for Jira Issues

Updates the Account field for multiple Jira issues.

6: Set Parent for Jira Issues

Updates the Parent field for multiple Jira issues.

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

License

MIT