ci: add Linux KiCad real-pcbnew matrix

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tests/conftest.py

@@ -6,6 +6,7 @@ test module can trigger their import, preventing crashes on systems where the
 real KiCAD environment is not fully initialised for testing.
 """
 
+import os
 import sys
 import types
 from unittest.mock import MagicMock
@@ -16,12 +17,13 @@ from unittest.mock import MagicMock
 # attribute access (pcbnew.BOARD, pcbnew.PCB_TRACK, …) returns a mock
 # rather than raising AttributeError.
 # ---------------------------------------------------------------------------
-_pcbnew = MagicMock(name="pcbnew")
-_pcbnew.__file__ = "/fake/pcbnew.cpython-313-x86_64-linux-gnu.so"
-_pcbnew.__name__ = "pcbnew"
-_pcbnew.__spec__ = None
-_pcbnew.GetBuildVersion.return_value = "9.0.0-stub"
-sys.modules["pcbnew"] = _pcbnew
+if os.environ.get("KICAD_USE_REAL_PCBNEW") != "1":
+    _pcbnew = MagicMock(name="pcbnew")
+    _pcbnew.__file__ = "/fake/pcbnew.cpython-313-x86_64-linux-gnu.so"
+    _pcbnew.__name__ = "pcbnew"
+    _pcbnew.__spec__ = None
+    _pcbnew.GetBuildVersion.return_value = "9.0.0-stub"
+    sys.modules["pcbnew"] = _pcbnew
 
 # ---------------------------------------------------------------------------
 # Stub: skip  (kicad-skip — use real module if available, stub otherwise)

tests/test_real_pcbnew_matrix.py

@@ -0,0 +1,43 @@
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+PYTHON_DIR = Path(__file__).parent.parent / "python"
+sys.path.insert(0, str(PYTHON_DIR))
+
+pytestmark = [
+    pytest.mark.integration,
+    pytest.mark.real_pcbnew,
+    pytest.mark.linux,
+]
+
+
+@pytest.fixture(autouse=True)
+def require_real_pcbnew() -> None:
+    if os.environ.get("KICAD_USE_REAL_PCBNEW") != "1":
+        pytest.skip("real pcbnew smoke tests require KICAD_USE_REAL_PCBNEW=1")
+
+
+def test_project_commands_create_and_load_board_with_real_pcbnew(tmp_path: Path) -> None:
+    import pcbnew
+
+    from commands.project import ProjectCommands
+
+    version = pcbnew.GetBuildVersion()
+    assert version
+    assert not str(version).endswith("-stub")
+
+    commands = ProjectCommands()
+    result = commands.create_project({"name": "matrix_smoke", "path": str(tmp_path)})
+
+    assert result["success"] is True, result
+
+    board_path = Path(result["project"]["boardPath"])
+    assert board_path.exists()
+
+    board = pcbnew.LoadBoard(str(board_path))
+    assert board is not None
+    assert hasattr(board, "GetFileName")
+    assert board.GetFileName().endswith(".kicad_pcb")