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

$3

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

$3

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

$3

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

$3

- Cypress plugin (CI-safe, non-interactive)
- CLI (local workflows, debugging, ad-hoc tasks)

---

Architecture Overview

The package is intentionally layered:

- Gateways
Low-level Jira & Xray API wrappers

- Services
Business logic (batch updates, transitions, resolution)

- Controllers
Task-level orchestration (prime plans, import executions)

- Factory
Centralized config validation + gateway instantiation

- CLI / Cypress Plugin
Thin interfaces over the same core logic

---

Installation

``bash
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 load .env files itself.
Your Cypress project is responsible for loading environment variables.

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

---

CLI

`bash
$ 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
| ---
| (*): Quit
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
`

$3

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

---

Testing

`bash
npm test
``

---

License

MIT