Pytest JIRA XRAY Plugin

0.9.3 · active · verified Fri Apr 17

pytest-jira-xray is a pytest plugin that facilitates integration of test results with Atlassian JIRA's XRAY Test Management tool. It allows users to export pytest test results to XRAY JSON format or directly upload them to JIRA, associating tests with JIRA issues and updating test plans/executions. The current version is 0.9.3, and it appears to be actively maintained with releases tied to new features or bug fixes.

Common errors

```
Jira Xray API Error: 401 Unauthorized
```
cause Incorrect JIRA URL, username, or password provided. The credentials do not have permission to access JIRA or the XRAY API.

fix Verify your JIRA_URL, JIRA_USER, and JIRA_PASSWORD (or corresponding CLI arguments/pytest.ini entries) are correct and that the user has necessary permissions in JIRA and XRAY. Test credentials separately if possible.
```
Error: the following arguments are required: --xray-json
```
cause You are trying to run pytest-jira-xray without specifying an output file for the XRAY JSON report or explicitly disabling JSON output when uploading results directly.

fix If you want to generate a JSON report, add `--xray-json=<path/to/report.json>`. If you are uploading directly to Jira and don't need a local JSON file, you still need to ensure `--upload-xray-results` is used correctly with JIRA credentials and test execution details.
```
XRAY: The Test Plan with key 'XXX-YYY' does not exist.
```
cause The Test Plan key provided with `--testplan-key` does not correspond to an actual Test Plan in JIRA.

fix Double-check the Test Plan key for typos or ensure that the Test Plan actually exists in your JIRA instance and is accessible to the provided JIRA user.
```
Cannot assign a test case key 'TEST-XXX' to a test method because it already exists in a different test execution.
```
cause This usually happens when trying to update test cases in a Test Execution where the link between the test method and XRAY Test Case is already established differently or there's a conflict in how tests are mapped.

fix Verify that your test methods are uniquely mapped to XRAY Test Cases via the `@pytest.mark.jira(test_key='TEST-XXX')` marker. If you're using Test Plans, ensure the test cases are correctly associated within the plan.

Warnings

gotcha Authentication details (JIRA URL, user, password) can be provided via command-line arguments, environment variables (JIRA_URL, JIRA_USER, JIRA_PASSWORD), or `pytest.ini`. Command-line arguments take precedence over environment variables, which take precedence over `pytest.ini`.
Fix: Be mindful of the precedence order. For CI/CD, environment variables are often preferred for security and flexibility. For local development, `pytest.ini` can be convenient.
gotcha When uploading results to a new or existing Test Execution, you must provide either `--testplan-key` to create a new execution under that plan, or `--testexecution-key` to update an existing execution.
Fix: Ensure you include the appropriate flag (`--testplan-key <KEY>` or `--testexecution-key <KEY>`) with your `pytest` command when using `--upload-xray-results`.
gotcha The plugin relies on specific XRAY API endpoints. Differences between XRAY Cloud and XRAY Data Center/Server versions can sometimes cause unexpected behavior, although the plugin generally attempts to abstract these.
Fix: Consult the official pytest-jira-xray documentation and XRAY API documentation if you encounter unexpected errors, especially when interacting with different JIRA/XRAY hosting types. Ensure your JIRA instance and XRAY plugin are up-to-date.

Install

pip install pytest-jira-xray Install stable version

Imports

pytest.mark
```
import pytest
```
While not importing a specific class from the plugin, users interact with it primarily through pytest markers, e.g., @pytest.mark.jira(key='TEST-123').

Quickstart

This quickstart demonstrates creating a test file with JIRA markers and running pytest to generate an XRAY JSON report and upload results to a specified Test Plan/Execution. Authentication details (URL, user, password) can be provided via command-line arguments, environment variables, or configured in `pytest.ini`. For security, using environment variables for sensitive data is recommended.

# my_test.py
import pytest

@pytest.mark.jira(key='TP-100', test_key='TEST-456')
def test_example_success():
    assert True

@pytest.mark.jira(key='TP-100', test_key='TEST-457')
def test_example_failure():
    assert False

# pytest.ini
# [pytest]
# jira-url = https://your-jira-instance.com
# jira-user = your-username
# jira-password = your-password

# Run from terminal:
# export JIRA_URL='https://your-jira-instance.com'
# export JIRA_USER='your-username'
# export JIRA_PASSWORD='your-password'
# pytest --xray-json=xray_report.json --jira-url "${JIRA_URL}" --jira-user "${JIRA_USER}" --jira-password "${JIRA_PASSWORD}" --testplan-key "TP-100" --testexecution-key "TP-EXEC-123" --upload-xray-results

view raw JSON →