1500+测试守护每一块PCB：KiCAD MCP Server测试体系与CI质量门实战内幕-平芜编程栈

1500+测试守护每一块PCB：KiCAD MCP Server测试体系与CI质量门实战内幕

【免费下载链接】KiCAD-MCP-ServerKiCAD MCP is a Model Context Protocol (MCP) implementation that enables Large Language Models (LLMs) like Claude to directly interact with KiCAD for printed circuit board design.项目地址: https://gitcode.com/gh_mirrors/ki/KiCAD-MCP-Server

KiCAD MCP Server 是一个 Model Context Protocol（MCP）服务器，让 Claude 等大语言模型能直接操作 KiCAD 完成原理图绘制、PCB 布局布线等设计工作。当 AI 开始"动手画板子"，一个关键问题来了：怎么保证它每一步操作都是可靠的？本文带你走进 KiCAD MCP Server 的测试体系与 CI 质量门，看看 1500+ 个测试是如何守护每一块 PCB 的。

为什么 AI 驱动 PCB 设计需要"测试安全网" 🛡️

让 AI 改原理图、挪焊盘，出错的代价不是"页面刷新一下"，而是可能报废一块板子。KiCAD MCP Server 的应对思路是：每个 MCP 工具（加元件、连导线、自动布线……）背后都有对应的回归测试，任何一处行为回归都会立刻被拦下。

测试全景：约 2400 个用例覆盖三大语言层

测试资产主要集中在两个目录：

目录	技术栈	规模
tests/	Python（pytest）	169 个测试文件，2300+ 测试函数
tests-ts/	TypeScript（vitest）	11 个测试文件，约 110 个用例

测试用例都验证什么？

翻看 tests/ 目录名就能感受到覆盖面之广：

AI 操作链路：如 test_wire_dragger_orthogonality.py（拖线正交性）、test_net_label_pin_snapping.py（网络标签吸附引脚）、test_autoroute_best_of_n.py（自动布线择优）；
跨版本兼容：如 test_ipc_kicad10_footprint_load.py（KiCad 10 封装加载）、test_kicad10_config_dirs.py；
平台适配：如 test_cairo_dll_preload_windows.py（Windows 动态库预加载）、test_seven_zip_resolver.py；
工程质量元测试：如 readme-counts.test.ts、no-stale-tool-references.test.ts，连"README 里的工具数量对不对"都有测试盯着。

用 Markers 给测试分层

pytest.ini 中定义了一套 marker 体系，让不同深度的测试可以按需执行：

markers = unit: Unit tests (fast, no external dependencies) integration: Integration tests (requires KiCAD) real_pcbnew: Headless tests that exercise real KiCad SWIG bindings slow: Slow-running tests linux: Linux-specific tests windows: Windows-specific tests macos: macOS-specific tests

同时 pytest.ini 默认开启分支覆盖率（--cov-branch）并输出 HTML/XML 报告，覆盖率数据会上传到 Codecov 持续追踪。

CI 矩阵：一次提交要闯几道关？

所有质量规则集中在 .github/workflows/ci.yml。一次 push 或 Pull Request 会触发以下并行任务：

1️⃣ TypeScript 任务：3 个操作系统 × 2 个 Node 版本

在ubuntu-24.04 / ubuntu-22.04 / windows-latest / macos-latest× Node.js20.x / 22.x的矩阵上依次执行npm ci→npm run build→npm run lint:ts→npm run test:ts（即 package.json 中定义的 vitest）。

2️⃣ Python 任务：4 个解释器版本交叉验证

在3.9 / 3.10 / 3.11 / 3.12四个 Python 版本上运行完整 pytest 套件，覆盖率只在 3.12 + ubuntu-24.04 这一格上传，避免重复。

3️⃣ 集成任务：真刀真枪装 3 个 KiCad 版本

这是含金量最高的一关：CI 会从官方 PPA 依次安装KiCad 8.0、9.0、10.0，自动探测pcbnewPython 绑定路径，然后运行 test_real_pcbnew_matrix.py 中的integration + real_pcbnew测试——用真实的 KiCad SWIG 绑定做冒烟验证，确保跨 KiCad 大版本的行为一致。

4️⃣ 质量门与文档门

Code Quality 任务：运行 pre-commit 全量钩子（Black、isort、Prettier、flake8、mypy、ESLint），是整个仓库唯一的格式化/Lint 权威门禁；
docs-check 任务：校验所有 JSON 文件可解析；
ci-passed 聚合任务：ci.yml末尾的ci-passedjob 要求上面所有任务全部 success才算通过，并作为分支保护规则绑定的唯一状态检查——任何一路挂了，PR 都别想合并。

发布流程的质量门则记录在 docs/RELEASING.md，由 .github/workflows/release.yml 执行。

干货：注释里藏着的"踩坑实录" 🕵️

ci.yml 的注释是这个项目最值钱的部分之一，它诚实地记录了几次"假门禁"翻车：

|| echo吞错误：早期 Lint 步骤写成npx eslint src/ || echo "ok"，检查失败也报成功。后来把 Lint 收敛为真实门禁，|| echo式"自欺"全部清除；
测试套件"假运行"：曾有pytest python/指向源码目录，覆盖了 pytest.ini 的testpaths = tests，结果 CI 只跑了 7 个游离测试，真正的 1500+ 套件根本没执行。修复方式是裸跑pytest，让配置生效；
文档漂移：docs/TOOL_INVENTORY.md由 scripts/generate-tool-inventory.mjs 从工具注册表生成，曾漂移到"文档 138 个工具 vs 实际注册 229 个"。现在npm run docs:tools:check成为构建后的强制检查；
环境依赖坑：freerouting 自动布线测试会解析java可执行文件，CI 特意加装 Temurin JRE 21，避免"纯环境问题导致的假失败"；
格式化确定性：Black/MyPy 检查只在固定版本（3.12 + ubuntu-24.04）跑一次，因为 pip 在不同解释器上会解析到不同版本的 linter——"门禁必须是确定的"。