Managing Xray

Xray Test Management Skill

Manage and analyze Xray test plans, executions, and coverage within Jira.

Core Helper Functions

#!/bin/bash

# Xray Cloud API helper
xray_api() {
    local method="${1:-GET}"
    local endpoint="$2"
    local data="${3:-}"

    # Authenticate and get token
    if [ -z "$XRAY_TOKEN" ]; then
        XRAY_TOKEN=$(curl -s -X POST \
            -H "Content-Type: application/json" \
            "https://xray.cloud.getxray.app/api/v2/authenticate" \
            -d "{\"client_id\":\"${XRAY_CLIENT_ID}\",\"client_secret\":\"${XRAY_CLIENT_SECRET}\"}" | tr -d '"')
    fi

    if [ -n "$data" ]; then
        curl -s -X "$method" \
            -H "Authorization: Bearer ${XRAY_TOKEN}" \
            -H "Content-Type: application/json" \
            "https://xray.cloud.getxray.app/api/v2/${endpoint}" \
            -d "$data"
    else
        curl -s -X "$method" \
            -H "Authorization: Bearer ${XRAY_TOKEN}" \
            "https://xray.cloud.getxray.app/api/v2/${endpoint}"
    fi
}

# Jira API helper for Xray issue queries
jira_api() {
    curl -s -X GET \
        -u "${JIRA_USER}:${JIRA_API_TOKEN}" \
        -H "Content-Type: application/json" \
        "${JIRA_URL}/rest/api/3/${1}"
}

MANDATORY: Discovery-First Pattern

Always discover test plans and test sets before querying specifics.

Phase 1: Discovery

#!/bin/bash

echo "=== Xray Test Plans ==="
PROJECT_KEY="${1:?Project key required}"
jira_api "search?jql=project=${PROJECT_KEY}+AND+issuetype='Test Plan'&maxResults=10&fields=summary,status" | jq -r '
    .issues[] | "\(.key)\t\(.fields.summary)\tstatus=\(.fields.status.name)"
' | column -t

echo ""
echo "=== Test Executions ==="
jira_api "search?jql=project=${PROJECT_KEY}+AND+issuetype='Test Execution'&maxResults=10&fields=summary,status" | jq -r '
    .issues[] | "\(.key)\t\(.fields.summary)\tstatus=\(.fields.status.name)"
' | column -t

echo ""
echo "=== Test Cases ==="
jira_api "search?jql=project=${PROJECT_KEY}+AND+issuetype='Test'&maxResults=15&fields=summary,status,labels" | jq -r '
    .issues[] | "\(.key)\t\(.fields.summary)\tstatus=\(.fields.status.name)\tlabels=\(.fields.labels | join(","))"
' | column -t

echo ""
echo "=== Test Sets ==="
jira_api "search?jql=project=${PROJECT_KEY}+AND+issuetype='Test Set'&maxResults=10&fields=summary" | jq -r '
    .issues[] | "\(.key)\t\(.fields.summary)"
' | column -t

Phase 2: Analysis

#!/bin/bash

PROJECT_KEY="${1:?Project key required}"

echo "=== Test Execution Results ==="
EXEC_KEY="${2:-}"
if [ -n "$EXEC_KEY" ]; then
    xray_api GET "testexecutions/${EXEC_KEY}/tests" | jq -r '
        .[:20][] | "\(.key)\t\(.summary // "unnamed")\tstatus=\(.status // "TODO")"
    ' | column -t

    echo ""
    echo "=== Execution Summary ==="
    xray_api GET "testexecutions/${EXEC_KEY}/tests" | jq '{
        total: length,
        by_status: (group_by(.status) | map({status: .[0].status, count: length}))
    }'
fi

echo ""
echo "=== Requirement Coverage ==="
jira_api "search?jql=project=${PROJECT_KEY}+AND+issuetype+in+(Story,Bug)&maxResults=10&fields=summary,issuelinks" | jq -r '
    .issues[] | {
        key: .key,
        summary: .fields.summary,
        linked_tests: [.fields.issuelinks[] | select(.type.name == "Test") | .outwardIssue.key // .inwardIssue.key] | length
    } | "\(.key)\t\(.summary | .[0:40])\ttests=\(.linked_tests)"
' | column -t | head -15

echo ""
echo "=== Cucumber Feature Files ==="
xray_api GET "export/cucumber?keys=${PROJECT_KEY}" 2>/dev/null | head -20 || echo "No Cucumber export configured"

Output Rules

• TOKEN EFFICIENCY: Target 50 lines per output
• Use JQL queries for efficient issue filtering
• Summarize coverage metrics, not full test step details

Anti-Hallucination Rules

• NEVER guess issue keys — always discover via JQL search
• NEVER fabricate test results — query actual Xray data
• NEVER assume Xray Cloud vs Server — check API endpoint compatibility

Safety Rules

• NEVER create or delete test executions without explicit user confirmation
• NEVER modify test status without user approval
• NEVER import results without user consent

Output Format

Present results as a structured report:

Managing Xray Report
════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations