Use for any question or task about managing test cases in TestRail, Xray, Zephyr Scale, Allure TestOps or Qase, including organizing suites, importing cases from CSV or JSON, linking them to requirements and migrating between tools without losing steps: writing cases from a spec, steps with expected results and mass edits. Pushing run results is test-management-sync.
91%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Per-vendor reference for the tcm-case-management SKILL.md. Author and manage Xray test cases (Jira issues with Test issue type) via the GraphQL + REST APIs - create tests, attach steps, link preconditions, set testType (Manual / Cucumber / Generic), associate with requirements, bulk import via JSON. Per docs.getxray.app/display/XRAYCLOUD/REST+API (Cloudflare-protected; cite by stable URL).
In Xray, tests are first-class Jira issues with issuetype: Test. Xray
augments them with test-specific data (steps, type, preconditions)
accessible via either the REST v2 API or a GraphQL endpoint.
Xray Cloud requires OAuth client credentials (different from Jira auth):
# From Xray Global Settings → API Keys, create a client
export XRAY_CLIENT_ID="..."
export XRAY_CLIENT_SECRET="..."
export JIRA_BASE="https://your-tenant.atlassian.net"import requests, os
# Exchange client credentials for a JWT
def get_token():
r = requests.post("https://xray.cloud.getxray.app/api/v2/authenticate",
json={"client_id": os.environ["XRAY_CLIENT_ID"],
"client_secret": os.environ["XRAY_CLIENT_SECRET"]})
r.raise_for_status()
return r.text.strip('"') # response is a quoted string
XRAY_BASE = "https://xray.cloud.getxray.app/api/v2"
GRAPHQL = "https://xray.cloud.getxray.app/api/v2/graphql"
def xray_headers(token):
return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}JWT expires in 24 hours; cache + refresh.
CREATE_TEST_MUTATION = """
mutation CreateTest($input: CreateTestInput!) {
createTest(input: $input) {
test { issueId jira(fields: ["key", "summary"]) }
warnings
}
}
"""
def create_manual_test(token, project_key, summary, steps,
preconditions_issue_id=None):
"""
steps: list of {"action": "...", "data": "...", "result": "..."}
"""
variables = {
"input": {
"testType": {"name": "Manual"},
"jira": {
"fields": {
"summary": summary,
"project": {"key": project_key},
"issuetype": {"name": "Test"},
}
},
"steps": steps,
"preconditionIssueIds": [preconditions_issue_id] if preconditions_issue_id else [],
}
}
r = requests.post(GRAPHQL,
json={"query": CREATE_TEST_MUTATION, "variables": variables},
headers=xray_headers(token))
r.raise_for_status()
return r.json()Per Xray docs, the three canonical types:
| testType | Steps storage | When to use |
|---|---|---|
Manual | Structured step list with action / data / result | Default; hand-executed cases |
Cucumber | Gherkin scenario text | BDD-driven tests (composes with the qa-bdd plugin) |
Generic | Single free-text definition | Automated tests where the script is the spec |
POST /api/v2/import/test/bulk accepts JSON arrays of tests:
def bulk_import(token, project_key, tests):
"""
tests: list of {"testtype": "Manual", "fields": {...}, "steps": [...]}
"""
r = requests.post(
f"{XRAY_BASE}/import/test/bulk",
json={"projectKey": project_key, "tests": tests},
headers=xray_headers(token),
)
r.raise_for_status()
return r.json() # returns job id + status poll URLBulk import returns a job ID - poll /api/v2/import/test/bulk/{jobId}/status
until complete. Expect ~50 ms per test.
# Upload .feature file via /api/v2/import/feature
with open("checkout.feature", "rb") as f:
r = requests.post(
f"{XRAY_BASE}/import/feature",
files={"file": f},
params={"projectKey": "ENG"},
headers={"Authorization": f"Bearer {token}"},
)One scenario = one Test issue; one feature = one Pre-Condition (if Background present).
Requirements in Xray are arbitrary Jira issues marked with a Requirement issue type or in a configured project. Link tests to requirements via Jira issue links:
def link_test_to_requirement(jira_base, jira_email, jira_token,
test_key, req_key, link_type="Tests"):
r = requests.post(
f"{jira_base}/rest/api/3/issueLink",
json={
"type": {"name": link_type},
"inwardIssue": {"key": req_key},
"outwardIssue": {"key": test_key},
},
auth=(jira_email, jira_token),
)
r.raise_for_status()The Tests/TestedBy link type is Xray-recommended; configure per project.
Xray stores preconditions as Jira issues with type Pre-Condition. Reuse a
precondition across tests by creating the Pre-Condition issue via the Jira
REST API v3, then attaching via preconditionIssueIds: [...] in the
create-test mutation.
| Source field | Xray field |
|---|---|
| Title | Jira summary |
| Steps | steps array |
| Preconditions text | Linked Pre-Condition issue |
| Type | testType.name (Manual / Cucumber / Generic) |
| Refs | Jira issue links to requirement issues |
GraphQL updateTest mutation (signature similar to createTest). For step
changes:
UPDATE_STEPS_MUTATION = """
mutation UpdateTestSteps($issueId: String!, $steps: [UpdateStepInput!]!) {
updateTestSteps(issueId: $issueId, steps: $steps) {
test { issueId }
warnings
}
}
"""createTest response includes test.issueId (internal Jira ID) and
test.jira (the requested Jira fields, e.g., key). Permalink:
url = f"{os.environ['JIRA_BASE']}/browse/{jira_key}"Sync Cucumber .feature files on every PR merge:
- name: Sync feature files to Xray
env:
XRAY_CLIENT_ID: ${{ secrets.XRAY_CLIENT_ID }}
XRAY_CLIENT_SECRET: ${{ secrets.XRAY_CLIENT_SECRET }}
run: |
TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
-d '{"client_id":"'$XRAY_CLIENT_ID'","client_secret":"'$XRAY_CLIENT_SECRET'"}' \
https://xray.cloud.getxray.app/api/v2/authenticate | tr -d '"')
for f in features/*.feature; do
curl -X POST -H "Authorization: Bearer $TOKEN" \
-F "file=@$f" \
"https://xray.cloud.getxray.app/api/v2/import/feature?projectKey=ENG"
done| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Storing preconditions in step 1 of every test | Duplication; preconditions evolve and tests drift | Use Pre-Condition issues + preconditionIssueIds |
| Manual tests as Generic (single text blob) | Per-step results lost | Use testType: Manual with structured steps |
| Skipping the OAuth client setup | Xray Cloud rejects Jira-auth-only requests | Always use Xray's OAuth credentials |
| Hard-coding the JWT | Expires in 24 h | Cache + refresh on 401 |
| Creating tests via Jira REST without Xray-specific fields | Tests look right in Jira but Xray's data layer (steps, type) is empty | Use GraphQL createTest or REST /import/test/bulk |
| Polling job status without backoff | Rate-limited | Exponential backoff |
| One feature = many tests imported individually | Slow | Import via /import/feature (single call) |
test-management-sync (qa-test-reporting) - result
sync, not case authoring.