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/<id></id>） - 若需路径级定制，得继承
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">
<div class="artcardd flexRow">
<a class="aritcle_card_img" href="/xiazai/skill11526" title="Python Hardener"><img
src="https://img.php.cn/upload/skill/001/246/273/6adaf20dbae7c507.jpg" alt="Python Hardener" ></a>
<div class="aritcle_card_info flexColumn">
<a href="/xiazai/skill11526" title="Python Hardener">Python Hardener</a>
<p>通过完整的安全审查、代码整洁重构、健壮的错误处理、正确的日志记录以及完整的文档字符串覆盖，强化 Python 脚本。</p>
</div>
<a href="/xiazai/skill11526" title="Python Hardener" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a>
</div>
</div><p><span>立即学习</span>“<a href="https://pan.quark.cn/s/00968c3c2c15" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">Python免费学习笔记（深入）</a>”；</p><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 工具都只能覆盖一部分。选哪个，取决于你这次想验证的是「业务逻辑」还是「集成行为」。
