Code coverage support

Author: davidfstr

.coverage

@@ -30,3 +30,6 @@ tmpdir_*
 
 # AI Coding
 /plan
+
+# Coverage
+.coverage

.gitignore

@@ -37,3 +37,12 @@ Windows 11 and later:
 
 Linux:
 * Figure it out and let me know.
+
+
+Running Coverage
+================
+
+$ coverage run -m crystal --test
+$ coverage report
+$ coverage html
+$ open htmlcov/index.html

COMPILING.txt

@@ -26,6 +26,7 @@ Release Notes ⋮
     * Manually bring app to front on macOS when run from source,
       to workaround a wxPython 4.2.3 bug.
     * Show correct Dock icon on macOS when run from source.
+    * Code coverage statistics can now be gathered using the `coverage` tool.
 
 ### v2.0.0 (September 26, 2025)
 

RELEASE_NOTES.md

@@ -123,6 +123,7 @@ pillow = { version = ">=9.2.0", markers = "sys_platform == 'linux'" }
 playwright = "^1.48.0"
 # For serializing local function closures in Playwright tests
 dill = "^0.3.8"
+coverage = "^7.11.0"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

poetry.lock

@@ -323,9 +323,14 @@ def on_atexit() -> None:
             # Main thread did not set an exit code. Assume a bug.
             exit_code = 1  # default error exit code
 
-        # Exit process immediately, without bothering to run garbage collection
-        # or other cleanup processes that can take a long time
-        os._exit(exit_code)
+        from crystal.util.xos import is_coverage
+        if is_coverage():
+            # Exit process normally, so that coverage results are written to disk
+            pass
+        else:
+            # Exit process immediately, without bothering to run garbage collection
+            # or other cleanup processes that can take a long time
+            os._exit(exit_code)
     atexit.register(on_atexit)
 
     # Set headless mode, before anybody tries to call fg_call_later
@@ -564,6 +569,8 @@ def _on_end_session(self, event: wx.CloseEvent) -> None:
             # before starting bg_task() on background thread
             from crystal.tests.index import run_tests
             from crystal.util.bulkheads import capture_crashes_to_stderr
+            from crystal.util.xos import is_coverage
+            from crystal.util.xthreading import fg_call_and_wait
 
             # NOTE: Any unhandled exception will probably call os._exit(1)
             #       before reaching this decorator.
@@ -579,7 +586,16 @@ def bg_task():
                     is_ok = run_tests(parsed_args.test)
                 finally:
                     exit_code = 0 if is_ok else 1
-                    os._exit(exit_code)
+                    if is_coverage():
+                        # Exit app normally,
+                        # so that coverage results are written to disk
+                        def close_all_windows() -> None:
+                            for w in list(wx.GetTopLevelWindows()):
+                                w.Close()
+                        fg_call_and_wait(close_all_windows)
+                    else:
+                        # Exit app immediately
+                        os._exit(exit_code)
             bg_call_later(bg_task)
 
         # 1. Run main loop

pyproject.toml

@@ -18,7 +18,7 @@
 from crystal.tests.util.subtests import SubtestFailed
 from crystal.util.test_mode import tests_are_running
 from crystal.util.xcollections.dedup import dedup_list
-from crystal.util.xos import is_windows
+from crystal.util.xos import is_coverage, is_windows
 from crystal.util.xthreading import bg_affinity, fg_call_and_wait, has_foreground_thread, is_foreground_thread
 from crystal.util.xtime import sleep_profiled
 from crystal.util.xtraceback import _CRYSTAL_PACKAGE_PARENT_DIRPATH
@@ -235,6 +235,10 @@ def _run_tests(test_names: list[str]) -> bool:
             test_func_id = (test_func.__module__, test_func.__name__)  # type: _TestFuncId
             test_name = f'{test_func_id[0]}.{test_func_id[1]}'
 
+            # Skip suites that cause segfaults under coverage
+            if is_coverage() and 'test_bulkheads' in test_name:
+                continue
+            
             # Only run test if it was requested (or if all tests are to be run)
             if len(test_names) > 0:
                 if test_name not in test_names and test_func.__module__ not in test_names:

src/crystal/main.py

@@ -91,6 +91,10 @@ def is_asan() -> bool:
     return os.environ.get('CRYSTAL_ADDRESS_SANITIZER') == 'True'
 
 
+def is_coverage() -> bool:
+    return os.environ.get('COVERAGE_RUN', None) is not None
+
+
 # === Misc ===
 
 def preferences_are_called_settings_in_this_os() -> bool: