Merge pull request #19 from axiomantic/elijahr/subprocess-plugin

Migrate subprocess mocks to bigfoot and address Gemini feedback

Author: elijahr

.github/workflows/test-install-libclang.yml

@@ -22,7 +22,7 @@ jobs:
       - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
         with:
-          python-version: "3.10"
+          python-version: "3.11"
           cache: 'pip'
 
       - name: Install package

.github/workflows/test.yml

@@ -10,7 +10,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
         os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
       - uses: actions/checkout@v6

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- Test suite now uses [bigfoot](https://github.com/axiomantic/bigfoot) for subprocess interception. `subprocess.run` and `shutil.which` mocks in `test_install_libclang.py`, `test_version_detect.py`, `test_libclang.py`, and `test_windows_detection.py` are replaced with `bigfoot.subprocess_mock`, which enforces strict FIFO ordering and fails fast on unexpected calls.
+- Integration test writer assertions extracted into shared helpers (`_check_ctypes_write`, `_check_cython_write`, etc.) in `test_real_headers.py`, eliminating repeated assertion logic across the five library test classes.
+
 ## [0.8.1] - 2026-03-04
 
 ### Removed

pyproject.toml

@@ -19,7 +19,6 @@ classifiers = [
     "Topic :: Software Development :: Code Generators",
     "Topic :: Software Development :: Compilers",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -30,7 +29,7 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Typing :: Typed",
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = []
 
 [project.urls]
@@ -43,15 +42,16 @@ Changelog = "https://github.com/axiomantic/headerkit/blob/main/CHANGELOG.md"
 headerkit = "headerkit._cli:main"
 
 [project.optional-dependencies]
-toml = ["tomli>=1.1.0; python_version < '3.11'"]
-test = ["pytest", "pytest-timeout"]
+toml = []
+test = ["pytest", "pytest-timeout", "bigfoot>=0.3.0"]
 lint = ["ruff", "mypy"]
 docs = ["mkdocs>=1.6", "mkdocs-material>=9.5", "mkdocstrings[python]>=0.27", "mike>=2.1"]
 dev = ["headerkit[test,lint,docs,toml]"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["headerkit"]
 
+
 [tool.ruff]
 line-length = 120
 target-version = "py310"

tests/conftest.py

@@ -0,0 +1 @@
+# bigfoot.pytest_plugin is registered automatically via the pytest11 entry point.

tests/test_backends/test_libclang.py

@@ -5,8 +5,9 @@
 import os
 import shutil
 import subprocess
-from unittest.mock import MagicMock, patch
+from unittest.mock import patch
 
+import bigfoot
 import pytest
 
 from headerkit.backends.libclang import (
@@ -728,59 +729,84 @@ def test_c_and_cxx_cached_separately(self):
 
     def test_clang_not_found_returns_empty(self):
         """When clang is not on PATH, returns empty list."""
+        import sys
+
         import headerkit.backends.libclang as mod
 
+        null_file = "NUL" if sys.platform == "win32" else "/dev/null"
         mod._system_include_cache_c = None
-        with patch("headerkit.backends.libclang.subprocess.run", side_effect=FileNotFoundError):
+        bigfoot.subprocess_mock.mock_run(
+            ["clang", "-v", "-x", "c", "-E", null_file],
+            raises=FileNotFoundError(),
+        )
+        with bigfoot.sandbox():
             result = get_system_include_dirs()
-            assert result == []
+        assert result == []
+        bigfoot.assert_interaction(bigfoot.subprocess_mock.run, command=["clang", "-v", "-x", "c", "-E", null_file])
 
     def test_clang_timeout_returns_empty(self):
         """When clang times out, returns empty list."""
+        import sys
+
         import headerkit.backends.libclang as mod
 
+        null_file = "NUL" if sys.platform == "win32" else "/dev/null"
         mod._system_include_cache_c = None
-        with patch(
-            "headerkit.backends.libclang.subprocess.run",
-            side_effect=subprocess.TimeoutExpired(cmd="clang", timeout=10),
-        ):
+        bigfoot.subprocess_mock.mock_run(
+            ["clang", "-v", "-x", "c", "-E", null_file],
+            raises=subprocess.TimeoutExpired(cmd="clang", timeout=10),
+        )
+        with bigfoot.sandbox():
             result = get_system_include_dirs()
-            assert result == []
+        assert result == []
+        bigfoot.assert_interaction(bigfoot.subprocess_mock.run, command=["clang", "-v", "-x", "c", "-E", null_file])
 
     def test_parses_include_search_paths(self):
         """Parses clang -v output to extract include search paths."""
+        import sys
+
         import headerkit.backends.libclang as mod
 
+        null_file = "NUL" if sys.platform == "win32" else "/dev/null"
         mod._system_include_cache_c = None
-        mock_result = MagicMock()
-        mock_result.stderr = (
-            "clang version 18.0.0\n"
-            "#include <...> search starts here:\n"
-            " /usr/lib/clang/18/include\n"
-            " /usr/include\n"
-            "End of search list.\n"
+        bigfoot.subprocess_mock.mock_run(
+            ["clang", "-v", "-x", "c", "-E", null_file],
+            returncode=0,
+            stderr=(
+                "clang version 18.0.0\n"
+                "#include <...> search starts here:\n"
+                " /usr/lib/clang/18/include\n"
+                " /usr/include\n"
+                "End of search list.\n"
+            ),
         )
-        with patch("headerkit.backends.libclang.subprocess.run", return_value=mock_result):
+        with bigfoot.sandbox():
             result = get_system_include_dirs()
-            assert "-isystem/usr/lib/clang/18/include" in result
-            assert "-isystem/usr/include" in result
+        assert result == ["-isystem/usr/lib/clang/18/include", "-isystem/usr/include"]
+        bigfoot.assert_interaction(bigfoot.subprocess_mock.run, command=["clang", "-v", "-x", "c", "-E", null_file])
 
     def test_skips_framework_directories(self):
         """Framework directories are excluded from the result."""
+        import sys
+
         import headerkit.backends.libclang as mod
 
+        null_file = "NUL" if sys.platform == "win32" else "/dev/null"
         mod._system_include_cache_c = None
-        mock_result = MagicMock()
-        mock_result.stderr = (
-            "#include <...> search starts here:\n"
-            " /usr/include\n"
-            " /System/Library/Frameworks (framework directory)\n"
-            "End of search list.\n"
+        bigfoot.subprocess_mock.mock_run(
+            ["clang", "-v", "-x", "c", "-E", null_file],
+            returncode=0,
+            stderr=(
+                "#include <...> search starts here:\n"
+                " /usr/include\n"
+                " /System/Library/Frameworks (framework directory)\n"
+                "End of search list.\n"
+            ),
         )
-        with patch("headerkit.backends.libclang.subprocess.run", return_value=mock_result):
+        with bigfoot.sandbox():
             result = get_system_include_dirs()
-            assert "-isystem/usr/include" in result
-            assert len(result) == 1  # framework dir excluded
+        assert result == ["-isystem/usr/include"]
+        bigfoot.assert_interaction(bigfoot.subprocess_mock.run, command=["clang", "-v", "-x", "c", "-E", null_file])
 
 
 @libclang