Skip to main content
Help us improve Python packaging – donate today!

py.test JIRA integration plugin, using markers

Project Description

Build Status Code Health Code Coverage


A pytest plugin for JIRA integration.

This plugin links tests with JIRA tickets. The plugin behaves similar to the pytest-bugzilla plugin.

The plugin does not close JIRA tickets, or create them. It just allows you to link tests to existing tickets.

Please feel free to contribute by forking and submitting pull requests or by submitting feature requests or issues to issues.

Test results

  • If the test unresolved
    • and the run=False, the test is skiped
    • and the run=True or not set, the test is executed and based on it the result is xpassed (e.g. unexpected pass) or xfailed (e.g. expected fail)
  • If the test resolved
    • the test is executed and based on it the result is passed or failed

NOTE: You can set default value for run parameter globally in config file (option run_test_case) or from CLI --jira-do-not-run-test-case. Default value is run=True.

Marking tests

You can specify jira issue ID in docstring or in pytest.mark.jira decorator.

By default the regular expression pattern for matching jira issue ID is [A-Z]+-[0-9]+, it can be changed by --jira-issue-regex=REGEX or in a config file by jira_regex=REGEX.

It’s also possible to change behavior if issue ID was not found by setting --jira-marker-strategy=STRATEGY or in config file as marker_strategy=STRATEGY.

Strategies for dealing with issue IDs that were not found:

  • open - issue is considered as open (default)
  • strict - raise an exception
  • ignore - issue id is ignored
  • warn - write error message and ignore

Issue ID in decorator

If you use decorator you can specify optional parameter run. If it’s false and issue is unresolved, the test will be skipped.

@pytest.mark.jira("ORG-1382", run=False)
def test_skip(): # will be skipped if unresolved
    assert False

def test_xfail(): # will run and xfail if unresolved
    assert False

Issue ID in docstring

You can disable searching for issue ID in doc string by using --jira-disable-docs-search parameter or by docs_search=False in jira.cfg.

def test_xpass(): # will run and xpass if unresolved
"""issue: ORG-1382"""
    assert True

Status evaluation

Issues are considered as resolved if their status matches resolved_statuses. By default it is Resolved or Closed.

You can set your own custom resolved statuses on command line --jira-resolved-statuses, or in config file.

If you specify components (in command line or jira.cfg), open issues will be considered unresolved only if they are also open for at least one used component.

If you specify version, open issues will be unresolved only if they also affects your version. Even when the issue is closed, but your version was affected and it was not fixed for your version, the issue will be considered unresolved.

Fixture usage

Besides a test marker, you can also use the added jira_issue fixture. This enables examining issue status mid test and not just at the beginning of a test. The fixture return a boolean representing the state of the issue. If the issue isn’t found, or the jira plugin isn’t loaded, it returns None.

NICE_ANIMALS = ["bird", "cat", "dog"]

def test_stuff(jira_issue):
    animals = ["dog", "cat"]
    for animal in animals:
        if animal == "dog" and jira_issue("ORG-1382") is True:
            print("Issue is still open, cannot check for dogs!")
        assert animal in NICE_ANIMALS


  • pytest >= 2.2.3
  • requests >= 2.13.0
  • six


pip install pytest_jira


  1. Create a jira.cfg and put it at least in one of following places.

    • /etc/jira.cfg
    • ~/jira.cfg
    • tests_root_dir/jira.cfg

    The configuration file is loaded in that order meantioned above. That means that first options from global configuration are loaded, and might be overwritten by options from user’s home directory and finally these might be overwritten by options from test’s root directory.

    See example bellow, you can use it as tempate, and update it according to your needs.

    url =
    username = USERNAME (or blank for no authentication
    password = PASSWORD (or blank for no authentication)
    # ssl_verification = True/False
    # version = foo-1.0
    # components = com1,second component,com3
    # strategy = [open|strict|warn|ignore] (dealing with not found issues)
    # docs_search = False (disable searching for issue id in docs)
    # issue_regex = REGEX (replace default `[A-Z]+-[0-9]+` regular expression)
    # resolved_statuses = comma separated list of statuses (closed, resolved)
    # run_test_case = True (default value for 'run' parameter)

    Configuration options can be overridden with command line options as well. For all available command line options run following command.

    py.test --help
  2. Mark your tests with jira marker and issue id.


    You can put Jira ID into doc string of test case as well.

  3. Run py.test with jira option to enable the plugin.

    py.test --jira


In order to execute tests run

$ tox

Release history Release notifications

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date (29.2 kB) Copy SHA256 hash SHA256 Source None Oct 5, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page