pytest-localserver 专为单元测试设计，通过封装 http.server 实现自动端口分配、启停管理与多线程安全，支持真实 TCP 连接以验证网络行为（如 DNS、代理、超时），但不适用于生产环境，也不支持 HTTPS、WebSocket 或高并发。
pytest-localserver 不能直接用于生产环境 Mock，它只适合单元测试中模拟 HTTP 服务，且默认不支持 HTTPS、WebSocket 或并发高负载场景。
为什么选 pytest-localserver 而不是 Flask + threading？
它封装了 http.server，自动处理端口占用、生命周期（启动/关闭）、多线程安全，避免你手动调用 server.serve_forever() 阻塞主线程。尤其在 pytest 中，它能配合 fixture 自动启停，不用写 try/finally 清理逻辑。
- 默认绑定
127.0.0.1，不对外网暴露，安全性比手起 Flask 更可控 - 支持
HTTPServer（返回静态响应）和SMTPServer（发信模拟），但不支持动态路由匹配（比如/api/users/） - 若需路径级定制，得继承
http.server.BaseHTTPRequestHandler并重写do_GET/do_POST，而不是靠装饰器或路由表
快速启动一个返回 JSON 的 Mock 服务
用 httpserver fixture 最省事：它会在测试函数执行前自动启动服务器，结束后自动 shutdown。返回内容必须是 bytes，别直接 return dict。
import json
<p>def test_api_call(httpserver):</p><div class="aritcle_card flexRow artxards">
<div class="artcardd flexRow">
<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill11526" title="Python Hardener"><img
src="https://img.php.cn/upload/skill/001/246/273/6adaf20dbae7c507.jpg" alt="Python Hardener" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a rel="nofollow" href="/xiazai/skill11526" title="Python Hardener" class="overflowclass">Python Hardener</a>
<p class="overflowclass">通过完整的安全审查、代码整洁重构、健壮的错误处理、正确的日志记录以及完整的文档字符串覆盖，强化 Python 脚本。</p>
</div>
<a rel="nofollow" href="/xiazai/skill11526" title="Python Hardener" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
</a>
</div>
</div><h1>构造响应体</h1><pre class="brush:python;toolbar:false;">response_data = {"status": "ok", "data": [1, 2, 3]}
httpserver.expect_request("/health").respond_with_json(response_data)
# 此时 httpserver.url 就是运行中的地址，如 'http://127.0.0.1:56789'
import requests
r = requests.get(httpserver.url + "/health")
assert r.json() == response_data
-
expect_request()是关键：它注册一个期望路径，未命中会抛AssertionError，帮你发现请求没发对 - 不调用
expect_request()直接访问，服务会返回 404 —— 它不是“兜底响应”，而是“契约式 Mock” - 同一个路径可多次调用
respond_with_json()，但每次 expect 是独立的；若要模拟多次调用不同响应，得用times=参数或分多次 expect
遇到 ConnectionRefusedError 怎么办？
常见于端口被占或 server 未真正启动。pytest-localserver 默认随机端口，但如果你硬编码了 port=8000，而本地已有进程占着，就会失败。
- 检查是否重复运行了测试：pytest 默认并行时，多个
httpserverfixture 可能抢同一端口，加--workers=1或改用httpserver_ssl（虽不启用 SSL，但底层换用不同端口分配策略） - 确认没在测试里手动调用了
httpserver.stop()—— 这会导致后续请求失败，fixture 的自动管理就失效了 - Windows 上偶尔因防火墙拦截新端口，可临时关掉或添加例外规则，目标端口范围通常是 50000–60000
它和 responses / httpx.MockTransport 比有什么不可替代性？
responses 是纯客户端拦截，不走网络栈；httpx.MockTransport 也是内存级 mock。而 pytest-localserver 真实监听 socket，能测 DNS 解析、代理配置、超时重试、SSL 握手失败等真实网络行为。
- 当你需要验证代码是否真的发出了
POST /login，且 header 带了Authorization: Bearer xxx，用httpserver可以在 handler 里打印self.headers和self.rfile.read()查看原始字节流 - 它无法 mock 302 重定向链或 chunked transfer encoding 的流式响应 —— 这些得自己在 handler 里拼
send_response()和send_header()，远不如httpx的 transport mock 灵活 - 如果项目已用
httpx，优先考虑httpx.MockTransport；只有当必须走真实 TCP 连接时，才值得引入pytest-localserver
真实网络环境的边界情况太多，比如连接池复用、keep-alive 超时、DNS 缓存失效——这些 mock 工具都只能覆盖一部分。选哪个，取决于你这次想验证的是「业务逻辑」还是「集成行为」。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
