A solipsist event loop

async-solipsism provides a Python asyncio event loop that does not interact with the outside world at all. This is ideal for writing unit tests that intend to mock out real-world interactions. It makes for tests that are reliable (unaffected by network outages), reproducible (not affected by random timing effects) and portable (run the same everywhere).

Features

Clock

A very handy feature is that time runs infinitely fast! What's more, time advances only when explicitly waiting. For example, this code will print out two times that are exactly 60s apart, and will take negligible real time to run:

print(loop.time())
await asyncio.sleep(60)
print(loop.time())

This also provides a handy way to ensure that all pending callbacks have a chance to run: just sleep for a second.

The simulated clock has microsecond resolution, independent of whatever resolution the system clock has. This helps ensure that tests behave the same across operating systems.

Sometimes buggy code or a buggy test will await an event that will never happen. For example, it might wait for data to arrive on a socket, but forget to insert data into the other end. If async-solipsism detects that it will never wake up again, it will raise a SleepForeverError rather than leaving your test to hang.

Sockets

While real sockets cannot be used, async-solipsism provides mock sockets that implement just enough functionality to be used with the event loop. Sockets are obtained by calling async_solipsism.socketpair(), which returns two sockets that are connected to each other. They can then be used with event loop functions like sock_sendall or create_connection.

Because the socket implementation is minimal, you may run into cases where the internals of asyncio try to call methods that aren't implemented. Pull requests are welcome.

Each direction of flow implements a buffer that holds data written to the one socket but not yet received by the other. If this buffer fills up, write calls will raise BlockingIOError, just like a real non-blocking socket. This can be used to test that your protocol properly handles flow control. The size of these buffers can be changed with the optional capacity argument to socketpair.

Streams

As a convenience, it is possible to open two pairs of streams that are connected to each other, with

((reader1, writer1), (reader2, writer2)) = await async_solipsism.stream_pairs()

Anything written to writer1 will be received by reader2, and anything written to writer2 will be received by reader1.

Servers

It is also possible to use the asyncio functions for starting servers and connecting to them. You can supply any host name and port, even if they're not actually associated with the machine! For example,

server = await asyncio.start_server(callback, 'test.invalid', 1234)
reader, writer = await asyncio.open_connection('test.invalid', 1234)

will start a server, then open a client connection to it. The reader and writer represent the client end of the connection, and the callback will be given the server end of the connection.

The host and port are associated with the event loop, and are remembered until the server is closed. Attempting to connect after closing the server, or to an address that hasn't been registered, will raise a ConnectionRefusedError.

If you don't want the bother of picking non-colliding ports, you can pass a port number of 0, and async-solipsism will bind the first port number above 60000 that is unused.

Integration with pytest-asyncio

async-solipsism and pytest-asyncio complement each other well: just write a custom event_loop_policy fixture in your test file or conftest.py and it will override the default provided by pytest-asyncio:

@pytest.fixture
def event_loop_policy():
    return async_solipsism.EventLoopPolicy()

The above is for pytest-asyncio 0.23+. If you're using an older version, then instead you should do this:

@pytest.fixture
def event_loop():
    loop = async_solipsism.EventLoop()
    yield loop
    loop.close()

Integration with aiohappyeyeballs

Unfortunately aiohappyeyeballs.start_connection doesn't work out of the box because it relies on creating a real socket. I've created a replacement async_solipsism.aiohappyeyeballs_start_connection that can be used to replace it. See the aiohttp section below for example code.

Integration with aiohttp

A little extra work is required to work with aiohttp's test utilities, but it is possible. The example below requires at least aiohttp 3.8.0.

import async_solipsism
import pytest
from aiohttp import web, test_utils


@pytest.fixture
def event_loop_policy():
    return async_solipsism.EventLoopPolicy()


@pytest.fixture(autouse=True)
def mock_start_connection(monkeypatch):
    monkeypatch.setattr("aiohappyeyeballs.start_connection",
                        async_solipsism.aiohappyeyeballs_start_connection)


def socket_factory(host, port, family):
    return async_solipsism.ListenSocket((host, port))


async def test_integration():
    app = web.Application()
    async with test_utils.TestServer(app, socket_factory=socket_factory) as server:
        async with test_utils.TestClient(server) as client:
            resp = await client.post("/hey", json={})
            assert resp.status == 404

Note that this relies on pytest-asyncio (in auto mode) and does not use pytest-aiohttp. The fixtures provided by the latter do not support overriding the socket factory, although it may be possible to do by monkeypatching. In practice you will probably want to define your own fixtures for the client and server.

Limitations

The requirement to have no interaction with the outside world naturally imposes some restrictions. Other restrictions exist purely because I haven't gotten around to figuring out what a fake version should look like and implementing it. The following are all unsupported:

• call_soon_threadsafe, except when called from the thread running the event loop (it just forwards to call_soon). Multithreading is fundamentally incompatible with the fast-forward clock.
• getaddrinfo and getnameinfo
• connect_read_pipe and connect_write_pipe
• signal handlers
• subprocesses
• TLS/SSL
• datagrams (UDP)
• UNIX domain sockets
• any Windows-specific features

run_in_executor is supported, but it blocks the event loop while the task runs in the executor. This works fine for short-running tasks like reading some data from a file, but is not suitable if the task is a long-running one such as a sidecar server.

Calling functions that are not supported will generally raise SolipsismError.

Changelog

0.7

• Add a replacement function for aiohappyeyeballs.start_connection.

0.6

• Drop support for Python 3.6 and 3.7, which have reached end of life.
• Add EventLoopPolicy to simplify integration with pytest-asyncio 0.23+, and use it for the internal tests.
• Make Socket.write and Socket.recv_into accept arbitrary buffer-protocol objects.
• Various packaging and developer experience improvements:
  • Put the packaging metadata in pyproject.toml, removing setup.cfg.
  • Pin versions for CI in requirements.txt using pip-compile.
  • Use pre-commit to enforce flake8 and pip-compile.
  • Remove wheel from build-system.requires (on setuptools advice).
  • Test against Python 3.11 and 3.12.
  • Run CI workflow against pull requests.

0.5

• Map port 0 to an unused port.

0.4

• Allow call_soon_threadsafe from the same thread.
• Don't warn when SO_KEEPALIVE is set on a socket.
• Update instructions for use with aiohttp.
• Add a pyproject.toml.

0.3

• Fix start_server with an explicit socket.
• Update README with an example of aiohttp integration.

0.2

• Numerous fixes to make the fake sockets behave more like real ones.
• Sockets now return IPv6 addresses from getsockname.
• Implement setsockopt.
• Introduce SolipsismWarning base class for warnings.

0.1

First release.