cypress-xporter
Version:
CLI tool to sync Cypress test results with Jira, TestRail, and Confluence.
253 lines (189 loc) âĸ 8.99 kB
Markdown
# đ Cypress Xporter
[](https://www.cypress.io/)
[](https://www.atlassian.com/software/jira)
[](https://www.atlassian.com/software/confluence)
[](https://www.testrail.com/)
**Cypress Xporter** is a CLI tool that syncs your Cypress test results with **Jira**, **TestRail**, and **Confluence**. It automates the process of merging test reports, creating bug tickets, updating test plans, and documenting test summaries â all from your terminal.
---
## đ Table of Contents
- [⨠Features](#-features)
- [đĻ Installation](#-installation)
- [âī¸ Environment Setup](#-environment-setup)
- [đ Usage](#-usage)
- [đ Example CLI Commands](#-example-cli-commands)
- [đ§ CI/CD Integration](#-cicd-integration)
- [GitHub Actions](#github-actions)
- [Jenkins](#jenkins)
- [đ Token & ID Setup Help](#-token--id-setup-help)
- [đˇ Screenshots](#-screenshots)
- [đ ī¸ Version](#-version)
- [đ License](#-license)
---
## ⨠Features
- â
Automatically creates Jira bugs for failed tests
- â
Logs test results in TestRail test runs
- â
Publishes Cypress test dashboards to Confluence pages
- â
Merges all `mochawesome*.json` reports automatically
- â
Supports flexible CLI flags (`--jira`, `--testrail`, `--confluence`)
---
## đĻ Installation
### Dependency:
- â
`"NODE": "^22.12.0"`
- â
`"npm": "^11.0.0"`
- â
`"cypress": "12.x.x,13.x.x, and 14.x.x" OR higher`
- â
`"axios": "^1.8.4"`
- â
`"dotenv": "^16.4.7"`
- â
`"fast-glob": "^3.3.3"`
- â
`"chalk": "^4.1.2"`
- â
`"form-data": "^4.0.0"`
- â
`"minimist": "^1.2.8"`
### Global installation:
```bash
npm install cypress-xporter
or
npm install cypress-xporter --save-dev
```
---
## âī¸ Environment Setup
Create a `.env` file in your project root:
```env
# JIRA
JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-jira-api-token
JIRA_PROJECT_KEY=PROJECTKEY
# TESTRAIL
TESTRAIL_DOMAIN=https://yourcompany.testrail.io
TESTRAIL_USERNAME=testrail@example.com
(opt) TESTRAIL_API_KEY=your-testrail-api-key
TESTRAIL_PASSWORD=your-testrail-password
TESTRAIL_PROJECT_ID=ProjectID
# CONFLUENCE
CONFLUENCE_BASE_URL=https://your-domain.atlassian.net
CONFLUENCE_USERNAME=your-email@example.com
CONFLUENCE_API_TOKEN=your-confluence-token
CONFLUENCE_SPACE_KEY=SPACEKEY
CONFLUENCE_PARENT_PAGE_ID=Folder |OR| PageID
```
---
## đ Usage
> **âšī¸ Note:**
> When writing your Cypress tests, you can include the TestRail ProjectID or Test Case ID in the test name using the following format:
> ### Handle ProjectID dynamically
> ```javascript
> describe( '[P<ID>][S<ID>] Multi Project and Handle ProjectID dynamically', () =>
> {
> it( '<Test Name> [C<ID>]', () =>
> {
> // Your test code here
> } );
> } );
> ```
> To Dynamically handle ProjectID replace `[P<ID>]` `[S<ID>]`with the corresponding TestRail ProjectID and SuiteId This helps Cypress Xporter map the test results to the correct TestRail test cases.
> Replace `<Test Name>` with the name of your test and `[C<ID>]` with the corresponding TestRail Case ID. This helps Cypress Xporter map the test results to the correct TestRail test cases.
> ### Handle ProjectID from .ENV
> ```javascript
> describe( 'Make sure .env has the projectID', () =>
> {
> it( '<Test Name> [C<ID>]', () =>
> {
> // Your test code here
> } );
> } );
> ```
> Replace `<Test Name>` with the name of your test and `[C<ID>]` with the corresponding TestRail Case ID. This helps Cypress Xporter map the test results to the correct TestRail test cases.
### After running Cypress tests (with Mochawesome reporter):
```bash
npx cypress-xporter --jira --testrail --confluence
```
Cypress Xporter will:
1. Search for all `mochawesome*.json` reports across the project
2. Merge them into a single report
3. Create Jira tickets for failed tests (if `--jira` is passed)
4. Log results to TestRail (if `--testrail` is passed)
5. Generate a dashboard and upload to Confluence (if `--confluence` is passed)
> **Note:**
> To successfully publish dashboards to Confluence, ensure that the **Confluence HTML Macro** is enabled in your Confluence instance. Without this macro, embedded HTML dashboards may not render correctly on your Confluence pages.
---
## đ Example CLI Commands
```bash
# Run everything
npx cypress-xporter --jira --testrail --confluence
# Only push to Jira and TestRail
npx cypress-xporter --jira --testrail
# Only push to Confluence
npx cypress-xporter --confluence
```
Or via npm script (defined in root `package.json`):
```bash
npm run run-all-tools
npm run run-jira-testrail
npm run run-testrail
```
---
## đ§ CI/CD Integration
### GitHub Actions
```yaml
- name: Run Cypress Tests
run: npm run cy:run
- name: Report with Cypress Xporter
run: npx cypress-xporter --jira --testrail --confluence
env:
JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
...
```
### Jenkins
In your pipeline script:
```bash
npm install
npx cypress run
npx cypress-xporter --jira --testrail --confluence
```
---
## đ Token & ID Setup Help
- đ [Get a Jira API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
- đ [Get a Confluence API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
- đ [Get a TestRail API key](https://support.testrail.com/hc/en-us/articles/7077039051284-Accessing-the-TestRail-API#h_01J53NS43210J0AN0TV6JPHVYY)
- đ **JIRA_PROJECT_KEY** â Can be found in the project settings (e.g., `ABC`)
- đ **TESTRAIL_PROJECT_ID** â Use TestRail API or UI to identify
- đ **CONFLUENCE_SPACE_KEY** â Space key shown in your space URL (e.g., `TEST`)
- đ **CONFLUENCE_PARENT_PAGE_ID** â ID of the parent page/folder where test logs go (check Confluence URL or API)
---
## đˇ Screenshots
### CLI Execution
### Test Results Dashboard
### Jira Bug Ticket Example
### Confluence Test Summary
## đ ī¸ Version
### ^2.4.0
1. Parses Cypress mochawesome reports.
2. Extracts ProjectID and Case IDs from test titles.
3. For each unique ProjectID:
- Queries all Suites.
- Finds the matching Suite containing all Case IDs.
4. Creates a TestRail Run with the correct Suite and Case IDs.
5. Posts test results to the newly created Test Run.
6. Automatically closes the Test Run after posting results.
7. Dynamic Run Name Based on File Path
- Now accepts `runName` as a parameter.
- If 2+ folders: **Folder1-Folder2 Automated Run** with `<date>` :: _e.g._ `cypress/e2e/Shopping/Smoke`
- If 1 folder: **Folder1 Automated Run** with `<date>` :: _e.g._ `cypress/e2e/Smoke`
- If none: **Automated Cypress Run - `<date>`**
<br>
| **Before** | **After** |
|----------------------------------------------------|------------------------------------------------------------------|
| â Could only work with static `.env` ProjectID | â
Dynamic ProjectID works from `[P2]` |
| â 400 Error: `case_ids` unrecognized if wrong suite used | â
Dynamically finds the correct `suite_id` `[S1]` |
| â Poor debug logs when things fail | â
Clean, visible logs for ProjectID, SuiteID, CaseIDs |
| â Unscalable for multiple projects | â
Now supports multiple Projects and Suites automatically |
| â Needed manual hardcoding | â
100% automatic detection |
| â Manual step needed to close test run | â
Automatically closes TestRail run after results are posted |
## đ License
MIT Š [Kabir Faisal](https://kabirfaisal1.github.io/myReactProtfolio/#/) | [Linkedin](https://www.linkedin.com/in/kabirfaisal89/) |
[Discord](https://discord.gg/MFh6gYZB)