docs: add websockets testing capabilities (#4040)

Author: euri10

docs/examples/testing/test_websocket.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from litestar import WebSocket, websocket
+from litestar.datastructures import State
+from litestar.testing import create_test_client
+
+
+def test_websocket() -> None:
+    @websocket(path="/ws")
+    async def websocket_handler(socket: WebSocket[Any, Any, State]) -> None:
+        await socket.accept()
+        recv = await socket.receive_json()
+        await socket.send_json({"message": recv})
+        await socket.close()
+
+    with create_test_client(route_handlers=[websocket_handler]).websocket_connect("/ws") as ws:
+        ws.send_json({"hello": "world"})
+        data = ws.receive_json()
+        assert data == {"message": {"hello": "world"}}

docs/usage/testing.rst

@@ -148,6 +148,17 @@ We would then be able to rewrite our test like so:
             :caption: tests/test_health_check.py
             :language: python
 
+Testing websockets
+++++++++++++++++++
+
+Litestar's test client enhances the httpx client to support websockets. To test a websocket endpoint, you can use the :meth:`websocket_connect <litestar.testing.TestClient.websocket_connect>`
+method on the test client. The method returns a websocket connection object that you can use to send and receive messages, see an example below for json:
+
+For more information, see also the :class:`WebSocket <litestar.connection.WebSocket>` class in the API documentation and the :ref:`websocket <usage/websockets:websockets>` documentation.
+
+    .. literalinclude:: /examples/testing/test_websocket.py
+        :language: python
+
 
 Using sessions
 ++++++++++++++