xray-cli

Xray CLI - Test Management

Compact Rules

• DO: confirm the project is in Modality jira-xray before invoking anything here; a jira-native project (no Xray plugin) routes to /acli instead. Modality is resolved once in /test-documentation Phase 0 and inherited downstream, never re-decided mid-flow.
• DO NOT: call this CLI from a workflow skill. Workflow skills write [TMS_TOOL] pseudocode and load this skill; only this skill owns the literal syntax.
• DO: pass an explicit --limit above the expected count on every list command — all of them default to a small --limit (see cli/xray) and truncate silently. Read the true count from the (N total) header, never by counting rows; a truncated read looks exactly like data loss.
• DO: capture the key of anything you create from the bare KEY <PROJ-123> line or from --json, never by scraping the decorated success line — a create whose key was not captured leaves an orphan artifact nothing downstream can link.
• DO NOT: pass Manual steps inline when creating a test — Xray Cloud silently drops them. Create the test first, add one step per call, then verify the steps landed.
• DO: pin every ATR execution to a Test Environment (value from active_env), so results stay comparable across runs. An execution that slipped through without one is repaired in place, not left.
• DO: keep the Set-first cascade: the per-Story ATS holds the membership, and the Plan (ATP) and Execution (ATR) derive their test lists from it rather than maintaining their own.
• DO: fill Story coverage with the Jira-layer issue link from the ATS to the Story. Plan→Story and Execution→Story links are administrative traceability and cover nothing; a direct Test→Story link is a last resort for an instance with no Test Set work type. Plan/Execution/Set MEMBERSHIP is Xray-internal GraphQL; membership of the Story's ATS is ALSO a TC→ATS test issue link (link create <TC> <ATS> --type test), in both modalities (agentic-qa-core/references/traceability-linking.md §9).
• DO: state the coverage direction as the RAW FIELD, never as an outward/inward description: on a Story, the counting edge is the issuelinks entry carrying the artifact under inwardIssue. The artifact-first argument order produces it. Verify against Xray coverage (the three-edge check or the coverage panel), never against Jira link semantics — a Jira link list looks correct in both directions.
• DO: replace an inverted coverage link, never add a corrected one on top: Jira dedupes a link between the same pair and type regardless of direction, so the create is a silent no-op until the wrong link is deleted by its own link id. Read the id first, dry-run, then delete with an explicit confirmation.
• DO: verify traceability with the one-call three-edge check, never from the coverage edge alone — a missing ATP→Story or ATR→Story link is a FAIL, not a warning, and the same call compares the ATS membership against the Plan and Execution test lists. Sweep a whole project (several keys or a JQL query) at least once per engagement: an inverted link is invisible per Story and only reads as a pattern in aggregate.
• DO: treat Xray run statuses as PER-INSTANCE vocabulary. TODO / EXECUTING / PASSED / FAILED are the safe floor; ABORTED and BLOCKED are Xray defaults a project may not define, and the mutation is rejected when it does not. Record a blocked case in a status the project DOES define and explain it in the run comment — never leave the run TODO, which reads as never executed.
• WHEN a Jira-fallback path created the container without authenticated Xray: the Xray layer never registered the tests and runs come back empty. Reconcile with the per-entity sync (or the bulk repair scan) before importing results.
• DO: import results onto an existing Execution key, never scoped to a project — the import API cannot set a parent, so a project-scoped import mints a fresh unparented Execution on every run, outside the artifact ladder.
• DO NOT: hand-craft Xray JSON payloads outside this CLI, or reuse a bearer token past its 24h TTL. A stale token produces silent 401s mid-import that read like network blips.
• DO: dry-run any import or backup restore before applying. Both write irreversibly across hundreds of tests and runs.
• WHEN moving between sites: restore in sync-by-key mode (GraphQL ids are re-assigned per site, keys are not), re-authenticate between export and restore because auth holds ONE site at a time, and finish with the Jira instance-migration flow — field ids are reassigned and an old id silently resolves to a different field.
• DO NOT: push run results for TCs the ROI verdict marked terminal-Manual. It creates audit noise and breaks the Candidate / Manual / Deferred reporting.
• WHEN Xray credentials are missing or broken: STOP per Critical Rule #10 — name XRAY_CLIENT_ID / XRAY_CLIENT_SECRET, point at .env, ask for a session restart. Nothing reaches the Xray GraphQL layer without them.