# testing

URL: /pounce/api/testing/
Section: api
Description: First-class testing utilities for pounce.

Provides ``TestServer`` for running a real pounce server in tests — works with
httpx, Playwright, Selenium, or any HTTP client.

Usage::

    from pounce.testing import TestServer

    def test_homepage():
        with TestServer(app) as server:
            resp = httpx.get(f"{server.url}/")
            assert resp.status_code == 200

When pounce is installed, the ``pounce_server`` pytest fixture is auto-registered
via the ``pytest11`` entry point.

---

> For a complete page index, fetch /pounce/llms.txt.

Open LLM text
(/pounce/api/testing/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Ftesting%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Ftesting%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Ftesting%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Ftesting%2Findex.txt)

Module

#
`testing`

First-class testing utilities for pounce.

Provides`TestServer`for running a real pounce server in tests — works with
httpx, Playwright, Selenium, or any HTTP client.

Usage::

```
from pounce.testing import TestServer

def test_homepage():
    with TestServer(app) as server:
        resp = httpx.get(f"{server.url}/")
        assert resp.status_code == 200
```

When pounce is installed, the`pounce_server`pytest fixture is auto-registered
via the`pytest11`entry point.

2Classes1Function

## Classes

`TestServer`

11

▼

Run a real pounce server in a background thread for testing.

Run a real pounce server in a background thread for testing.

#### Methods

`host`

0

`str`

▼

The host the server is bound to.

property

`def host(self) -> str`

##### Returns

`str`

`port`

0

`int`

▼

The actual port the server is listening on (useful with ``port=0``).

property

`def port(self) -> int`

##### Returns

`int`

`url`

0

`str`

▼

Base URL for the running server (e.g. ``http://127.0.0.1:54321``).

property

`def url(self) -> str`

##### Returns

`str`

`is_running`

0

`bool`

▼

Whether the server background thread is alive.

property

`def is_running(self) -> bool`

##### Returns

`bool`

`start`

1

▼

Start the server in a background thread. Blocks until ready.

`def start(self, *, timeout: float = 5.0) -> None`

##### Parameters

Name
Type
Description

`timeout`
`—`

Default:`5.0`

`stop`

1

▼

Gracefully stop the server and join the background thread.

`def stop(self, *, timeout: float = 5.0) -> None`

##### Parameters

Name
Type
Description

`timeout`
`—`

Default:`5.0`

Internal Methods
5

▼

`__init__`

4

▼

`def __init__(self, app: ASGIApp, *, host: str = '127.0.0.1', port: int = 0, **config_kwargs: Any) -> None`

##### Parameters

Name
Type
Description

`app`
`—`

`host`
`—`

Default:`'127.0.0.1'`

`port`
`—`

Default:`0`

`**config_kwargs`
`—`

`__enter__`

0

`TestServer (/pounce/api/testing/#TestServer)`

▼

`def __enter__(self) -> TestServer`

##### Returns

`TestServer (/pounce/api/testing/#TestServer)`

`__exit__`

1

▼

`def __exit__(self, *exc: object) -> None`

##### Parameters

Name
Type
Description

`*exc`
`—`

`__aenter__`

0

`TestServer (/pounce/api/testing/#TestServer)`

▼

async

`async def __aenter__(self) -> TestServer`

##### Returns

`TestServer (/pounce/api/testing/#TestServer)`

`__aexit__`

1

▼

async

`async def __aexit__(self, *exc: object) -> None`

##### Parameters

Name
Type
Description

`*exc`
`—`

`RoundRobinTestProxy`

9

▼

Pin each incoming TCP connection to the next test server.

This intentionally small raw-TCP proxy p…

Pin each incoming TCP connection to the next test server.

This intentionally small raw-TCP proxy preserves streaming responses and
is suitable for multi-instance SSE integration tests. It is not a
production reverse proxy and does not add forwarding headers.

#### Methods

`host`

0

`str`

▼

property

`def host(self) -> str`

##### Returns

`str`

`port`

0

`int`

▼

property

`def port(self) -> int`

##### Returns

`int`

`url`

0

`str`

▼

property

`def url(self) -> str`

##### Returns

`str`

`is_running`

0

`bool`

▼

property

`def is_running(self) -> bool`

##### Returns

`bool`

`start`

1

▼

Start the proxy and wait until its listener is ready.

`def start(self, *, timeout: float = 5.0) -> None`

##### Parameters

Name
Type
Description

`timeout`
`—`

Default:`5.0`

`stop`

1

▼

Stop accepting connections and cancel active proxy streams.

`def stop(self, *, timeout: float = 5.0) -> None`

##### Parameters

Name
Type
Description

`timeout`
`—`

Default:`5.0`

Internal Methods
3

▼

`__init__`

3

▼

`def __init__(self, backends: Sequence[TestServer], *, host: str = '127.0.0.1', port: int = 0) -> None`

##### Parameters

Name
Type
Description

`backends`
`—`

`host`
`—`

Default:`'127.0.0.1'`

`port`
`—`

Default:`0`

`__enter__`

0

`RoundRobinTestProxy (/pounce/api/testing/#RoundRobinTestProxy)`

▼

`def __enter__(self) -> RoundRobinTestProxy`

##### Returns

`RoundRobinTestProxy (/pounce/api/testing/#RoundRobinTestProxy)`

`__exit__`

1

▼

`def __exit__(self, *exc: object) -> None`

##### Parameters

Name
Type
Description

`*exc`
`—`

## Functions

`serve`

2

`AsyncIterator[TestServer (/pounce/api/testing/#TestServer)]`

▼

Async context manager that starts and stops a `TestServer`.

Example::

asy…

async

`async def serve(app: ASGIApp, **kwargs: Any) -> AsyncIterator[TestServer]`

Async context manager that starts and stops a `TestServer` (/pounce/api/testing/#TestServer).

Example::

```
async with serve(app) as server:
    async with httpx.AsyncClient() as client:
        resp = await client.get(server.url)
```

##### Parameters

Name
Type
Description

`app`
`ASGIApp`

`**kwargs`
`Any`

##### Returns

`AsyncIterator[TestServer (/pounce/api/testing/#TestServer)]`