pytest-twisted

1.14.3 · active · verified Thu Apr 16

pytest-twisted is a plugin for the pytest testing framework that facilitates testing code built with the Twisted asynchronous networking framework. It allows pytest test functions to return Twisted Deferred objects, ensuring that tests wait for asynchronous operations to complete, and manages the Twisted reactor lifecycle within the test suite. The library is actively maintained, with its current version being 1.14.3.

Common errors

```
RuntimeError: This event loop is already running
```
cause Attempting to run `twisted.trial.unittest.TestCase` tests alongside standard `pytest-twisted` tests, particularly when the `asyncio` reactor is enabled, leading to conflicting event loop management.

fix Isolate `twisted.trial` tests from `pytest-twisted` tests or avoid using `asyncio` reactor when running mixed tests. `pytest-twisted` is optimized for `pytest`-style tests returning `Deferreds`.
```
NotImplementedError (typically on Windows with Python 3.8+ and asyncio reactor)
```
cause The default `asyncio` proactor event loop on Windows in Python 3.8+ is not fully compatible with Twisted's `asyncio` reactor implementation.

fix Force the use of the `asyncio.WindowsSelectorEventLoopPolicy` in a `conftest.py` file to ensure the selector loop is used. Refer to the 'Gotcha' warning for a code example.
```
Tests hang indefinitely without error output.
```
cause An unhandled exception within a `Deferred` chain (e.g., a missing `errback` handler) can prevent the Deferred from firing, causing `pytest-twisted` to wait indefinitely.

fix Ensure all `Deferred` objects have appropriate `addErrback` handlers to catch and log exceptions. Use Twisted's debugging tools (like `Deferred.debug(True)`) during development to identify unhandled errors.
```
DeprecationWarning: returnValue was deprecated in Twisted 24.7.0; please use standard return statement instead.
```
cause Using `twisted.internet.defer.returnValue()` within `inlineCallbacks` generators instead of a plain `return` statement, which is no longer recommended in recent Twisted versions.

fix Replace all instances of `returnValue(value)` with `return value` in `inlineCallbacks`-decorated functions.

Warnings

deprecated `twisted.internet.defer.returnValue` is deprecated since Twisted 24.7.0. Users should migrate to using standard Python `return` statements in `inlineCallbacks` generators.
Fix: Replace `returnValue(value)` with `return value` in `inlineCallbacks`-decorated functions and generators. Ensure `except:` clauses are changed to `except Exception:` to avoid catching `returnValue`'s internal `BaseException` subclass.
gotcha On Windows with Python 3.8+ and the `asyncio` reactor, you might encounter a `NotImplementedError` due to asyncio's default proactor loop not fully supporting Twisted's `asyncio` integration.
Fix: Explicitly set the `asyncio` event loop policy to `asyncio.WindowsSelectorEventLoopPolicy` early in your test suite, typically in a `conftest.py` file, to use the selector loop. Example `conftest.py` snippet: ```python import sys import pytest import asyncio @pytest.hookimpl(tryfirst=True) def pytest_configure(config): if (config.getoption("reactor", "default") == "asyncio" and sys.platform == 'win32' and sys.version_info >= (3, 8)): selector_policy = asyncio.WindowsSelectorEventLoopPolicy() asyncio.set_event_loop_policy(selector_policy) ```
gotcha Directly using `twisted.internet.defer.inlineCallbacks` or `twisted.internet.defer.ensureDeferred` as decorators for pytest test functions that rely on fixtures can lead to unexpected behavior or failures.
Fix: Always use the `inlineCallbacks` and `ensureDeferred` decorators provided by `pytest_twisted` (i.e., `from pytest_twisted import inlineCallbacks`) when writing tests with fixtures.
gotcha Mixing `pytest` tests with `twisted.trial.unittest.TestCase` in the same test run, especially when using the `--reactor=asyncio` option, can result in a `RuntimeError: This event loop is already running`.
Fix: It is generally recommended to separate tests written for `twisted.trial` from `pytest`-style tests that leverage `pytest-twisted`, or to ensure that trial tests do not attempt to manage the reactor in a way that conflicts with `pytest-twisted`'s reactor management. `pytest-twisted` is primarily designed for native `pytest` functions returning `Deferreds`.
breaking Older versions of `pytest-twisted` might have compatibility issues with newer `pytest` releases (e.g., `pytest` 8.2.0+).
Fix: Ensure `pytest-twisted` is updated to the latest version (1.14.2 or higher) to ensure compatibility with `pytest` 8.2.0 and later.
breaking The behavior of `pytest.skip()` in `twisted.trial` unittests changed with Twisted 25.5.0, potentially causing unhandled exceptions when `pytest-twisted` is used.
Fix: Upgrade `pytest` to at least 8.4.1, which includes fixes for compatibility with Twisted 25+.

Install

pip install pytest-twisted Install stable release

Imports

inlineCallbacks
wrong:
```
from twisted.internet.defer import inlineCallbacks
```
correct:
```
from pytest_twisted import inlineCallbacks
```
When using `inlineCallbacks` in pytest test functions, especially with fixtures, use the version provided by `pytest-twisted` to ensure proper integration with pytest's test collection and fixture management.
ensureDeferred
wrong:
```
from twisted.internet.defer import ensureDeferred
```
correct:
```
from pytest_twisted import ensureDeferred
```
Similar to `inlineCallbacks`, if you are decorating pytest test functions with `ensureDeferred`, use the version from `pytest_twisted` for correct behavior with fixtures.
pytest_twisted
```
import pytest_twisted
```
The main module, often used for configuring the reactor or accessing utility functions if needed explicitly in `conftest.py` or setup code.

Quickstart

This quickstart demonstrates how to write a basic test using `pytest-twisted`. It shows a test function decorated with `pytest_twisted.inlineCallbacks` that yields a Twisted Deferred and asserts its result. A second example checks if the Twisted reactor is running within the test context. You can specify a reactor type using `--reactor` (e.g., `--reactor=asyncio`) when running pytest.

import pytest
from twisted.internet.defer import Deferred
from pytest_twisted import inlineCallbacks

@inlineCallbacks
def test_deferred_returns_value():
    d = Deferred()
    d.callback('hello')
    result = yield d
    assert result == 'hello'

@pytest.mark.reactor_default # Or specify --reactor=asyncio in pytest command
@inlineCallbacks
def test_reactor_is_running():
    from twisted.internet import reactor
    assert reactor.running

# To run this, save as test_example.py and run: pytest test_example.py

view raw JSON →