mirror of https://github.com/encode/starlette.git
87 lines
2.7 KiB
Markdown
87 lines
2.7 KiB
Markdown
|
|
||
|
|
The test client allows you to make requests against your ASGI application,
|
||
|
|
using the `requests` library.
|
||
|
|
|
||
|
|
```python
|
||
|
|
from starlette import HTMLResponse, TestClient
|
||
|
|
|
||
|
|
|
||
|
|
class App:
|
||
|
|
def __init__(self, scope):
|
||
|
|
self.scope = scope
|
||
|
|
|
||
|
|
async def __call__(self, receive, send):
|
||
|
|
response = HTMLResponse('<html><body>Hello, world!</body></html>')
|
||
|
|
await response(receive, send)
|
||
|
|
|
||
|
|
|
||
|
|
def test_app():
|
||
|
|
client = TestClient(App)
|
||
|
|
response = client.get('/')
|
||
|
|
assert response.status_code == 200
|
||
|
|
```
|
||
|
|
|
||
|
|
The test client exposes the same interface as any other `requests` session.
|
||
|
|
In particular, note that the calls to make a request are just standard
|
||
|
|
function calls, not awaitables.
|
||
|
|
|
||
|
|
### Testing WebSocket applications
|
||
|
|
|
||
|
|
You can also test websocket applications with the test client.
|
||
|
|
|
||
|
|
The `requests` library will be used to build the initial handshake, meaning you
|
||
|
|
can use the same authentication options and other headers between both http and
|
||
|
|
websocket testing.
|
||
|
|
|
||
|
|
```python
|
||
|
|
from starlette.testclient import TestClient
|
||
|
|
from starlette.websockets import WebSocketSession
|
||
|
|
|
||
|
|
|
||
|
|
class App:
|
||
|
|
def __init__(self, scope):
|
||
|
|
self.scope = scope
|
||
|
|
|
||
|
|
async def __call__(self, receive, send):
|
||
|
|
session = WebSocketSession(self.scope, receive=receive, send=send)
|
||
|
|
await session.accept()
|
||
|
|
await session.send_text('Hello, world!')
|
||
|
|
await session.close()
|
||
|
|
|
||
|
|
|
||
|
|
def test_app():
|
||
|
|
client = TestClient(App)
|
||
|
|
with client.wsconnect('/') as session:
|
||
|
|
data = session.receive_text()
|
||
|
|
assert data == 'Hello, world!'
|
||
|
|
```
|
||
|
|
|
||
|
|
The operations on session are standard function calls, not awaitables.
|
||
|
|
|
||
|
|
It's important to use the session within a context-managed `with` block. This
|
||
|
|
ensure that the background thread on which the ASGI application is properly
|
||
|
|
terminated, and that any exceptions that occur within the application are
|
||
|
|
always raised by the test client.
|
||
|
|
|
||
|
|
#### Establishing a test session
|
||
|
|
|
||
|
|
* `.wsconnect(url, subprotocols=None, **options)` - Takes the same set of arguments as `requests.get()`.
|
||
|
|
|
||
|
|
May raise `starlette.websockets.Disconnect` if the application does not accept the websocket connection.
|
||
|
|
|
||
|
|
#### Receiving data
|
||
|
|
|
||
|
|
* `.receive_text()` - Wait for incoming text sent by the application and return it.
|
||
|
|
* `.receive_bytes()` - Wait for incoming bytestring sent by the application and return it.
|
||
|
|
* `.receive_json()` - Wait for incoming json data sent by the application and return it.
|
||
|
|
|
||
|
|
May raise `starlette.websockets.Disconnect`.
|
||
|
|
|
||
|
|
#### Closing the connection
|
||
|
|
|
||
|
|
* `.close(code=1000)` - Perform a client-side close of the websocket connection.
|
||
|
|
|
||
|
|
|
||
|
|
<p align="center">— ⭐️ —</p>
|
||
|
|
<p align="center"><i>Starlette is <a href="https://github.com/tomchristie/starlette/blob/master/LICENSE.md">BSD licensed</a> code. Designed & built in Brighton, England.</i></p>
|