Add free-threading safety tests and CI integration

- Introduced `test-freethreaded` command for thread safety testing with `pytest-freethreaded`.
- Added `ci-checks-ft` for comprehensive CI checks including free-threading tests.
- Updated dependencies to include `pytest-freethreaded` and `pytest-timeout`.
- Enhanced documentation with guidelines for thread safety testing and Python 3.14t usage.
- Updated workflows to run free-threading safety checks during CI.

Author: pauleveritt

.github/workflows/ci.yml

@@ -18,5 +18,5 @@ jobs:
         run: |
           curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
 
-      - name: Run CI checks
-        run: just ci-checks
+      - name: Run CI checks (including free-threading safety)
+        run: just ci-checks-ft

Justfile

@@ -26,6 +26,10 @@ test *ARGS:
 test-parallel *ARGS:
     uv run pytest -n auto {{ ARGS }}
 
+# Run tests with free-threading safety checks (parallel threads + iterations)
+test-freethreaded *ARGS:
+    uv run pytest --threads=8 --iterations=10 --require-gil-disabled {{ ARGS }}
+
 # Lint code (check for issues)
 lint *ARGS:
     uv run ruff check {{ ARGS }} .
@@ -63,6 +67,10 @@ clean:
 ci-checks:
     just install && just lint && just fmt-check && just typecheck && just test-parallel
 
+# Run all checks + free-threading safety tests
+ci-checks-ft:
+    just ci-checks && just test-freethreaded
+
 # Enable pre-push hook to run ci-checks before pushing
 enable-pre-push:
     @echo "Installing pre-push hook..."

docs/benchmark.md

@@ -410,17 +410,53 @@ With Python 3.14's free-threaded build (no GIL):
 
 ### Running with Free-Threaded Python
 
-To test with Python 3.14's free-threaded build:
+aria-testing uses Python 3.14t (free-threaded build) by default and includes specialized testing to detect thread safety issues.
+
+#### Standard Testing
+
+```bash
+# Regular parallel tests (pytest-xdist)
+just test-parallel
+
+# All quality checks (lint, format, typecheck, tests)
+just ci-checks
+```
+
+#### Free-Threading Safety Testing
+
+Uses `pytest-freethreaded` to run tests multiple times across multiple threads simultaneously:
+
+```bash
+# Run tests with thread safety detection
+just test-freethreaded
+
+# This runs: pytest --threads=8 --iterations=10 --require-gil-disabled
+# - 8 threads running tests in parallel
+# - 10 iterations of each test
+# - Requires GIL to be disabled (fails if not using 3.14t)
+```
+
+**What This Detects:**
+- Race conditions from concurrent access
+- Deadlocks and hangs (via timeouts)
+- Issues with global mutable state
+- Non-deterministic behavior
+
+**Timeouts Configured:**
+- `timeout = 60` - Test timeout (detects hangs)
+- `faulthandler_timeout = 120` - Dump stack traces on timeout
+
+#### Manual Free-Threading Testing
 
 ```bash
-# Install free-threaded Python 3.14
-# (Build with --disable-gil or use python3.14t)
+# Verify Python is free-threaded
+python -c "import sys; print(f'Free-threaded: {not sys._is_gil_enabled()}')"
 
-# Run tests with free-threading enabled
-PYTHON_GIL=0 pytest -n auto
+# Run with custom thread/iteration counts
+pytest --threads=16 --iterations=50 --require-gil-disabled tests/test_concurrency.py
 
-# Verify no race conditions with longer runs
-PYTHON_GIL=0 pytest -n auto --count=100
+# Run specific stress test
+pytest tests/test_concurrency.py::TestThreadSafetyStress -v
 ```
 
 ### Thread-Safety Guarantees

docs/contributing.md

@@ -6,7 +6,7 @@ Guide for developers contributing to aria-testing.
 
 ### Prerequisites
 
-- Python 3.14+
+- Python 3.14t (free-threaded build)
 - [uv](https://docs.astral.sh/uv/) package manager
 - [just](https://just.systems/) command runner
 
@@ -45,11 +45,13 @@ just fmt-check     # Check formatting without changes
 just typecheck     # Run type checking
 
 # Testing
-just test          # Run tests (sequential)
-just test-parallel # Run tests (parallel)
+just test                # Run tests (sequential)
+just test-parallel       # Run tests (parallel with pytest-xdist)
+just test-freethreaded   # Run thread safety tests (8 threads x 10 iterations)
 
 # Quality checks
 just ci-checks     # Run all checks (lint, format, typecheck, tests)
+just ci-checks-ft  # All checks + free-threading safety tests
 
 # Documentation
 just docs          # Build documentation
@@ -283,6 +285,80 @@ just test-parallel
 just test --cov
 ```
 
+### Thread Safety Testing
+
+aria-testing is designed for Python 3.14's free-threaded mode (no GIL). All code must be thread-safe.
+
+#### Testing for Thread Safety
+
+Use `pytest-freethreaded` to detect race conditions and threading issues:
+
+```bash
+# Run thread safety tests (8 threads, 10 iterations)
+just test-freethreaded
+
+# Custom thread/iteration counts
+pytest --threads=16 --iterations=50 --require-gil-disabled tests/
+
+# Test specific concurrency tests
+pytest tests/test_concurrency.py -v
+```
+
+#### What Gets Tested
+
+The `--threads` and `--iterations` options:
+- Run each test multiple times (`--iterations=10`)
+- Run tests concurrently across threads (`--threads=8`)
+- Expose race conditions, deadlocks, and non-deterministic behavior
+
+Example:
+```bash
+# This test will run 80 times total (8 threads × 10 iterations)
+pytest tests/test_queries.py::test_get_by_role --threads=8 --iterations=10
+```
+
+#### Writing Thread-Safe Tests
+
+**✅ Good - No shared mutable state:**
+```python
+def test_concurrent_queries():
+    # Each test creates its own container - thread-safe
+    doc = html(t'<div><button>Click</button></div>')
+    button = get_by_role(doc, "button")
+    assert button.tag == "button"
+```
+
+**⚠️ Careful - Shared containers are OK if read-only:**
+```python
+# Module-level container (created once)
+SAMPLE_DOC = html(t'<div><button>Click</button></div>')
+
+def test_read_only_access():
+    # Read-only access to shared container - thread-safe
+    button = get_by_role(SAMPLE_DOC, "button")
+    assert button.tag == "button"
+```
+
+**❌ Bad - Shared mutable state:**
+```python
+# Module-level mutable list - NOT thread-safe!
+results = []
+
+def test_with_shared_state():
+    # Multiple threads modifying same list - race condition!
+    element = get_by_role(doc, "button")
+    results.append(element)  # ❌ NOT THREAD-SAFE
+```
+
+#### Thread Safety Guidelines
+
+1. **No global mutable state** - Use function-local variables
+2. **Immutable data structures** - Use `MappingProxyType`, tuples, frozensets
+3. **No caching without locks** - Caching creates shared mutable state
+4. **Document thread-safety** - Mark functions as thread-safe in docstrings
+
+See `tests/test_concurrency.py` for examples of proper thread-safe testing.
+
 ## Adding New Features
 
 ### Adding a New Query Type

pyproject.toml

@@ -21,6 +21,9 @@ Homepage = "https://github.com/t-strings/aria-testing"
 testpaths = ["tests"]
 python_files = ["test_*.py"]
 addopts = "-p no:doctest"
+# Free-threading safety: timeout tests to detect hangs/deadlocks
+timeout = 60
+faulthandler_timeout = 120
 
 [build-system]
 requires = ["uv_build>=0.8.17,<0.9.0"]
@@ -37,4 +40,6 @@ dev = [
     "sphinx-autobuild>=2024.9.3",
     "ty>=0.0.1a25",
     "coverage>=7.11.2",
+    "pytest-freethreaded>=0.1.0",
+    "pytest-timeout>=2.4.0",
 ]