zephyr-jira-linker 0.1.9

A command-line tool for linking test cases in Zephyr Scale to Jira issues

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

From Source

git clone https://github.com/pandiyarajk/zephyr-jira-linker.git
cd zephyr-jira-linker
pip install .

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)

Usage

Command Line

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.

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.

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

# 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

# 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

Development

Setting up Development Environment

git clone https://github.com/pandiyarajk/zephyr-jira-linker.git
cd zephyr-jira-linker
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Running Tests

# Run the tool directly
python -m zephyr_jira_linker.main <branch_name>

# Or use the installed command
zephyr-jira-linker <branch_name>

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes and add tests
4. Commit your changes: git commit -am 'Add some feature'
5. Push to the branch: git push origin feature/your-feature-name
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGE_LOG.md for version history and updates.

Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Email: [e-mail]

Related Projects

• Zephyr Scale API Documentation
• Jira REST API Documentation