Troubleshooting and migration¶
Invalid defects marker (0.1.5+): when --jira-xray is enabled, defects
must be a list of nonempty strings. For example, change the marker on your test to:
Use defects=[] or omit it when there are no defects. Do not pass a bare string
(defects="BUG-1"), tuple, None, numbers, empty strings or whitespace-only
strings. Values are not trimmed or checked against a Jira-key regex; Jira/Xray
still determines whether a supplied key exists and is usable.
Run the same offline preview command from the tutorial. Malformed defects now
produce a collection error before any test fixtures run, in serial and xdist.
Uploads are withheld, even with --continue-on-collection-errors; a local preview
may contain an empty tests list for diagnosis. The error describes the required
shape without displaying defect values. Fix the marker and rerun. Ordinary pytest
runs and local-case reporting without --jira-xray do not apply this validation.
--collect-only retains its existing behavior of not configuring Xray reporting;
it lists tests but does not validate these markers, run fixtures or upload.
This validates marker configuration only; it does not contact Jira or validate
credentials. Earlier versions could fail later inside report hooks or retain
invalid values in export payloads.
| What happened | What to do |
|---|---|
unrecognized arguments |
Activate the intended environment and use python -m pytest. Check python -m pip show pytest-jira-xray-plus. If plugin autoload is disabled, add -p pytest_xray.plugin. |
| Duplicate plugin/import errors | Create a fresh environment with this fork only, not upstream pytest-jira-xray. |
| Duplicate Jira IDs | Add --allow-duplicate-ids only when the cases intentionally share one Test. |
No xray.json |
Use both --jira-xray and --xraypath=xray.json. Case reporting is separate. |
| Cannot write a report | Check permissions and distinct paths. Create the case-report parent folder. A previous file retained after failure is not a new result. |
| Comment exceeds the limit | Add --xray-full-report=PATH to retain full text before truncation; inspect the resulting export. |
| Missing authentication variable | Set the variables for your selected auth method. Offline file exports do not need credentials. |
| HTTP 401/403 | Check existing credentials and permissions with the sandbox administrator. Do not paste secrets into issue reports. |
| HTTP 404 or redirect | Check the base URL, context path and Server/DC versus Cloud mode. |
| Certificate error | Configure the trusted CA bundle; do not bypass verification. |
| Timeout, invalid JSON or missing execution ID | Inspect local server/proxy information and check whether the import already succeeded before retrying. |
| No native parameter rows | Expected: this exporter provides aggregate status and optional comment detail, not native iterations. |
From upstream: create a fresh environment and install pytest-jira-xray-plus.
The Python imports, marker and xray plugin name are retained. Check the dependency
requirements, add local reporting as needed, and compare an offline export before
uploading. Do not install both distributions together.
From 0.1.0–0.1.2: 0.1.3 confirms Generic as the target Test type in the documentation; runtime behavior is unchanged. From 0.1.0a1: later releases add bounded comments, meaningful publishing failures, atomic file export and failure-preserving rerun summaries; update CI expectations.