Testing MicroPie applications
=============================

This guide shows practical approaches for testing MicroPie applications.
MicroPie does not ship with a bespoke test client, but because it is a
regular ASGI application you can exercise it using familiar Python
libraries such as :mod:`unittest`, :mod:`pytest` and
:mod:`httpx`'s ASGI tools.

Choosing a test framework
-------------------------

MicroPie itself uses :class:`unittest.IsolatedAsyncioTestCase` in
``tests.py`` to run asynchronous tests. ``pytest`` with the
``pytest-asyncio`` plugin offers a similar developer experience. Pick the
library that best matches your project's conventions—the examples below
work with either.

Unit testing handlers directly
------------------------------

Because handlers are regular functions, you can instantiate your
:class:`~micropie.App` subclass and call methods directly. Use the
:data:`micropie.current_request` context variable to set up any request
state that your handler expects.

.. code-block:: python

   from micropie import App, Request, current_request

   class MyApp(App):
       async def greet(self, name="World"):
           return f"Hello {name}!"

   async def test_greet_uses_default():
       app = MyApp()
       scope = {"type": "http", "method": "GET", "path": "/"}
       request = Request(scope)
       token = current_request.set(request)
       try:
           response = await app.greet()
       finally:
           current_request.reset(token)
       assert response == "Hello World!"

Testing through the ASGI interface
----------------------------------

For higher confidence, drive the full ASGI stack. ``httpx`` provides an
``ASGITransport`` class that can mount a MicroPie app. Install ``httpx``
with ``pip install httpx``. The example below uses ``pytest`` style
asserts, but the structure works in ``unittest`` with
``self.assertEqual``.

.. code-block:: python

   import pytest
   import httpx

   from micropie import App

   class MyApp(App):
       async def index(self):
           return {"status": "ok"}

   @pytest.mark.asyncio
   async def test_index_returns_json():
       app = MyApp()
       async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app)) as client:
           response = await client.get("http://test/")
       assert response.status_code == 200
       assert response.json() == {"status": "ok"}

Simulating sessions and middleware
----------------------------------

To assert session behaviour, populate ``scope["headers"]`` with a
``cookie`` header and inspect the response headers for the updated
``Set-Cookie`` value. Middleware can be tested by attaching it to your
app instance before issuing requests.

.. code-block:: python

   import httpx

   from micropie import App, HttpMiddleware

   class AddHeader(HttpMiddleware):
       async def before_request(self, request):
           return None

       async def after_request(self, request, status_code, response_body, extra_headers):
           extra_headers.append(("X-Test", "1"))
           return {"headers": extra_headers}

   class MyApp(App):
       async def index(self):
           return "hi"

   async def test_middleware_header():
       app = MyApp()
       app.middlewares.append(AddHeader())
       transport = httpx.ASGITransport(app=app)
       async with httpx.AsyncClient(transport=transport) as client:
           response = await client.get("http://test/")
       assert response.headers["x-test"] == "1"

Handling lifespan events
------------------------

If your application registers startup or shutdown handlers, wrap your
ASGI client in a lifespan manager. ``httpx`` exposes
:class:`httpx.ASGITransport` with a ``lifespan="auto"`` mode that will
run lifespan events before the first request and after the client exits
(on versions that support this option).

.. code-block:: python

   async with httpx.AsyncClient(
       transport=httpx.ASGITransport(app=app, lifespan="auto")
   ) as client:
       ...

Further reading
---------------

* Browse ``tests.py`` in the MicroPie source tree for additional
  patterns, including WebSocket testing helpers.
* The `httpx documentation <https://www.python-httpx.org/advanced/#calling-into-python-web-apps>`_
  has more on driving ASGI apps from tests.