pytest-asyncio

https://pytest-asyncio.readthedocs.io/en/stable/
Admin
A pytest plugin that facilitates testing of asyncio code, allowing users to write and run async...
Tokens:26,959
Snippets:272
Trust Score:9.6
Update:5 days ago
Show doc for...
Tokens:
Raw
### Example tests using default and custom event loop factories

Source: https://pytest-asyncio.readthedocs.io/en/stable/how-to-guides/configure_loop_factories_per_test.html

These tests demonstrate how to use the custom factory by requesting the 'requires_custom_loop' fixture. The first test runs only with the default factory, the second only with the custom factory.

```python
import pytest


@pytest.mark.asyncio
async def test_runs_with_default_factory_only():
    pass


@pytest.mark.asyncio
async def test_runs_with_custom_factory_only(requires_custom_loop):
    pass

```

--------------------------------

### Basic asyncio test with pytest.mark.asyncio

Source: https://pytest-asyncio.readthedocs.io/en/stable/concepts.html

A simple async test that verifies an event loop is running. Use this as a minimal example of marking an async test with @pytest.mark.asyncio.

```python
import asyncio

import pytest


@pytest.mark.asyncio
async def test_runs_in_a_loop():
    assert asyncio.get_running_loop()

```

--------------------------------

### Using @pytest_asyncio.fixture with different loop scopes

Source: https://pytest-asyncio.readthedocs.io/en/stable/reference/decorators/index.html

Shows four examples of using @pytest_asyncio.fixture with various loop_scope and scope combinations. The first uses the default function loop scope, the second uses a session loop with module caching scope, the third uses a module loop with module caching scope, and the fourth uses a module loop with function caching scope. The loop scope must be larger or the same as the fixture's caching scope.

```python
import pytest_asyncio


@pytest_asyncio.fixture
async def fixture_runs_in_fresh_loop_for_every_function(): ...


@pytest_asyncio.fixture(loop_scope="session", scope="module")
async def fixture_runs_in_session_loop_once_per_module(): ...


@pytest_asyncio.fixture(loop_scope="module", scope="module")
async def fixture_runs_in_module_loop_once_per_module(): ...


@pytest_asyncio.fixture(loop_scope="module")
async def fixture_runs_in_module_loop_once_per_function(): ...

```

--------------------------------

### Parametrize event_loop_policy fixture to run tests with multiple event loops

Source: https://pytest-asyncio.readthedocs.io/en/stable/how-to-guides/multiple_loops.html

Defines a session-scoped fixture that parametrizes the event_loop_policy with two instances of a custom policy, causing all async tests to run once per policy. The example suppresses deprecation warnings for the deprecated fixture and includes a test that asserts the custom policy is active. Use this when you need to run tests against multiple event loop policies, but note that this approach is deprecated and will be removed in future versions.

```python
import asyncio
import warnings

with warnings.catch_warnings():
    warnings.simplefilter("ignore", DeprecationWarning)
    from asyncio import DefaultEventLoopPolicy

import pytest


class CustomEventLoopPolicy(DefaultEventLoopPolicy):
    pass


@pytest.fixture(
    scope="session",
    params=(
        CustomEventLoopPolicy(),
        CustomEventLoopPolicy(),
    ),
)
def event_loop_policy(request):
    return request.param


@pytest.mark.asyncio
@pytest.mark.filterwarnings("ignore::DeprecationWarning")
async def test_uses_custom_event_loop_policy():
    assert isinstance(asyncio.get_event_loop_policy(), CustomEventLoopPolicy)

```

--------------------------------

### Implement pytest_asyncio_loop_factories hook in conftest.py

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/how-to-guides/custom_loop_factory.rst.txt

Define a pytest_asyncio_loop_factories hook that returns a mapping of factory names to loop factory callables. The hook receives the pytest item, enabling different factory mappings per test. This example provides 'stdlib' and 'custom' factories, where 'custom' uses a custom event loop class.

```python
import asyncio

import pytest


class CustomEventLoop(asyncio.SelectorEventLoop):
    pass


def pytest_asyncio_loop_factories(config, item):
    return {
        "stdlib": asyncio.new_event_loop,
        "custom": CustomEventLoop,
    }
```

--------------------------------

### Module-level pytestmark with loop_scope='module'

Source: https://pytest-asyncio.readthedocs.io/en/stable/how-to-guides/run_module_tests_in_same_loop.html

Use this snippet to run all tests in a module within the same event loop. It sets a module-level pytestmark that applies the asyncio marker with loop_scope='module' to every test in the module. The example includes two tests that verify the same event loop is used across tests.

```python
import asyncio

import pytest

pytestmark = pytest.mark.asyncio(loop_scope="module")

loop: asyncio.AbstractEventLoop


async def test_remember_loop():
    global loop
    loop = asyncio.get_running_loop()


async def test_assert_same_loop():
    global loop
    assert asyncio.get_running_loop() is loop

```

--------------------------------

### Set asyncio_default_fixture_loop_scope in setup.cfg

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/how-to-guides/change_default_fixture_loop.rst.txt

Configure all async fixtures to use a session-scoped event loop by default in a setup.cfg file. The option is set under the [tool:pytest] section.

```ini
[tool:pytest]
asyncio_default_fixture_loop_scope = session
```

--------------------------------

### Run all tests in a class in the same event loop with pytest.mark.asyncio(loop_scope='class')

Source: https://pytest-asyncio.readthedocs.io/en/stable/how-to-guides/run_class_tests_in_same_loop.html

Mark a test class with @pytest.mark.asyncio(loop_scope='class') to run all its tests in the same event loop. The example stores the running loop in a class attribute and asserts that a later test runs in the same loop.

```python
import asyncio

import pytest


@pytest.mark.asyncio(loop_scope="class")
class TestInOneEventLoopPerClass:
    loop: asyncio.AbstractEventLoop

    async def test_remember_loop(self):
        TestInOneEventLoopPerClass.loop = asyncio.get_running_loop()

    async def test_assert_same_loop(self):
        assert asyncio.get_running_loop() is TestInOneEventLoopPerClass.loop

```

--------------------------------

### Use unused_tcp_port_factory

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/reference/fixtures/index.rst.txt

Demonstrates using the unused_tcp_port_factory fixture to obtain multiple unused TCP ports in a test.

```python
def a_test(unused_tcp_port_factory):
    _port1, _port2 = unused_tcp_port_factory(), unused_tcp_port_factory()
```

--------------------------------

### Override event_loop_policy fixture with custom policy

Source: https://pytest-asyncio.readthedocs.io/en/stable/reference/fixtures/index.html

Shows how to override the deprecated event_loop_policy fixture to return a custom event loop policy. The fixture is automatically applied to all pytest-asyncio tests. The example defines a CustomEventLoopPolicy and uses it in a test with module-scoped loop. Deprecation warnings are suppressed.

```python
import asyncio
import warnings

with warnings.catch_warnings():
    warnings.simplefilter("ignore", DeprecationWarning)
    from asyncio import DefaultEventLoopPolicy

import pytest


class CustomEventLoopPolicy(DefaultEventLoopPolicy):
    pass


@pytest.fixture(scope="module")
def event_loop_policy(request):
    return CustomEventLoopPolicy()


@pytest.mark.asyncio(loop_scope="module")
@pytest.mark.filterwarnings("ignore::DeprecationWarning")
async def test_uses_custom_event_loop_policy():
    assert isinstance(asyncio.get_event_loop_policy(), CustomEventLoopPolicy)

```

--------------------------------

### Auto mode configuration

Source: https://pytest-asyncio.readthedocs.io/en/stable/concepts.html

Configuration for auto mode, which automatically adds the asyncio marker to all async test functions and takes ownership of all async fixtures.

```toml
[tool.pytest.ini_options]
asyncio_mode = "auto"

```

--------------------------------

### Set package-level pytestmark for same event loop

Source: https://pytest-asyncio.readthedocs.io/en/stable/how-to-guides/run_package_tests_in_same_loop.html

Add this code to the __init__.py of the test package to run all tests in the same event loop. The marker is not passed down to subpackages; each subpackage constitutes its own separate package.

```python
import pytest

pytestmark = pytest.mark.asyncio(loop_scope="package")

```

--------------------------------

### Set asyncio_mode via command line

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/reference/configuration.rst.txt

Uses the --asyncio-mode command-line option to set the asyncio mode to strict. The command-line option takes precedence over the configuration file if both are set.

```bash
$ pytest tests --asyncio-mode=strict
```

--------------------------------

### Set asyncio_default_test_loop_scope in setup.cfg

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/how-to-guides/change_default_test_loop.rst.txt

Configure pytest to use a session-scoped event loop by default for all async tests. Place this in your setup.cfg file under the [tool:pytest] section.

```ini
[tool:pytest]
asyncio_default_test_loop_scope = session
```

--------------------------------

### Select specific loop factories with loop_factories

Source: https://pytest-asyncio.readthedocs.io/en/stable/how-to-guides/run_test_with_specific_loop_factories.html

Shows how to use the `loop_factories` parameter in `@pytest.mark.asyncio` to run a test only with the 'custom' factory, while a test without the parameter runs with every configured factory. If a requested factory name is not available, the test variant is skipped.

```python
import pytest


@pytest.mark.asyncio
async def test_runs_with_every_configured_factory():
    pass


@pytest.mark.asyncio(loop_factories=["custom"])
async def test_runs_with_only_custom_factory():
    pass

```

--------------------------------

### Run pytest with --asyncio-mode=strict command-line option

Source: https://pytest-asyncio.readthedocs.io/en/stable/reference/configuration.html

Use the --asyncio-mode=strict command-line option to set the asyncio mode to strict. If the asyncio mode is set in both the configuration file and the command-line option, the command-line option takes precedence.

```bash
$ pytest tests --asyncio-mode=strict

```

--------------------------------

### Parametrize an async test with pytest.mark.parametrize

Source: https://pytest-asyncio.readthedocs.io/en/stable/how-to-guides/parametrize_with_asyncio.html

Apply both pytest.mark.asyncio and pytest.mark.parametrize to an async test function. Each test case runs sequentially, not concurrently.

```python
import asyncio

import pytest


@pytest.mark.asyncio
@pytest.mark.parametrize("value", [1, 2, 3])
async def test_parametrized_async_function(value):
    await asyncio.sleep(1)
    assert value > 0

```

--------------------------------

### Set asyncio_default_fixture_loop_scope in pyproject.toml

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/how-to-guides/change_default_fixture_loop.rst.txt

Configure all async fixtures to use a session-scoped event loop by default in a pyproject.toml file. The option is set under the [tool.pytest.ini_options] table.

```toml
[tool.pytest.ini_options]
asyncio_default_fixture_loop_scope = "session"
```

--------------------------------

### Parametrize event_loop_policy fixture

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/reference/fixtures/index.rst.txt

Shows how to parametrize the event_loop_policy fixture to run tests with multiple event loop policies. The fixture is automatically applied to all pytest-asyncio tests, so each test runs once per parameter.

```python
.. include:: event_loop_policy_parametrized_example.py
    :code: python
```

--------------------------------

### Auto mode configuration in pyproject.toml

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/concepts.rst.txt

Sets asyncio_mode to auto, which automatically adds the asyncio marker to async tests and takes ownership of all async fixtures.

```toml
[tool.pytest.ini_options]
asyncio_mode = "auto"
```

--------------------------------

### Define a module-scoped async fixture and test

Source: https://pytest-asyncio.readthedocs.io/en/stable/how-to-guides/change_fixture_loop.html

Use the loop_scope='module' argument to run the fixture in a module-scoped event loop. The test also uses loop_scope='module' to ensure it runs in the same loop, and asserts that the fixture's loop is the running loop.

```python
import asyncio

import pytest

import pytest_asyncio


@pytest_asyncio.fixture(loop_scope="module")
async def current_loop():
    return asyncio.get_running_loop()


@pytest.mark.asyncio(loop_scope="module")
async def test_runs_in_module_loop(current_loop):
    assert current_loop is asyncio.get_running_loop()

```

--------------------------------

### Apply pytest.mark.asyncio via pytestmark module variable

Source: https://pytest-asyncio.readthedocs.io/en/stable/reference/markers/index.html

Marks all test coroutines in a module by setting pytestmark = pytest.mark.asyncio. This is an alternative to decorating each test individually.

```python
import asyncio

import pytest

# Marks all test coroutines in this module
pytestmark = pytest.mark.asyncio


async def test_runs_in_asyncio_event_loop():
    assert asyncio.get_running_loop()

```

--------------------------------

### Strict mode configuration in pyproject.toml

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/concepts.rst.txt

Sets asyncio_mode to strict, the default mode, which only runs tests with the asyncio marker and async fixtures decorated with @pytest_asyncio.fixture.

```toml
[tool.pytest.ini_options]
asyncio_mode = "strict"
```

--------------------------------

### Async test function with @pytest.mark.asyncio

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/index.rst.txt

Use this snippet to write an async test function that can await asyncio code. The test is marked with @pytest.mark.asyncio and runs as a pytest test item. Note that test classes subclassing unittest are not supported.

```python
@pytest.mark.asyncio
async def test_some_asyncio_code():
    res = await library.do_something()
    assert b"expected result" == res
```

--------------------------------

### pytest --collect-only output for a test module

Source: https://pytest-asyncio.readthedocs.io/en/stable/_sources/concepts.rst.txt

Shows the collection hierarchy for a test module and function, illustrating pytest collectors.

```text
<Module test_all_the_things.py>
  <Function test_runs_in_a_loop>
```

--------------------------------

### Apply pytest.mark.asyncio as a decorator

Source: https://pytest-asyncio.readthedocs.io/en/stable/reference/markers/index.html

Marks a single async test function with @pytest.mark.asyncio. The test runs as an asyncio task in the event loop provided by pytest-asyncio.

```python
import asyncio

import pytest


@pytest.mark.asyncio
async def test_runs_in_asyncio_event_loop():
    assert asyncio.get_running_loop()

```
Tokens:
Raw