Rooba
/
starlette
mirror of https://github.com/encode/starlette.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity
starlette/docs/test_client.md

98 lines
3.2 KiB
Markdown
Raw Normal View History

Initial conversion of README.md to mkdocs
2018-08-28 13:58:03 +00:00
The test client allows you to make requests against your ASGI application,
using the `requests` library.
```python
Update test_client doc from README.md
2018-08-28 14:18:17 +00:00
from starlette.response import HTMLResponse
from starlette.testclient import TestClient
Initial conversion of README.md to mkdocs
2018-08-28 13:58:03 +00:00
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.
Exception handling (#54) * Exception handling * Black formatting * Add exception handling to App * Handle cases where exception raised but response already started * Order exception handler lookup by class inheritance * Handle 404/405 as responses without App, or exceptions with it. * Only use TestClient(app, raise_exceptions=False) explicitly inside test cases * Documentation for ExceptionMiddleware * Drop error_handler/exception_handler distinction. * Finesse and document TestClient(app, raise_server_exceptions=False) * Refactoring to make debug responses easier to obtain from elsewhere in code * Use named status_code argument in example * Clean up raise_server_errors usage in tests * Consistent title-casing in HTTP reason phrases * Black formatting * Add WebSocketClose close. Omit message-body on 204, 304 exception cases. * Black formatting * Add 'debug' flag to App and ExceptionMiddleware * Support app.debug * Document debug mode * Documenting debug
2018-09-04 10:52:29 +00:00
You can use any of `requests` standard API, such as authentication, session
cookies handling, or file uploads.
Initial conversion of README.md to mkdocs
2018-08-28 13:58:03 +00:00
Exception handling (#54) * Exception handling * Black formatting * Add exception handling to App * Handle cases where exception raised but response already started * Order exception handler lookup by class inheritance * Handle 404/405 as responses without App, or exceptions with it. * Only use TestClient(app, raise_exceptions=False) explicitly inside test cases * Documentation for ExceptionMiddleware * Drop error_handler/exception_handler distinction. * Finesse and document TestClient(app, raise_server_exceptions=False) * Refactoring to make debug responses easier to obtain from elsewhere in code * Use named status_code argument in example * Clean up raise_server_errors usage in tests * Consistent title-casing in HTTP reason phrases * Black formatting * Add WebSocketClose close. Omit message-body on 204, 304 exception cases. * Black formatting * Add 'debug' flag to App and ExceptionMiddleware * Support app.debug * Document debug mode * Documenting debug
2018-09-04 10:52:29 +00:00
By default the `TestClient` will raise any exceptions that occur in the
application. Occasionally you might want to test the content of 500 error
responses, rather than allowing client to raise the server exception. In this
case you should use `client = TestClient(app, raise_server_exceptions=False)`.
### Testing WebSocket sessions
You can also test websocket sessions with the test client.
Initial conversion of README.md to mkdocs
2018-08-28 13:58:03 +00:00
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)
Update test_client doc from README.md
2018-08-28 14:18:17 +00:00
with client.websocket_connect('/') as session:
Initial conversion of README.md to mkdocs
2018-08-28 13:58:03 +00:00
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
Update test_client doc from README.md
2018-08-28 14:18:17 +00:00
* `.websocket_connect(url, subprotocols=None, **options)` - Takes the same set of arguments as `requests.get()`.
Initial conversion of README.md to mkdocs
2018-08-28 13:58:03 +00:00
May raise `starlette.websockets.Disconnect` if the application does not accept the websocket connection.
Update test_client doc from README.md
2018-08-28 14:18:17 +00:00
#### Sending data
* `.send_text(data)` - Send the given text to the application.
* `.send_bytes(data)` - Send the given bytes to the application.
* `.send_json(data)` - Send the given data to the application.
Initial conversion of README.md to mkdocs
2018-08-28 13:58:03 +00:00
#### 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.