Metadata-Version: 1.1
Name: pytest-github
Version: 0.0.9
Summary: Plugin for py.test that associates tests with github issues using a marker.
Home-page: http://github.com/jlaska/pytest-github
Author: James Laska
Author-email: <jlaska@ansible.com>
License: MIT
Description: pytest-github
        =============
        
        |Build Status| |Coverage Status| |Requirements Status| |Version|
        |Downloads| |License| |Supported Python Versions|
        
        Plugin for py.test that integrates with github using markers.
        Integration allows tests to xfail (or skip) based on the status of
        linked github issues.
        
        Installation
        ------------
        
        Install the plugin using ``pip``
        
        .. code:: bash
        
            pip install pytest-github
        
        Usage
        -----
        
        1. Once installed, the following ``py.test`` command-line parameters are
           available.
        
        .. code:: bash
        
            py.test \
                [--github-cfg=GITHUB_CFG] \
                [--github-username=GITHUB_USERNAME] \
                [--github-token=GITHUB_TOKEN] \
                [--github-completed=GITHUB_COMPLETED] \
                [--github-summary]
        
        2. Next, create a configure file called ``github.yml`` that contains
           your GitHub username and `personal api
           token <https://github.com/blog/1509-personal-api-tokens>`__. A sample
           file is included below.
        
        .. code:: yaml
        
            github:
                username: j.doe
                token: XXXXXXXXXXXXX
        
        Marker
        ~~~~~~
        
        The following ``py.test`` marker is available:
        
        .. code:: python
        
            @pytest.mark.github(*args): GitHub issue integration
        
        The marker can be used to influence the outcome of tests. See the
        examples below for guidance.
        
        Example: xfail
        ~~~~~~~~~~~~~~
        
        Often, when a test fails, one might file a GitHub issue to track the
        resolution of the problem. Alternatively, you could use the built-in
        ``xfail`` marker. This is where ``pytest-github`` can be of use. To
        avoid having to review known failures with each test run, and to avoid
        always using ``xfail``, consider the ``github`` marker to dynamically
        influence the test outcome based on the state of the GitHub issue.
        
        The following example demonstrates using the ``github`` marker to
        influence the outcome of a known failing test.
        
        .. code:: python
        
            @pytest.mark.github('https://github.com/some/open/issues/1')
            def test_will_xfail():
                assert False
        
        Running this test with ``py.test`` will produce the following output:
        
        .. code:: bash
        
            test.py::test_will_xfail xfail
        
        Example: Anticipating specific exceptions with the 'raises' keyword
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        To avoid masking additional failures that might be uncovered by a test
        while a github issue is being resolved, you can restrict expected
        failures to specific exceptions using the ``raises`` keyword argument:
        
        .. code:: python
        
            @pytest.mark.github('https://github.com/some/open/issues/1', raises=ZeroDivisionError)
            def test_will_xfail():
                foo = 1/0
        
        
            @pytest.mark.github('https://github.com/some/open/issues/1', raises=ValueError)
            def test_will_fail():
                # This test has been marked with an open issue but it will still fail
                # because the exception raised is different from the one indicated by
                # the 'raises' keyword.
                foo = 1/0
        
        Running this test with ``py.test`` will produce the following output:
        
        .. code:: bash
        
            collected 2 items
            collected 1 github issues
        
            test.py::test_will_xfail xfail
            test.py::test_will_fail FAILED
        
        Example: XPASS
        ~~~~~~~~~~~~~~
        
        The following example demonstrates a test that succeeds, despite being
        associated with an *open* GitHub issue.
        
        .. code:: python
        
            @pytest.mark.github('https://github.com/some/open/issues/1')
            def test_will_xpass():
                assert True
        
        In this example, the ``XPASS`` outcome (a.k.a. unexpected pass) is used.
        
        ::
        
            test.py::test_will_xpass XPASS
        
        Example: PASSED
        ~~~~~~~~~~~~~~~
        
        The following example demonstrates a test that succeeds, while it is
        associated with a *closed* GitHub issue. When a test associated with a
        GitHub
        
        .. code:: python
        
            @pytest.mark.github('https://github.com/some/closed/issues/2')
            def test_will_pass():
                assert True
        
        In this example, the ``PASSED`` outcome is used.
        
        ::
        
            test.py::test_will_pass PASSED
        
        Example: FAILED
        ~~~~~~~~~~~~~~~
        
        The following example demonstrates a test that fails, while it is
        associated with a *closed* GitHub issue.
        
        .. code:: python
        
            @pytest.mark.github('https://github.com/some/closed/issues/2')
            def test_will_fail():
                assert False
        
        In this example, the ``FAILED`` outcome is used.
        
        ::
        
            test.py::test_will_fail FAILED
        
        Example: SKIPPED
        ~~~~~~~~~~~~~~~~
        
        The following example demonstrates a test that fails, while it is
        associated with an *open* GitHub issue.
        
        .. code:: python
        
            @pytest.mark.github('https://github.com/some/open/issues/1', skip=True)
            def test_will_skip():
                assert False
        
        In this example, the ``SKIPPED`` outcome is used.
        
        ::
        
            test.py::test_will_skip SKIPPED
        
        .. |Build Status| image:: https://img.shields.io/travis/jlaska/pytest-github.svg
           :target: https://travis-ci.org/jlaska/pytest-github
        .. |Coverage Status| image:: https://img.shields.io/coveralls/jlaska/pytest-github.svg
           :target: https://coveralls.io/r/jlaska/pytest-github
        .. |Requirements Status| image:: https://requires.io/github/jlaska/pytest-github/requirements.svg?branch=master
           :target: https://requires.io/github/jlaska/pytest-github/requirements/?branch=master
        .. |Version| image:: https://img.shields.io/pypi/v/pytest-github.svg
           :target: https://pypi.python.org/pypi/pytest-github/
        .. |Downloads| image:: https://img.shields.io/pypi/dm/pytest-github.svg
           :target: https://pypi.python.org/pypi/pytest-github/
        .. |License| image:: https://img.shields.io/pypi/l/pytest-github.svg
           :target: https://pypi.python.org/pypi/pytest-github/
        .. |Supported Python Versions| image:: https://img.shields.io/pypi/pyversions/pytest-github.svg
           :target: https://pypi.python.org/pypi/pytest-github/
        
Keywords: py.test pytest testing github issues
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
