.. image:: https://img.shields.io/pypi/v/pytest-runner.svg
:target: `PyPI link`_
.. image:: https://img.shields.io/pypi/pyversions/pytest-runner.svg
:target: `PyPI link`_
.. _PyPI link: https://pypi.org/project/pytest-runner
.. image:: https://github.com/pytest-dev/pytest-runner/workflows/tests/badge.svg
:target: https://github.com/pytest-dev/pytest-runner/actions?query=workflow%3A%22tests%22
:alt: tests
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Code style: Black
.. .. image:: https://readthedocs.org/projects/skeleton/badge/?version=latest
.. :target: https://skeleton.readthedocs.io/en/latest/?badge=latest
.. image:: https://img.shields.io/badge/skeleton-2022-informational
:target: https://blog.jaraco.com/skeleton
.. image:: https://tidelift.com/badges/package/pypi/pytest-runner
:target: https://tidelift.com/subscription/pkg/pypi-pytest-runner?utm_source=pypi-pytest-runner&utm_medium=readme
Setup scripts can use pytest-runner to add setup.py test support for pytest
runner.
Deprecation Notice
==================
pytest-runner depends on deprecated features of setuptools and relies on features that break security
mechanisms in pip. For example 'setup_requires' and 'tests_require' bypass ``pip --require-hashes``.
See also `pypa/setuptools#1684 <https://github.com/pypa/setuptools/issues/1684>`_.
It is recommended that you:
- Remove ``'pytest-runner'`` from your ``setup_requires``, preferably removing the ``setup_requires`` option.
- Remove ``'pytest'`` and any other testing requirements from ``tests_require``, preferably removing the ``tests_requires`` option.
- Select a tool to bootstrap and then run tests such as tox.
Usage
=====
- Add 'pytest-runner' to your 'setup_requires'. Pin to '>=2.0,<3dev' (or
similar) to avoid pulling in incompatible versions.
- Include 'pytest' and any other testing requirements to 'tests_require'.
- Invoke tests with ``setup.py pytest``.
- Pass ``--index-url`` to have test requirements downloaded from an alternate
index URL (unnecessary if specified for easy_install in setup.cfg).
- Pass additional py.test command-line options using ``--addopts``.
- Set permanent options for the ``python setup.py pytest`` command (like ``index-url``)
in the ``[pytest]`` section of ``setup.cfg``.
- Set permanent options for the ``py.test`` run (like ``addopts`` or ``pep8ignore``) in the ``[pytest]``
section of ``pytest.ini`` or ``tox.ini`` or put them in the ``[tool:pytest]``
section of ``setup.cfg``. See `pytest issue 567
<https://github.com/pytest-dev/pytest/issues/567>`_.
- Optionally, set ``test=pytest`` in the ``[aliases]`` section of ``setup.cfg``
to cause ``python setup.py test`` to invoke pytest.
Example
=======
The most simple usage looks like this in setup.py::
setup(
setup_requires=[
'pytest-runner',
],
tests_require=[
'pytest',
],
)
Additional dependencies require to run the tests (e.g. mock or pytest
plugins) may be added to tests_require and will be downloaded and
required by the session before invoking pytest.
Follow `this search on github
<https://github.com/search?utf8=%E2%9C%93&q=filename%3Asetup.py+pytest-runner&type=Code&ref=searchresults>`_
for examples of real-world usage.
Standalone Example
==================
This technique is deprecated - if you have standalone scripts
you wish to invoke with dependencies, `use pip-run
<https://pypi.org/project/pip-run>`_.
Although ``pytest-runner`` is typically used to add pytest test
runner support to maintained packages, ``pytest-runner`` may
also be used to create standalone tests. Consider `this example
failure <https://gist.github.com/jaraco/d979a558bc0bf2194c23>`_,
reported in `jsonpickle #117
<https://github.com/jsonpickle/jsonpickle/issues/117>`_
or `this MongoDB test
<https://gist.github.com/jaraco/0b9e482f5c0a1300dc9a>`_
demonstrating a technique that works even when dependencies
are required in the test.
Either example file may be cloned or downloaded and simply run on
any system with Python and Setuptools. It will download the
specified dependencies and run the tests. Afterward, the the
cloned directory can be removed and with it all trace of
invoking the test. No other dependencies are needed and no
system configuration is altered.
Then, anyone trying to replicate the failure can do so easily
and with all the power of pytest (rewritten assertions,
rich comparisons, interactive debugging, extensibility through
plugins, etc).
As a result, the communication barrier for describing and
replicating failures is made almost trivially low.
Considerations
==============
Conditional Requirement
-----------------------
Because it uses Setuptools setup_requires, pytest-runner will install itself
on every invocation of setup.py. In some cases, this causes delays for
invocations of setup.py that will never invoke pytest-runner. To help avoid
this contingency, consider requiring pytest-runner only when pytest
is invoked::
needs_pytest = {'pytest', 'test', 'ptr'}.intersection(sys.argv)
pytest_runner = ['pytest-runner'] if needs_pytest else []
# ...
setup(
#...
setup_requires=[
#... (other setup requirements)
] + pytest_runner,
)
For Enterprise
==============
Available as part of the Tidelift Subscription.
This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.
`Learn more <https://tidelift.com/subscription/pkg/pypi-PROJECT?utm_source=pypi-PROJECT&utm_medium=referral&utm_campaign=github>`_.
Security Contact
================
To report a security vulnerability, please use the
`Tidelift security contact <https://tidelift.com/security>`_.
Tidelift will coordinate the fix and disclosure.
Raw data
{
"_id": null,
"home_page": "https://github.com/pytest-dev/pytest-runner/",
"name": "pytest-runner",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Jason R. Coombs",
"author_email": "jaraco@jaraco.com",
"download_url": "https://files.pythonhosted.org/packages/d7/7d/60976d532519c3a0b41e06a59ad60949e2be1af937cf02738fec91bfd808/pytest-runner-6.0.1.tar.gz",
"platform": null,
"description": ".. image:: https://img.shields.io/pypi/v/pytest-runner.svg\n :target: `PyPI link`_\n\n.. image:: https://img.shields.io/pypi/pyversions/pytest-runner.svg\n :target: `PyPI link`_\n\n.. _PyPI link: https://pypi.org/project/pytest-runner\n\n.. image:: https://github.com/pytest-dev/pytest-runner/workflows/tests/badge.svg\n :target: https://github.com/pytest-dev/pytest-runner/actions?query=workflow%3A%22tests%22\n :alt: tests\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Code style: Black\n\n.. .. image:: https://readthedocs.org/projects/skeleton/badge/?version=latest\n.. :target: https://skeleton.readthedocs.io/en/latest/?badge=latest\n\n.. image:: https://img.shields.io/badge/skeleton-2022-informational\n :target: https://blog.jaraco.com/skeleton\n\n.. image:: https://tidelift.com/badges/package/pypi/pytest-runner\n :target: https://tidelift.com/subscription/pkg/pypi-pytest-runner?utm_source=pypi-pytest-runner&utm_medium=readme\n\nSetup scripts can use pytest-runner to add setup.py test support for pytest\nrunner.\n\nDeprecation Notice\n==================\n\npytest-runner depends on deprecated features of setuptools and relies on features that break security\nmechanisms in pip. For example 'setup_requires' and 'tests_require' bypass ``pip --require-hashes``.\nSee also `pypa/setuptools#1684 <https://github.com/pypa/setuptools/issues/1684>`_.\n\nIt is recommended that you:\n\n- Remove ``'pytest-runner'`` from your ``setup_requires``, preferably removing the ``setup_requires`` option.\n- Remove ``'pytest'`` and any other testing requirements from ``tests_require``, preferably removing the ``tests_requires`` option.\n- Select a tool to bootstrap and then run tests such as tox.\n\nUsage\n=====\n\n- Add 'pytest-runner' to your 'setup_requires'. Pin to '>=2.0,<3dev' (or\n similar) to avoid pulling in incompatible versions.\n- Include 'pytest' and any other testing requirements to 'tests_require'.\n- Invoke tests with ``setup.py pytest``.\n- Pass ``--index-url`` to have test requirements downloaded from an alternate\n index URL (unnecessary if specified for easy_install in setup.cfg).\n- Pass additional py.test command-line options using ``--addopts``.\n- Set permanent options for the ``python setup.py pytest`` command (like ``index-url``)\n in the ``[pytest]`` section of ``setup.cfg``.\n- Set permanent options for the ``py.test`` run (like ``addopts`` or ``pep8ignore``) in the ``[pytest]``\n section of ``pytest.ini`` or ``tox.ini`` or put them in the ``[tool:pytest]``\n section of ``setup.cfg``. See `pytest issue 567\n <https://github.com/pytest-dev/pytest/issues/567>`_.\n- Optionally, set ``test=pytest`` in the ``[aliases]`` section of ``setup.cfg``\n to cause ``python setup.py test`` to invoke pytest.\n\nExample\n=======\n\nThe most simple usage looks like this in setup.py::\n\n setup(\n setup_requires=[\n 'pytest-runner',\n ],\n tests_require=[\n 'pytest',\n ],\n )\n\nAdditional dependencies require to run the tests (e.g. mock or pytest\nplugins) may be added to tests_require and will be downloaded and\nrequired by the session before invoking pytest.\n\nFollow `this search on github\n<https://github.com/search?utf8=%E2%9C%93&q=filename%3Asetup.py+pytest-runner&type=Code&ref=searchresults>`_\nfor examples of real-world usage.\n\nStandalone Example\n==================\n\nThis technique is deprecated - if you have standalone scripts\nyou wish to invoke with dependencies, `use pip-run\n<https://pypi.org/project/pip-run>`_.\n\nAlthough ``pytest-runner`` is typically used to add pytest test\nrunner support to maintained packages, ``pytest-runner`` may\nalso be used to create standalone tests. Consider `this example\nfailure <https://gist.github.com/jaraco/d979a558bc0bf2194c23>`_,\nreported in `jsonpickle #117\n<https://github.com/jsonpickle/jsonpickle/issues/117>`_\nor `this MongoDB test\n<https://gist.github.com/jaraco/0b9e482f5c0a1300dc9a>`_\ndemonstrating a technique that works even when dependencies\nare required in the test.\n\nEither example file may be cloned or downloaded and simply run on\nany system with Python and Setuptools. It will download the\nspecified dependencies and run the tests. Afterward, the the\ncloned directory can be removed and with it all trace of\ninvoking the test. No other dependencies are needed and no\nsystem configuration is altered.\n\nThen, anyone trying to replicate the failure can do so easily\nand with all the power of pytest (rewritten assertions,\nrich comparisons, interactive debugging, extensibility through\nplugins, etc).\n\nAs a result, the communication barrier for describing and\nreplicating failures is made almost trivially low.\n\nConsiderations\n==============\n\nConditional Requirement\n-----------------------\n\nBecause it uses Setuptools setup_requires, pytest-runner will install itself\non every invocation of setup.py. In some cases, this causes delays for\ninvocations of setup.py that will never invoke pytest-runner. To help avoid\nthis contingency, consider requiring pytest-runner only when pytest\nis invoked::\n\n needs_pytest = {'pytest', 'test', 'ptr'}.intersection(sys.argv)\n pytest_runner = ['pytest-runner'] if needs_pytest else []\n\n # ...\n\n setup(\n #...\n setup_requires=[\n #... (other setup requirements)\n ] + pytest_runner,\n )\n\nFor Enterprise\n==============\n\nAvailable as part of the Tidelift Subscription.\n\nThis project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.\n\n`Learn more <https://tidelift.com/subscription/pkg/pypi-PROJECT?utm_source=pypi-PROJECT&utm_medium=referral&utm_campaign=github>`_.\n\nSecurity Contact\n================\n\nTo report a security vulnerability, please use the\n`Tidelift security contact <https://tidelift.com/security>`_.\nTidelift will coordinate the fix and disclosure.\n",
"bugtrack_url": null,
"license": "",
"summary": "Invoke py.test as distutils command with dependency resolution",
"version": "6.0.1",
"project_urls": {
"Homepage": "https://github.com/pytest-dev/pytest-runner/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "232b73982c02d28538b6a1182c0a2faf764ca6a76a6dbe89a69288184051a67b",
"md5": "75dcfa79cc47ecce1a3943f96aafd643",
"sha256": "ea326ed6f6613992746062362efab70212089a4209c08d67177b3df1c52cd9f2"
},
"downloads": -1,
"filename": "pytest_runner-6.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "75dcfa79cc47ecce1a3943f96aafd643",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7186,
"upload_time": "2023-12-04T01:03:28",
"upload_time_iso_8601": "2023-12-04T01:03:28.706336Z",
"url": "https://files.pythonhosted.org/packages/23/2b/73982c02d28538b6a1182c0a2faf764ca6a76a6dbe89a69288184051a67b/pytest_runner-6.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d77d60976d532519c3a0b41e06a59ad60949e2be1af937cf02738fec91bfd808",
"md5": "bd11f67561d7c4db8cf7e96b13ab469f",
"sha256": "70d4739585a7008f37bf4933c013fdb327b8878a5a69fcbb3316c88882f0f49b"
},
"downloads": -1,
"filename": "pytest-runner-6.0.1.tar.gz",
"has_sig": false,
"md5_digest": "bd11f67561d7c4db8cf7e96b13ab469f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16056,
"upload_time": "2023-12-04T01:03:30",
"upload_time_iso_8601": "2023-12-04T01:03:30.835801Z",
"url": "https://files.pythonhosted.org/packages/d7/7d/60976d532519c3a0b41e06a59ad60949e2be1af937cf02738fec91bfd808/pytest-runner-6.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-04 01:03:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pytest-dev",
"github_project": "pytest-runner",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "pytest-runner"
}
JSON
