starlette 的 testclient 是专门用于测试 asgi 应用的轻量级客户端,它通过直接调用应用实例来模拟 http 请求,从而避免启动本地服务器。要使用它,只需将你的 asgi 应用实例传入 testclient 构造函数,然后像操作 requests 库一样发起 get、post 等请求并检查响应状态码和 json 数据。

如何初始化 TestClient 并发送基本请求
初始化 TestClient 时,必须传入一个实现了 ASGI 接口的应用对象,通常是 Starlette 的 Application 或 Router 实例。发送请求时,你可以指定路径、查询参数、JSON 负载以及自定义头部信息,客户端会返回一个包含 status_code、headers 和 json() 方法的响应对象。

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.testclient import TestClient
from starlette.routing import Route
async def homepage(request):
return JSONResponse({"message": "Hello World"})
routes = [Route("/", homepage)]
app = Starlette(routes=routes)
# 创建测试客户端
client = TestClient(app)
# 发送 GET 请求
response = client.get("/")
print(response.status_code) # 输出: 200
print(response.json()) # 输出: {'message': 'Hello World'}上述代码展示了最基础的用法。首先定义了一个简单的路由函数,然后将其注册到 Starlette 应用中。接着,TestClient(app) 建立了连接。调用 client.get("/") 后,我们直接访问了响应的属性。这种直接调用方式比使用 httpx 连接本地端口要快得多,因为它省去了网络 I/O 开销。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。
如何处理 POST 请求与表单数据
在处理需要提交数据的接口时,TestClient 支持通过 data 参数发送表单编码数据,或通过 json 参数发送 JSON 负载。对于 POST 请求,你需要确保应用端能正确解析这些输入,通常 Starlette 会自动处理 JSON 解析,而表单数据则需要通过 request.form() 获取。
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.testclient import TestClient
from starlette.routing import Route
import json
async def create_user(request):
if request.method == "POST":
# 尝试解析 JSON
try:
body = await request.json()
name = body.get("name")
except Exception:
# 如果失败,尝试解析表单
form = await request.form()
name = form.get("name")
return JSONResponse({"created": True, "user": name})
return JSONResponse({"error": "Method Not Allowed"}, status_code=405)
routes = [Route("/users", create_user, methods=["GET", "POST"])]
app = Starlette(routes=routes)
client = TestClient(app)
# 发送 JSON POST 请求
resp_json = client.post("/users", json={"name": "Alice"})
print(resp_json.json()) # {'created': True, 'user': 'Alice'}
# 发送表单 POST 请求
resp_form = client.post("/users", data={"name": "Bob"})
print(resp_form.json()) # {'created': True, 'user': 'Bob'}在这个例子中,create_user 函数同时兼容 JSON 和表单输入。client.post 方法接收 json 字典时会自动设置 Content-Type: application/json 头,而接收 data 字典时则默认为 application/x-www-form-urlencoded。测试时,我们可以分别验证这两种情况,确保后端逻辑的健壮性。注意,TestClient 会自动处理异步循环,因此无需在测试代码中手动管理事件循环。
当请求路径不存在时 TestClient 返回什么
当向未注册的路径发送请求时,Starlette 会触发 404 错误。此时 TestClient 不会抛出异常,而是返回一个状态码为 404 的响应对象。开发者可以通过检查 response.status_code 是否为 404 来验证路由缺失的情况,或者捕获 RuntimeError(如果在调试模式下且配置了特定的错误处理)。通常情况下,标准的 404 响应是预期的行为。
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.testclient import TestClient
from starlette.routing import Route
async def health_check(request):
return JSONResponse({"status": "ok"})
routes = [Route("/health", health_check)]
app = Starlette(routes=routes)
client = TestClient(app)
# 访问不存在的端点
response = client.get("/nonexistent")
print(response.status_code) # 输出: 404
print(response.text) # 输出: <!DOCTYPE html>... (默认 HTML 错误页)
# 如果启用了 debug 模式,可能会看到更详细的 traceback
# 但在生产配置或标准测试中,通常只关心 404 状态码在上述代码中,我们只注册了 /health 路由。当请求 /nonexistent 时,Starlette 的路由器无法匹配任何路径,因此返回默认的 404 响应。TestClient 忠实地反映了这一结果。在实际测试中,我们通常会断言 assert response.status_code == 404 来确保非法路径被正确拒绝。如果应用配置了自定义的错误页面,response.text 的内容也会相应改变,但状态码始终保持一致。

















