Repository: encode/starlette
Pull request: Add more TestClient examples
Fixes #1677 

Problem statement:
Document how to send files using `TestClient`
Currently, people need to rely on lost issues to understand how to send files using the `TestClient`. I guess we'd want to document how to do that. Even adding a reference to `requests` would be already helpful here.

Hints from issue discussion:

Commit message: add multiple files example

Patch to review:
diff --git a/docs/testclient.md b/docs/testclient.md
index a214715fe..a3963f9b8 100644
--- a/docs/testclient.md
+++ b/docs/testclient.md
@@ -26,6 +26,35 @@ function calls, not awaitables.
 You can use any of `requests` standard API, such as authentication, session
 cookies handling, or file uploads.
 
+For example, to set headers on the TestClient you can do:
+
+```python
+client = TestClient(app)
+
+# Set headers on the client for future requests
+client.headers = {"Authorization": "..."}
+response = client.get("/")
+
+# Set headers for each request separately
+response = client.get("/", headers={"Authorization": "..."})
+```
+
+And for example to send files with the TestClient:
+
+```python
+client = TestClient(app)
+
+# Send a single file
+files = {"file": open("example.txt", "rb")}
+response = client.post("/form", files=files)
+
+# Send multiple files
+files = {"file1": open("example.txt", "rb"), "file2": open("example.png", "rb")}
+response = client.post("/form", files=files)
+```
+
+For more information you can view `requests.Session` [docs](https://requests.readthedocs.io/en/master/user/advanced/) and [API](https://requests.readthedocs.io/en/master/api/#requests.Session).
+
 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


Code review comments:
diff_hunk: @@ -26,6 +26,35 @@ function calls, not awaitables.
 You can use any of `requests` standard API, such as authentication, session
 cookies handling, or file uploads.
 
+For example, to set headers on the TestClient you can do:
+
+```python
+client = TestClient(app)
+
+# Set headers on the client for future requests
+client.headers = {"Authorization": "..."}
+response = client.get("/")
+
+# Set headers for each request separately
+response = client.get("/", headers={"Authorization": "..."})
+```
+
+And for example to send files with the TestClient:
+
+```python
+client = TestClient(app)
+
+# Send a single file
+files = {"file": open("example.txt", "rb")}
+response = client.post("/form", files=files)
+
+# Send multiple files
+files = {"file1": open("example.txt", "rb"), "file2": open("example.png", "rb")}
+response = client.post("/form", files=files)
path: docs/testclient.md
text: @user1:
With `open()` like this, pytest will warn about unclosed resources, if we set to raise errors on warnings. 🤔

Also, I wrote this comment years ago, which kind of mismatch the written here: https://github.com/tiangolo/fastapi/issues/1536#issuecomment-640781718

@author:
Yeah that's a good point, but we also have this case in Starlette `test_staticfiles.py` which pytest warns about this. But I agree it's better to use the contextt manager. Let me update..

@author:
I think this should be ok now, thank you Marcelo.