PKG-INFO (10113B)
1 Metadata-Version: 2.1 2 Name: pytest-asyncio 3 Version: 0.19.0 4 Summary: Pytest support for asyncio 5 Home-page: https://github.com/pytest-dev/pytest-asyncio 6 Author: Tin Tvrtković <tinchester@gmail.com> 7 Author-email: tinchester@gmail.com 8 License: Apache 2.0 9 Project-URL: GitHub, https://github.com/pytest-dev/pytest-asyncio 10 Classifier: Development Status :: 4 - Beta 11 Classifier: Intended Audience :: Developers 12 Classifier: License :: OSI Approved :: Apache Software License 13 Classifier: Programming Language :: Python :: 3.7 14 Classifier: Programming Language :: Python :: 3.8 15 Classifier: Programming Language :: Python :: 3.9 16 Classifier: Programming Language :: Python :: 3.10 17 Classifier: Programming Language :: Python :: 3.11 18 Classifier: Topic :: Software Development :: Testing 19 Classifier: Framework :: AsyncIO 20 Classifier: Framework :: Pytest 21 Classifier: Typing :: Typed 22 Requires-Python: >=3.7 23 Description-Content-Type: text/x-rst 24 Provides-Extra: testing 25 License-File: LICENSE 26 27 pytest-asyncio: pytest support for asyncio 28 ========================================== 29 30 .. image:: https://img.shields.io/pypi/v/pytest-asyncio.svg 31 :target: https://pypi.python.org/pypi/pytest-asyncio 32 .. image:: https://github.com/pytest-dev/pytest-asyncio/workflows/CI/badge.svg 33 :target: https://github.com/pytest-dev/pytest-asyncio/actions?workflow=CI 34 .. image:: https://codecov.io/gh/pytest-dev/pytest-asyncio/branch/master/graph/badge.svg 35 :target: https://codecov.io/gh/pytest-dev/pytest-asyncio 36 .. image:: https://img.shields.io/pypi/pyversions/pytest-asyncio.svg 37 :target: https://github.com/pytest-dev/pytest-asyncio 38 :alt: Supported Python versions 39 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg 40 :target: https://github.com/ambv/black 41 42 pytest-asyncio is an Apache2 licensed library, written in Python, for testing 43 asyncio code with pytest. 44 45 asyncio code is usually written in the form of coroutines, which makes it 46 slightly more difficult to test using normal testing tools. pytest-asyncio 47 provides useful fixtures and markers to make testing easier. 48 49 .. code-block:: python 50 51 @pytest.mark.asyncio 52 async def test_some_asyncio_code(): 53 res = await library.do_something() 54 assert b"expected result" == res 55 56 pytest-asyncio has been strongly influenced by pytest-tornado_. 57 58 .. _pytest-tornado: https://github.com/eugeniy/pytest-tornado 59 60 Features 61 -------- 62 63 - fixtures for creating and injecting versions of the asyncio event loop 64 - fixtures for injecting unused tcp/udp ports 65 - pytest markers for treating tests as asyncio coroutines 66 - easy testing with non-default event loops 67 - support for `async def` fixtures and async generator fixtures 68 - support *auto* mode to handle all async fixtures and tests automatically by asyncio; 69 provide *strict* mode if a test suite should work with different async frameworks 70 simultaneously, e.g. ``asyncio`` and ``trio``. 71 72 Installation 73 ------------ 74 75 To install pytest-asyncio, simply: 76 77 .. code-block:: bash 78 79 $ pip install pytest-asyncio 80 81 This is enough for pytest to pick up pytest-asyncio. 82 83 Modes 84 ----- 85 86 Starting from ``pytest-asyncio>=0.17``, three modes are provided: *auto*, *strict* and 87 *legacy*. Starting from ``pytest-asyncio>=0.19`` the *strict* mode is the default. 88 89 The mode can be set by ``asyncio_mode`` configuration option in `configuration file 90 <https://docs.pytest.org/en/latest/reference/customize.html>`_: 91 92 .. code-block:: ini 93 94 # pytest.ini 95 [pytest] 96 asyncio_mode = auto 97 98 The value can be overridden by command-line option for ``pytest`` invocation: 99 100 .. code-block:: bash 101 102 $ pytest tests --asyncio-mode=strict 103 104 Auto mode 105 ~~~~~~~~~ 106 107 When the mode is auto, all discovered *async* tests are considered *asyncio-driven* even 108 if they have no ``@pytest.mark.asyncio`` marker. 109 110 All async fixtures are considered *asyncio-driven* as well, even if they are decorated 111 with a regular ``@pytest.fixture`` decorator instead of dedicated 112 ``@pytest_asyncio.fixture`` counterpart. 113 114 *asyncio-driven* means that tests and fixtures are executed by ``pytest-asyncio`` 115 plugin. 116 117 This mode requires the simplest tests and fixtures configuration and is 118 recommended for default usage *unless* the same project and its test suite should 119 execute tests from different async frameworks, e.g. ``asyncio`` and ``trio``. In this 120 case, auto-handling can break tests designed for other framework; please use *strict* 121 mode instead. 122 123 Strict mode 124 ~~~~~~~~~~~ 125 126 Strict mode enforces ``@pytest.mark.asyncio`` and ``@pytest_asyncio.fixture`` usage. 127 Without these markers, tests and fixtures are not considered as *asyncio-driven*, other 128 pytest plugin can handle them. 129 130 Please use this mode if multiple async frameworks should be combined in the same test 131 suite. 132 133 This mode is used by default for the sake of project inter-compatibility. 134 135 136 Legacy mode 137 ~~~~~~~~~~~ 138 139 This mode follows rules used by ``pytest-asyncio<0.17``: tests are not auto-marked but 140 fixtures are. 141 142 Deprecation warnings are emitted with suggestion to either switching to ``auto`` mode 143 or using ``strict`` mode with ``@pytest_asyncio.fixture`` decorators. 144 145 The default was changed to ``strict`` in ``pytest-asyncio>=0.19``. 146 147 148 Fixtures 149 -------- 150 151 ``event_loop`` 152 ~~~~~~~~~~~~~~ 153 Creates a new asyncio event loop based on the current event loop policy. The new loop 154 is available as the return value of this fixture or via `asyncio.get_running_loop <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.get_running_loop>`__. 155 The event loop is closed when the fixture scope ends. The fixture scope defaults 156 to ``function`` scope. 157 158 Note that just using the ``event_loop`` fixture won't make your test function 159 a coroutine. You'll need to interact with the event loop directly, using methods 160 like ``event_loop.run_until_complete``. See the ``pytest.mark.asyncio`` marker 161 for treating test functions like coroutines. 162 163 .. code-block:: python 164 165 def test_http_client(event_loop): 166 url = "http://httpbin.org/get" 167 resp = event_loop.run_until_complete(http_client(url)) 168 assert b"HTTP/1.1 200 OK" in resp 169 170 The ``event_loop`` fixture can be overridden in any of the standard pytest locations, 171 e.g. directly in the test file, or in ``conftest.py``. This allows redefining the 172 fixture scope, for example: 173 174 .. code-block:: python 175 176 @pytest.fixture(scope="session") 177 def event_loop(): 178 policy = asyncio.get_event_loop_policy() 179 loop = policy.new_event_loop() 180 yield loop 181 loop.close() 182 183 If you need to change the type of the event loop, prefer setting a custom event loop policy over redefining the ``event_loop`` fixture. 184 185 If the ``pytest.mark.asyncio`` marker is applied to a test function, the ``event_loop`` 186 fixture will be requested automatically by the test function. 187 188 ``unused_tcp_port`` 189 ~~~~~~~~~~~~~~~~~~~ 190 Finds and yields a single unused TCP port on the localhost interface. Useful for 191 binding temporary test servers. 192 193 ``unused_tcp_port_factory`` 194 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 195 A callable which returns a different unused TCP port each invocation. Useful 196 when several unused TCP ports are required in a test. 197 198 .. code-block:: python 199 200 def a_test(unused_tcp_port_factory): 201 port1, port2 = unused_tcp_port_factory(), unused_tcp_port_factory() 202 ... 203 204 ``unused_udp_port`` and ``unused_udp_port_factory`` 205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 206 Work just like their TCP counterparts but return unused UDP ports. 207 208 209 Async fixtures 210 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 211 Asynchronous fixtures are defined just like ordinary pytest fixtures, except they should be decorated with ``@pytest_asyncio.fixture``. 212 213 .. code-block:: python3 214 215 import pytest_asyncio 216 217 218 @pytest_asyncio.fixture 219 async def async_gen_fixture(): 220 await asyncio.sleep(0.1) 221 yield "a value" 222 223 224 @pytest_asyncio.fixture(scope="module") 225 async def async_fixture(): 226 return await asyncio.sleep(0.1) 227 228 All scopes are supported, but if you use a non-function scope you will need 229 to redefine the ``event_loop`` fixture to have the same or broader scope. 230 Async fixtures need the event loop, and so must have the same or narrower scope 231 than the ``event_loop`` fixture. 232 233 *auto* and *legacy* mode automatically converts async fixtures declared with the 234 standard ``@pytest.fixture`` decorator to *asyncio-driven* versions. 235 236 237 Markers 238 ------- 239 240 ``pytest.mark.asyncio`` 241 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 242 Mark your test coroutine with this marker and pytest will execute it as an 243 asyncio task using the event loop provided by the ``event_loop`` fixture. See 244 the introductory section for an example. 245 246 The event loop used can be overridden by overriding the ``event_loop`` fixture 247 (see above). 248 249 In order to make your test code a little more concise, the pytest |pytestmark|_ 250 feature can be used to mark entire modules or classes with this marker. 251 Only test coroutines will be affected (by default, coroutines prefixed by 252 ``test_``), so, for example, fixtures are safe to define. 253 254 .. code-block:: python 255 256 import asyncio 257 258 import pytest 259 260 # All test coroutines will be treated as marked. 261 pytestmark = pytest.mark.asyncio 262 263 264 async def test_example(event_loop): 265 """No marker!""" 266 await asyncio.sleep(0, loop=event_loop) 267 268 In *auto* mode, the ``pytest.mark.asyncio`` marker can be omitted, the marker is added 269 automatically to *async* test functions. 270 271 272 .. |pytestmark| replace:: ``pytestmark`` 273 .. _pytestmark: http://doc.pytest.org/en/latest/example/markers.html#marking-whole-classes-or-modules 274 275 Note about unittest 276 ------------------- 277 278 Test classes subclassing the standard `unittest <https://docs.python.org/3/library/unittest.html>`__ library are not supported, users 279 are recommended to use `unittest.IsolatedAsyncioTestCase <https://docs.python.org/3/library/unittest.html#unittest.IsolatedAsyncioTestCase>`__ 280 or an async framework such as `asynctest <https://asynctest.readthedocs.io/en/latest>`__. 281 282 Contributing 283 ------------ 284 Contributions are very welcome. Tests can be run with ``tox``, please ensure 285 the coverage at least stays the same before you submit a pull request.