Skip to content

Testing Guide - kicad-mcp-pro

Overview

kicad-mcp-pro uses pytest with the uv toolchain. Tests are organised into three layers:

Layer Path Description
Unit tests/unit/ Pure Python, no KiCad dependency
Integration tests/integration/ Requires kicad-cli in PATH
Smoke tests/smoke/ End-to-end MCP protocol over stdio

Running Tests Locally

# Install all extras (includes test deps)
uv sync --all-extras --frozen

# Unit tests only (fast, no KiCad needed)
uv run pytest tests/unit/ -v

# Full suite (requires KiCad installed)
uv run pytest -v

# With coverage
uv run pytest --cov=kicad_mcp_pro --cov-report=term-missing

If uv run exits before Python starts with a required-version mismatch, compare uv --version with uv.toml. Source checkouts pin the supported uv version so local and CI dependency resolution match. Run kicad-mcp-pro doctor --json for an explicit uv_version diagnostic, then switch to the repo-compatible version, for example uv self update 0.10.8 when uv.toml requires 0.10.8.

CI Matrix

CI runs in the canonical oaslananka/kicad-mcp GitHub repository on GitHub-hosted runners. Python 3.13 is the required PR/push lane for the MCP server, and package publishing uses the release workflows documented in docs/publishing.md.

Fixtures

KiCad project fixtures live in tests/fixtures/. See docs/development/contributing-fixtures.md for how to add new ones. Convention: one directory per test scenario, named <scenario>/.

Mutation Testing

Mutation tests run weekly via .github/workflows/mutation.yml using mutmut. Check the Actions tab for the latest mutation score. Target is >= 70% survived mutations caught.

Mocking Strategy

  • conftest.py root: common fixtures (temp dirs, fake KiCad stubs)
  • KiCad CLI is mocked via unittest.mock.patch in unit tests
  • Integration tests spin up a real kicad-cli process (Linux CI only)

Adding a Test

  1. Pick the correct layer (unit if no KiCad needed).
  2. Create tests/<layer>/test_<module>.py.
  3. Follow Arrange-Act-Assert pattern.
  4. Run uv run pytest tests/<layer>/test_<module>.py -v locally.
  5. Ensure uv run ruff check tests/ passes.