Zephyr Jira Linker

A command-line tool for automatically linking test cases in Zephyr Scale to Jira issues based on branch names and issue descriptions.

Features

• Automatic Issue Detection: Extracts Jira issue keys from Git branch names
• Test Case Extraction: Parses test case IDs from Jira issue descriptions using regex patterns
• Zephyr Scale Integration: Links test cases to Jira issues via Zephyr Scale API
• Field Updates: Automatically updates Jira custom fields with test case links and code changes
• Comprehensive Logging: Detailed logging with file and console output for debugging
• Error Handling: Robust error handling with retry logic and informative error messages

Installation

From PyPI (Recommended)

pip install zephyr-jira-linker

Requirements

• Python 3.7+
• requests>=2.25.0

Configuration

The tool requires the following environment variables to be set:

Required Environment Variables

• JIRA_BASE_URL: Your Jira instance URL (e.g., https://yourcompany.atlassian.net)
• JIRA_EMAIL: Your Jira account email
• JIRA_API_TOKEN: Your Jira API token (create one at https://id.atlassian.com/manage-profile/security/api-tokens)
• ZEPHYR_SCALE_TOKEN: Your Zephyr Scale API token

Optional Environment Variables

• JIRA_PROJECT_KEY: Default project key (can be overridden by branch name parsing)

Email Alert Configuration (for --alert_new_pr and --alert_merge_pr)

• EMAIL_USER: SMTP username for authentication (required for email alerts)
• EMAIL_PASS: SMTP password for authentication (required for email alerts)
  • For Gmail: Use an App Password, not your regular password
  • Requires 2-Factor Authentication to be enabled
  • Generate a 16-character App Password and use it as EMAIL_PASS
• EMAIL_TO: Email recipient(s), comma-separated
• EMAIL_CC: Email CC recipient(s), comma-separated
• EMAIL_FROM: Email address to use as sender (default: EMAIL_USER)
• SMTP_HOST: SMTP server hostname (default: smtp.gmail.com)
• SMTP_PORT: SMTP server port (default: 587)

Gmail Setup Instructions

1. Enable 2-Factor Authentication on your Google account if not already enabled
2. Generate an App Password:
   • Go to Google App Passwords
   • Select "Mail" and "Other (Custom name)"
   • Enter a name (e.g., "Zephyr Jira Linker")
   • Click "Generate"
   • Copy the 16-character password (remove spaces)
3. Set environment variables:

   export EMAIL_USER="your-email@gmail.com"
   export EMAIL_PASS="your-16-char-app-password"
   export EMAIL_TO="recipient@example.com"
   

Usage

Command Line

Check version:

zephyr-jira-linker --version
# or
zephyr-jira-linker -v

Link test cases (from a branch name):

zephyr-jira-linker <branch_name>

Return linked test cases for a Jira issue:

zephyr-jira-linker <issue_key> --testcases

Use --testcases with an issue key (e.g. PROJECT-1234) to list all test cases currently linked to that issue in Zephyr Scale. Output is a comma-separated list of test case keys.

Get ticket field values:

# Get assignee name
zephyr-jira-linker <issue_key> --assignee

# Get reviewer name
zephyr-jira-linker <issue_key> --reviewer

# Get implementor name
zephyr-jira-linker <issue_key> --implementor

Use these flags to retrieve specific field values from a Jira ticket. Each prints the field value (or empty string if not set) and exits.

Programmatic test status summary: Use get_test_status(issue_key) from the package to get a formatted summary of all linked test cases (ID, name, status, test method, type, component, script type). Example:

from zephyr_jira_linker import get_test_status
test_status = get_test_status("PROJECT-1234")
print(test_status)

Approve and update linked test cases for a Jira issue:

zephyr-jira-linker <issue_key> --approve

Use --approve with an issue key to approve all test cases linked to that issue in Zephyr Scale. For each linked test case, the tool updates the test method (e.g. Automated depending on project) and sets the status to Approved.

Remove all testcase links from a Jira issue:

zephyr-jira-linker <issue_key> --delink

Use --delink to remove all Zephyr Scale testcase links from the given Jira issue and clear the 'Link to Test Case' custom field. Exits with code 0 on success, 1 on failure.

Programmatic test case and label APIs: Use the package to update a single test case, or get/update labels by test case key:

from zephyr_jira_linker import update_test_case, get_testcase_labels, update_testcase_labels, get_testcase_info

# Update a test case (status, test type, labels). testcase_info is from get_testcase_info(key) or similar.
update_test_case(testcase_info, status="Approved", test_type="Regression", labels=["UI"])

# Get current labels for a test case (e.g. PRO-T10132)
labels = get_testcase_labels("PRO-T10132")

# Replace test case labels with a new list
update_testcase_labels("PRO-T10132", ["UI", "SMOKE"])

• update_test_case(testcase_info, status="Approved", test_type="Regression", labels=[]) — Updates a test case's status, test type, and optionally labels. Pass a test case dict (e.g. from get_testcase_info(key)).
• get_testcase_labels(testcase_id) — Returns the list of label strings for the given test case key; returns [] if none or on error.
• update_testcase_labels(testcase_id, labels) — Replaces the test case's labels with the given list; returns True on success, False otherwise.

Examples

# Check the installed version
zephyr-jira-linker --version

# Link test cases for a feature branch
zephyr-jira-linker feature/PROJ-123-add-user-authentication

# Link test cases for a bug fix branch
zephyr-jira-linker bugfix/PROJ-456-fix-login-issue

# Link test cases for a hotfix branch
zephyr-jira-linker hotfix/PROJ-789-critical-security-patch

# List test cases linked to a specific issue
zephyr-jira-linker PROJECT-1234 --testcases

# Approve and update all test cases linked to an issue
zephyr-jira-linker PROJECT-1234 --approve

# Remove all testcase links from an issue
zephyr-jira-linker PROJECT-1234 --delink

# Get reviewer name for an issue
zephyr-jira-linker PROJECT-1234 --reviewer

# Get implementor name for an issue
zephyr-jira-linker PROJECT-1234 --implementor

# Get assignee name for an issue
zephyr-jira-linker PROJECT-1234 --assignee

# Send mail for new pr
zephyr-jira-linker PROJECT-1234 --alert_new_pr

# Send mail for merge pr
zephyr-jira-linker PROJECT-1234 --alert_merge_pr

# Programmatic: update one test case; get or set labels
from zephyr_jira_linker import update_test_case, get_testcase_labels, update_testcase_labels, get_testcase_info

tc = get_testcase_info("PRO-T10132")
update_test_case(tc, status="Approved", test_type="Regression", labels=["UI"])

labels = get_testcase_labels("PRO-T10132")
update_testcase_labels("PRO-T10132", ["UI", "SMOKE"])

What the Tool Does

1. Extracts Issue Key: Parses the Jira issue key from the branch name (e.g., PROJ-123 from feature/PROJ-123-add-user-authentication)

2. Validates Issue: Verifies the issue exists and retrieves its details from Jira

3. Extracts Test Cases: Searches the issue description for test case IDs using regex pattern \b([A-Z]+-T\d+)\b

4. Links Test Cases: Uses Zephyr Scale API to link identified test cases to the Jira issue

5. Updates Fields:

   • Updates the 'Link to Test Case' custom field with the first linked test case URL
   • Updates the 'Code Changes' field with implementation details

6. Verification: Validates that all links were created successfully and fields were updated

Branch Name Format

The tool expects branch names to contain Jira issue keys in the format PROJECT-NUMBER. Examples:

• feature/PROJ-123-add-new-feature
• bugfix/PROJ-456-fix-bug
• hotfix/PROJ-789-security-patch
• PROJ-100-maintenance-update

Logging

The tool creates detailed logs in the logs/ directory:

• File Logging: logs/zephyr_test_status.log with rotating files (10MB max, 5 backups)
• Console Logging: Real-time output to stdout/stderr
• Log Levels: INFO, WARNING, ERROR with timestamps

Custom Field Configuration

The tool uses specific Jira custom field IDs. Update these in the source code if your instance uses different field IDs:

CUSTOMFIELD_TESTCASE_LINK = "customfield_13292"  # Link to Test Case field
CUSTOMFIELD_CODE_CHANGES = "customfield_13242"   # Code Changes field
CUSTOMFIELD_IMPLEMENTOR = "customfield_10810"    # Implementor field
CUSTOMFIELD_PULL_REQUEST = "customfield_12500"   # Pull Request field
CUSTOMFIELD_STORY_POINTS = "customfield_10004"   # Story Points field
CUSTOMFIELD_SPRINT = "customfield_10007"         # Sprint field

API Rate Limiting

The tool includes built-in delays and error handling for API rate limits. It will automatically retry failed requests with exponential backoff.

Error Handling

• Network Errors: Automatic retry with backoff for temporary network issues
• Authentication Errors: Clear error messages for invalid credentials
• Permission Errors: Detailed messages for insufficient permissions
• Invalid Issue Keys: Validation of issue key format and existence
• Test Case Not Found: Graceful handling of missing test cases

License

MIT License - see LICENSE.

References

• Zephyr Scale API Documentation
• Jira REST API Documentation