Intro
=====
A `pytest <http://pytest.org/latest/>`__ plugin for JIRA integration.
This plugin links tests with JIRA tickets. The plugin behaves similar to
the `pytest-bugzilla <https://pypi.python.org/pypi/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 <https://github.com/rhevm-qe-automation/pytest_jira/issues>`__.
Test results
------------
- If the test **unresolved** ...
- and the *run=False*, the test is **skipped**
- 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).
Interpretation of **xpassed** result depends on the py.test ini-file **xfail_strict** value,
i.e. with *xfail_strict=true* **xpassed** results will fail the test suite.
More information about strict xfail available on the py.test `doc <https://docs.pytest.org/en/latest/skipping.html#strict-parameter>`__
- If the test **resolved** ...
- the test is executed and based on it
the result is **passed** or **failed**
- If the **skipif** parameter is provided ...
- with value *False* or *callable returning False-like value* jira marker line is **ignored**
**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 parameters ``run`` and ``skipif``.
If ``run`` is false and issue is unresolved, the test will be skipped.
If ``skipif`` is is false jira marker line will be ignored.
.. code:: python
@pytest.mark.jira("ORG-1382", run=False)
def test_skip(): # will be skipped if unresolved
assert False
@pytest.mark.jira("ORG-1382")
def test_xfail(): # will run and xfail if unresolved
assert False
@pytest.mark.jira("ORG-1382", skipif=False)
def test_fail(): # will run and fail as jira marker is ignored
assert False
Using lambda value for skipif
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use lambda value for ``skipif`` parameter. Lambda function must take
issue JSON as input value and return boolean-like value. If any JIRA ID
gets False-like value marker for that issue will be ignored.
.. code:: python
@pytest.mark.jira("ORG-1382", skipif=lambda i: 'my component' in i['components'])
def test_fail(): # Test will run if 'my component' is not present in Jira issue's components
assert False
@pytest.mark.jira("ORG-1382", "ORG-1412", skipif=lambda i: 'to do' == i['status'])
def test_fail(): # Test will run if either of JIRA issue's status differs from 'to do'
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``.
.. code:: python
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**.
If you specify fixed resolutions closed issues will be **unresolved** if they do not also have a **resolved** resolution.
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``.
.. code:: python
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!")
continue
assert animal in NICE_ANIMALS
Requires
========
- pytest >= 2.2.3
- requests >= 2.13.0
- six
- retry2>=0.9.5
- marshmallow>=3.2.0
Installation
============
``pip install pytest_jira``
Usage
=====
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
* tests\_test\_dir/jira.cfg
The configuration file is loaded in that order mentioned 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 template, and update it according
to your needs.
.. code:: ini
[DEFAULT]
url = https://jira.atlassian.com
username = USERNAME (or blank for no authentication)
password = PASSWORD (or blank for no authentication)
token = TOKEN (either use token or username and password)
# 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)
# resolved_resolutions = comma separated list of resolutions (done, fixed)
# run_test_case = True (default value for 'run' parameter)
# connection_error_strategy [strict|skip|ignore] Choose how to handle connection errors
# return_jira_metadata = False (return Jira issue with metadata instead of boolean result)
Alternatively, you can set the url, password, username and token fields using relevant environment variables:
.. code:: sh
export PYTEST_JIRA_URL="https://..."
export PYTEST_JIRA_PASSWORD="FOO"
export PYTEST_JIRA_USERNAME="BAR"
export PYTEST_JIRA_TOKEN="TOKEN"
Configuration options can be overridden with command line options as well.
For all available command line options run following command.
.. code:: sh
py.test --help
2. Mark your tests with jira marker and issue id.
``@pytest.mark.jira('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``
Tests
=====
In order to execute tests run
.. code:: sh
$ tox
Raw data
{
"_id": null,
"home_page": "http://github.com/rhevm-qe-automation/pytest_jira",
"name": "pytest-jira",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "pytest, jira, plugin",
"author": "James Laska",
"author_email": "james.laska@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f7/4b/61ddccd94c0bea0ca5a710031ca6830059af4ab8f935219433342b8d52d4/pytest-jira-0.3.21.zip",
"platform": null,
"description": "Intro\n=====\n\nA `pytest <http://pytest.org/latest/>`__ plugin for JIRA integration.\n\nThis plugin links tests with JIRA tickets. The plugin behaves similar to\nthe `pytest-bugzilla <https://pypi.python.org/pypi/pytest-bugzilla>`__\nplugin.\n\nThe plugin does not close JIRA tickets, or create them. It just allows\nyou to link tests to existing tickets.\n\nPlease feel free to contribute by forking and submitting pull requests\nor by submitting feature requests or issues to\n`issues <https://github.com/rhevm-qe-automation/pytest_jira/issues>`__.\n\nTest results\n------------\n- If the test **unresolved** ...\n\n - and the *run=False*, the test is **skipped**\n\n - and the *run=True* or not set, the test is executed and based on it\n the result is **xpassed** (e.g. unexpected pass) or **xfailed** (e.g. expected fail).\n Interpretation of **xpassed** result depends on the py.test ini-file **xfail_strict** value,\n i.e. with *xfail_strict=true* **xpassed** results will fail the test suite.\n More information about strict xfail available on the py.test `doc <https://docs.pytest.org/en/latest/skipping.html#strict-parameter>`__\n\n- If the test **resolved** ...\n\n - the test is executed and based on it\n the result is **passed** or **failed**\n\n- If the **skipif** parameter is provided ...\n\n - with value *False* or *callable returning False-like value* jira marker line is **ignored**\n\n\n**NOTE:** You can set default value for ``run`` parameter globally in config\nfile (option ``run_test_case``) or from CLI\n``--jira-do-not-run-test-case``. Default value is ``run=True``.\n\nMarking tests\n-------------\nYou can specify jira issue ID in docstring or in pytest.mark.jira decorator.\n\nBy default the regular expression pattern for matching jira issue ID is ``[A-Z]+-[0-9]+``,\nit can be changed by ``--jira-issue-regex=REGEX`` or in a config file by\n``jira_regex=REGEX``.\n\nIt's also possible to change behavior if issue ID was not found\nby setting ``--jira-marker-strategy=STRATEGY`` or in config file\nas ``marker_strategy=STRATEGY``.\n\nStrategies for dealing with issue IDs that were not found:\n\n- **open** - issue is considered as open (default)\n- **strict** - raise an exception\n- **ignore** - issue id is ignored\n- **warn** - write error message and ignore\n\nIssue ID in decorator\n~~~~~~~~~~~~~~~~~~~~~\nIf you use decorator you can specify optional parameters ``run`` and ``skipif``.\nIf ``run`` is false and issue is unresolved, the test will be skipped.\nIf ``skipif`` is is false jira marker line will be ignored.\n\n.. code:: python\n\n @pytest.mark.jira(\"ORG-1382\", run=False)\n def test_skip(): # will be skipped if unresolved\n assert False\n\n @pytest.mark.jira(\"ORG-1382\")\n def test_xfail(): # will run and xfail if unresolved\n assert False\n\n @pytest.mark.jira(\"ORG-1382\", skipif=False)\n def test_fail(): # will run and fail as jira marker is ignored\n assert False\n\nUsing lambda value for skipif\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nYou can use lambda value for ``skipif`` parameter. Lambda function must take\nissue JSON as input value and return boolean-like value. If any JIRA ID\ngets False-like value marker for that issue will be ignored.\n\n.. code:: python\n\n @pytest.mark.jira(\"ORG-1382\", skipif=lambda i: 'my component' in i['components'])\n def test_fail(): # Test will run if 'my component' is not present in Jira issue's components\n assert False\n\n @pytest.mark.jira(\"ORG-1382\", \"ORG-1412\", skipif=lambda i: 'to do' == i['status'])\n def test_fail(): # Test will run if either of JIRA issue's status differs from 'to do'\n assert False\n\n\nIssue ID in docstring\n~~~~~~~~~~~~~~~~~~~~~\n\nYou can disable searching for issue ID in doc string by using\n``--jira-disable-docs-search`` parameter or by ``docs_search=False``\nin ``jira.cfg``.\n\n.. code:: python\n\n def test_xpass(): # will run and xpass if unresolved\n \"\"\"issue: ORG-1382\"\"\"\n assert True\n\nStatus evaluation\n-----------------\n\nIssues are considered as **resolved** if their status matches\n``resolved_statuses``. By default it is ``Resolved`` or ``Closed``.\n\nYou can set your own custom resolved statuses on command line\n``--jira-resolved-statuses``, or in config file.\n\nIf you specify components (in command line or jira.cfg), open issues will be considered\n**unresolved** only if they are also open for at least one used component.\n\nIf you specify version, open issues will be **unresolved** only if they also affects your version.\nEven when the issue is closed, but your version was affected and it was not fixed for your version,\nthe issue will be considered **unresolved**.\n\nIf you specify fixed resolutions closed issues will be **unresolved** if they do not also have a **resolved** resolution.\n\nFixture usage\n-------------\n\nBesides a test marker, you can also use the added ``jira_issue`` fixture. This enables examining issue status mid test\nand not just at the beginning of a test. The fixture return a boolean representing the state of the issue.\nIf the issue isn't found, or the jira plugin isn't loaded, it returns ``None``.\n\n.. code:: python\n\n NICE_ANIMALS = [\"bird\", \"cat\", \"dog\"]\n\n def test_stuff(jira_issue):\n animals = [\"dog\", \"cat\"]\n for animal in animals:\n if animal == \"dog\" and jira_issue(\"ORG-1382\") is True:\n print(\"Issue is still open, cannot check for dogs!\")\n continue\n assert animal in NICE_ANIMALS\n\nRequires\n========\n\n- pytest >= 2.2.3\n- requests >= 2.13.0\n- six\n- retry2>=0.9.5\n- marshmallow>=3.2.0\n\nInstallation\n============\n\n``pip install pytest_jira``\n\nUsage\n=====\n\n\n1. Create a ``jira.cfg`` and put it at least in one of following places.\n\n * /etc/jira.cfg\n * ~/jira.cfg\n * tests\\_root\\_dir/jira.cfg\n * tests\\_test\\_dir/jira.cfg\n\n The configuration file is loaded in that order mentioned above.\n That means that first options from global configuration are loaded,\n and might be overwritten by options from user's home directory and\n finally these might be overwritten by options from test's root directory.\n\n See example bellow, you can use it as template, and update it according\n to your needs.\n\n .. code:: ini\n\n [DEFAULT]\n url = https://jira.atlassian.com\n username = USERNAME (or blank for no authentication)\n password = PASSWORD (or blank for no authentication)\n token = TOKEN (either use token or username and password)\n # ssl_verification = True/False\n # version = foo-1.0\n # components = com1,second component,com3\n # strategy = [open|strict|warn|ignore] (dealing with not found issues)\n # docs_search = False (disable searching for issue id in docs)\n # issue_regex = REGEX (replace default `[A-Z]+-[0-9]+` regular expression)\n # resolved_statuses = comma separated list of statuses (closed, resolved)\n # resolved_resolutions = comma separated list of resolutions (done, fixed)\n # run_test_case = True (default value for 'run' parameter)\n # connection_error_strategy [strict|skip|ignore] Choose how to handle connection errors\n # return_jira_metadata = False (return Jira issue with metadata instead of boolean result)\n\n Alternatively, you can set the url, password, username and token fields using relevant environment variables:\n\n .. code:: sh\n\n export PYTEST_JIRA_URL=\"https://...\"\n export PYTEST_JIRA_PASSWORD=\"FOO\"\n export PYTEST_JIRA_USERNAME=\"BAR\"\n export PYTEST_JIRA_TOKEN=\"TOKEN\"\n\n Configuration options can be overridden with command line options as well.\n For all available command line options run following command.\n\n .. code:: sh\n\n py.test --help\n\n2. Mark your tests with jira marker and issue id.\n\n ``@pytest.mark.jira('issue_id')``\n\n You can put Jira ID into doc string of test case as well.\n\n3. Run py.test with jira option to enable the plugin.\n\n ``py.test --jira``\n\nTests\n=====\n\nIn order to execute tests run\n\n.. code:: sh\n\n $ tox\n\n",
"bugtrack_url": null,
"license": "GPLv2",
"summary": "py.test JIRA integration plugin, using markers",
"version": "0.3.21",
"project_urls": {
"Homepage": "http://github.com/rhevm-qe-automation/pytest_jira"
},
"split_keywords": [
"pytest",
" jira",
" plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f74b61ddccd94c0bea0ca5a710031ca6830059af4ab8f935219433342b8d52d4",
"md5": "e23dac4e0e0428911c89231c7cf1fb7f",
"sha256": "ca0dd9d13a915849507bc00957c8eae6905f9774434f1e4827e7bc6ae937f29e"
},
"downloads": -1,
"filename": "pytest-jira-0.3.21.zip",
"has_sig": false,
"md5_digest": "e23dac4e0e0428911c89231c7cf1fb7f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 34203,
"upload_time": "2024-04-30T10:45:51",
"upload_time_iso_8601": "2024-04-30T10:45:51.799577Z",
"url": "https://files.pythonhosted.org/packages/f7/4b/61ddccd94c0bea0ca5a710031ca6830059af4ab8f935219433342b8d52d4/pytest-jira-0.3.21.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-30 10:45:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rhevm-qe-automation",
"github_project": "pytest_jira",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "pytest-jira"
}
JSON
