KiCadIPCTest — Test Suite for KiCad IPC Operations

A modular, configurable test suite for the KiCad IPC Python interface (kipy library, KiCad 9/10). Designed primarily as a verification framework for the KiCadSpoke project (GitHub). Licensed under the GNU General Public License v3.0.

---

Table of Contents

• Requirements
• Installation
• Quick Start
• Project Structure
• Documentation
• Architecture Review
• License

---

Requirements

• KiCad 9 or 10 — GUI must be running with a PCB file open (IPC works only with the active PCB editor)
• kipy library — the official Python IPC wrapper for KiCad (repository)
• Python 3.8+

---

Installation

pip install -r requirements.txt

The requirements.txt file lists the exact kipy version and any other dependencies.

---

Quick Start

1. Launch KiCad, open a PCB file in the PCB Editor.
2. Run all enabled tests (requires a configured board profile in config/test_config.yaml):

python -m runner.run --config config/test_config.yaml --board 10CL006

3. Run a specific suite:

python -m runner.run --config config/test_config.yaml --board 10CL006 --suite safe

4. Run a single test:

python -m runner.run --config config/test_config.yaml --test smoke_footprints

5. Run a dangerous test (must be explicitly enabled in config):

python -m runner.run --config config/test_config.yaml --board 10CL006 --test decap_create_one_via

Safety note: Dangerous tests (dangerous: true) do not run unless explicitly enabled with enabled: true in the YAML config, even if invoked by --test.

---

Project Structure

├── config/                  # YAML configuration files
│   ├── test_config.yaml     # Main test configuration
│   └── 10CL006.yaml         # Board-specific profile
├── core_api/                # Thin wrapper over kipy (type-safe, documented)
│   ├── board.py             # Transactions, commits, board metadata
│   ├── fields.py            # Custom component field reading
│   ├── footprints.py        # Component search, read, modify
│   ├── geometry.py          # Coordinate conversion utilities
│   ├── kicad_client.py      # Connection & session management
│   ├── nets.py              # Net reading
│   ├── pads.py              # Pad reading
│   ├── project.py           # Project & schematic paths
│   ├── selection.py         # Selection analysis
│   ├── tracks.py            # Track reading & creation
│   ├── vias.py              # Via reading, creation, deletion
│   └── zones.py             # Zone reading
├── runner/                  # Test execution system
│   ├── config_schema.py     # YAML config loading & validation
│   ├── logging_setup.py     # Centralized logging
│   ├── registry.py          # @register decorator & test registry
│   ├── run.py               # CLI entry point & SharedConnection
│   └── step_helper.py       # Unified step logging
├── tests/                   # Test suites
│   ├── toy/                 # Dummy tests (runner validation)
│   ├── static/              # Static contract checks (no KiCad needed)
│   ├── safe/                # Read-only diagnostics
│   ├── smoke/               # Smoke tests for core_api modules
│   ├── mutating/            # Regression tests (dangerous)
│   └── decap_tools/         # Capacitor/via utilities (dangerous)
├── docs/                    # Detailed documentation
│   ├── architecture_review.md
│   ├── runner.md
│   ├── core_api.md
│   ├── test_suites.md
│   └── ..._ru.md            # Russian-language versions
├── test_boards/             # Reference test boards
└── requirements.txt

---

Documentation

Detailed documentation has been moved to the docs/ directory:

Document	English	Russian
Runner — test execution system, configuration, registry, CLI	docs/runner.md	docs/runner_ru.md
Core API — core_api module reference (all 12 modules)	docs/core_api.md	docs/core_api_ru.md
Test Suites — detailed descriptions of all 6 test suites	docs/test_suites.md	docs/test_suites_ru.md
Architecture Review — identified issues and improvement suggestions	docs/architecture_review.md	—
Crash Diagnostics — first-write crash (#24966) reproduction & context	docs/diagnose_first_write_crash.md	docs/diagnose_first_write_crash_ru.md

Quick Reference

• Runner docs — how to configure YAML, register new tests, connection management, CLI options
• Core API docs — complete API reference for all 12 modules: board, fields, footprints, geometry, kicad_client, nets, pads, project, selection, tracks, vias, zones
• Test Suites docs — detailed descriptions of each test in toy, static, safe, smoke, mutating, and decap_tools suites

---

Architecture Review

See docs/architecture_review.md for the full architecture review, including:

• Missing Track API (resolved — see core_api/tracks.py)
• Missing Custom Field API (resolved — see core_api/fields.py)
• Missing Via listing API (resolved — see core_api/vias.py)
• Other identified issues and recommendations

---

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.