notebooklm-py 如何运行本地故障注入 harness 做无账号的确定性回归测试？-创锋一号

notebooklm-py 如何运行本地故障注入 harness 做无账号的确定性回归测试？

【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLM's features—including capabilities the web UI doesn't expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py

如果你在 notebooklm-py 仓库中改动了重试策略、认证刷新、上传/下载管线或生命周期代码，想在不登录 NotebookLM 账号、不录制 cassette 的情况下验证这些改动是否引入了回归，可以使用仓库内置的本地故障注入 harness。它让生产客户端走真实的 loopback socket，由本地 HTTP 和 gRPC 故障服务按脚本注入确定性故障，并在服务端记录请求、提交和清理证据。权威指南是 docs/fault-injection.md，架构决策在 ADR-0038。

前提条件

harness 的辅助代码是 source-only（不随安装包分发），压测运行器 scripts/stress_fault_server.py 直接从源码树导入tests._fault_server，所以必须在一个源码检出目录里运行，并安装开发依赖：

uv sync --frozen --extra browser --extra dev --extra markdown \ --extra android --extra mcp --extra server

不需要任何账号凭证，也不请求上游服务；pytest 用例带allow_no_vcr，因为流量全部走本地 socket，无需 cassette 录制。

主路径：运行 socket 故障回归

在源码根目录执行：

uv run pytest tests/integration/faults -q

这个目录下是全部 socket 回归测试（Web/Android 场景、curl 故障、一致性探针、协议上限等），见 tests/integration/faults。其中较慢的进程死亡（process-death）用例族有自己的 CI 通道，可以单独分开运行：

uv run pytest tests/integration/faults/test_process_death.py -q

进程死亡用例会启动父进程托管的子进程并在观察到的边界上 kill 掉，运行时间明显更长，因此日常回归可以先跑主目录、按需再跑这一族。

用 stress 运行器执行完整场景牌

pytest 之外，压测运行器可以从同一套场景注册表调度并发的场景 cohort。先查看当前注册的场景清单：

uv run python scripts/stress_fault_server.py --list-scenarios

然后运行完整的可移植 deck（文档给出的示例参数）：

uv run python scripts/stress_fault_server.py \ --backend both --seed 42 --iterations 400 --concurrency 4 \ --require-all-scenarios --timeout 120 --scenario-timeout 15 \ --json-report /tmp/fault-stress-report.json

参数含义（以 docs/fault-injection.md 和运行器源码为准）：

--backend接受web、android、both；每个 iteration 独占一个客户端和它的本地服务。
--concurrency限制的是同时活跃的 cohort 数，而不是单个 RPC 数。
--seed对同一注册表和同一版本可以复现场景分配，但无法复现操作系统调度与时序；换注册表或改代码后不要期望旧 seed 逐位复现。
--require-all-scenarios会拒绝任何没有把选中的每个 case 至少执行一次的运行。
--json-report指定诊断报告输出位置，示例中的/tmp/fault-stress-report.json可以换成你自己的路径。
运行器的参数上限：--iterations1–100000，--concurrency1–64。
每个场景的 watchdog 是 15 秒，清理有独立的 5 秒 watchdog；场景内的 RPC/操作/传输截止时间必须先于该边界过期。

运行器的退出码：0 表示全部 cohort 通过；1 表示有失败或超时；2 表示参数错误。

可选分支：真实 curl 通道

如果还要验证 TLS 校验和逻辑路由在真实 curl 处理上的行为，走单独的 curl 通道。它需要额外的impersonate依赖，且只支持 Web 后端（--transport curl_cffi要求--backend web）：

uv sync --frozen --extra browser --extra dev --extra markdown \ --extra impersonate uv run python scripts/stress_fault_server.py \ --backend web --transport curl_cffi --seed 42 --iterations 40 \ --concurrency 2 --require-all-scenarios \ --json-report /tmp/curl-fault-report.json

注意：请求了 curl 通道但其依赖不可用时该运行会直接失败。报告会把 selected（选中）、executed（执行）、skipped（跳过）的 case 分开列出。

如何确认一次运行是成功的

退出码为 0，且没有失败/超时的 cohort；
--require-all-scenarios未被触发（即每个选中 case 都至少执行一次）；
--json-report产出的 JSON 中 selected/executed/skipped 与预期牌面一致。

文档记录的注册规模是202 个可移植 case（128 Web + 74 Android）加 10 个独立 real-curl case；另有仅走 pytest 通道的 3 个 auth-persistence、3 个 process-death 和 8 个 stored-auth MCP 传输 case，不计入可移植压测牌。文档给出的本机测量（macOS arm64 / Python 3.12.12，seed 42、concurrency 4）为：400/400 个可移植 cohort 用时 15.75 秒、零跳过；real-curl 40/40 个 cohort 用时 2.38 秒。这只是文档中的本机参考值，不是其他机器上必须达到的固定耗时，也不能替代 CI 平台矩阵。

失败时从哪里查

docs/fault-injection.md 给出的排查顺序是：

先看该操作的 plan（后端/传输、入口、fixture 与故障标签、预算、必需检查清单），再看失败或被遗漏的 check；
对比服务端的 commit 状态与客户端观察到的异常，再判断重试是否安全——本地服务能区分“被拒绝的写”和“已提交但响应丢失的写”；
用同一 revision、seed、选择和负载重跑，而不是反复随机重跑；
把时序类失败收敛到显式 gate；重复随机重跑不被视为修复手段。

报告是 secret-safe 的：只包含生成标签、布尔值、计数、摘要、路由标签和不透明的 fixture ID，不含原始 cookie/bearer、完整 URL 或 traceback。

适用边界

本地 harness 不是完整上游模拟器：它覆盖受控的协议与 socket 行为（重试、认证代际、部分传输、响应丢失、已提交写、取消、截止时间、共享工作、close/reopen 等）；
与真实服务一致性的权威证据仍然是录制的 cassette 和 live 测试；
浏览器登录、真实令牌签发、DNS 故障、内核丢包和 fixture 之外的上游行为不在其声明范围内。

下一步：新增或扩展场景

如果你要给自己的改动加场景，文档给出的六步是：选一个代表性的公共 API 或第一方工作流并复用真实 decoder fixture；在首次 await 前捕获构造依赖，显式路由每个逻辑 host 并证明遗漏目标会 fail closed；在分配资源前记录 plan 和精确的必需检查；断言公共结果加上独立的请求/体/凭证代际/提交证据；在finally中释放所有 gate 并落一条脱敏的 cleanup 事件；把场景注册到对应兄弟模块，先跑聚焦集成用例，再放进完整并发 deck 运行。各家族的场景归属（如 R3 上传、R5 产物发布、R6 流式 chat、R13 连接与 curl）见 tests/_fault_server 下的模块清单。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析