Organize test suite: add README, move loose tests to proper directories

- Add tests/README.md documenting test structure and usage
- Move issue_*_test.py files to tests/regression/ (9 files)
- Move loose test_*.py files to tests/unit/ (18 files)
- tests/ root now contains only pytest infrastructure

Addresses #166

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

tests/README.md

@@ -0,0 +1,174 @@
+# McRogueFace Test Suite
+
+Automated tests for the McRogueFace game engine.
+
+## Directory Structure
+
+```
+tests/
+├── unit/           # Unit tests for individual components (155+ tests)
+├── integration/    # Integration tests for system interactions
+├── regression/     # Bug regression tests (issue_XX_*.py)
+├── benchmarks/     # Performance benchmarks
+├── demo/           # Interactive demo system
+│   ├── demo_main.py    # Demo runner
+│   └── screens/        # Per-feature demo screens
+├── conftest.py     # Pytest configuration and fixtures
+├── pytest.ini      # Pytest settings
+├── run_tests.py    # Standalone test runner
+└── KNOWN_ISSUES.md # Test status and mcrfpy.step() documentation
+```
+
+## Running Tests
+
+### With pytest (recommended)
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific directory
+pytest tests/unit/ -v
+
+# Run tests matching a pattern
+pytest tests/ -k "bsp" -v
+
+# Quick run with short timeout (some timeouts expected)
+pytest tests/ -q --mcrf-timeout=5
+
+# Full run with longer timeout
+pytest tests/ -q --mcrf-timeout=30
+
+# Stop on first failure
+pytest tests/ -x
+```
+
+### With run_tests.py
+
+```bash
+# Run all tests
+python3 tests/run_tests.py
+
+# Run specific category
+python3 tests/run_tests.py unit
+python3 tests/run_tests.py regression
+
+# Verbose output
+python3 tests/run_tests.py -v
+
+# Quiet (no checksums)
+python3 tests/run_tests.py -q
+
+# Custom timeout
+python3 tests/run_tests.py --timeout=30
+```
+
+### Running individual tests
+
+```bash
+cd build
+./mcrogueface --headless --exec ../tests/unit/some_test.py
+```
+
+## Writing Tests
+
+### Test Pattern: Synchronous with `mcrfpy.step()`
+
+**Recommended:** Use `mcrfpy.step(t)` to advance simulation time synchronously.
+
+```python
+import mcrfpy
+import sys
+
+# Setup
+scene = mcrfpy.Scene("test")
+scene.activate()
+
+# Create UI elements
+frame = mcrfpy.Frame(pos=(100, 100), size=(50, 50))
+scene.children.append(frame)
+
+# Start animation
+frame.animate("x", 500.0, 1.0, mcrfpy.Easing.LINEAR)
+
+# Advance simulation synchronously
+mcrfpy.step(1.5)
+
+# Verify results
+if abs(frame.x - 500.0) < 0.1:
+    print("PASS")
+    sys.exit(0)
+else:
+    print(f"FAIL: frame.x = {frame.x}, expected 500.0")
+    sys.exit(1)
+```
+
+### Test Pattern: Timer-based (legacy)
+
+For tests that need multiple timer callbacks or complex timing:
+
+```python
+import mcrfpy
+import sys
+
+def run_test(runtime):
+    # Test code here
+    print("PASS")
+    sys.exit(0)
+
+scene = mcrfpy.Scene("test")
+scene.activate()
+
+# Timer fires after 100ms
+timer = mcrfpy.Timer("test", run_test, 100)
+# Script ends, game loop runs timer
+```
+
+### Test Output
+
+- Print `PASS` and `sys.exit(0)` for success
+- Print `FAIL` with details and `sys.exit(1)` for failure
+- Tests that timeout are marked as failures
+
+## Test Categories
+
+### Unit Tests (`unit/`)
+
+Test individual components in isolation:
+- `*_test.py` - Standard component tests
+- `api_*_test.py` - Python API tests
+- `automation_*_test.py` - Automation module tests
+
+### Regression Tests (`regression/`)
+
+Tests for specific bug fixes, named by issue number:
+- `issue_XX_description_test.py`
+
+### Integration Tests (`integration/`)
+
+Tests for system interactions and complex scenarios.
+
+### Benchmarks (`benchmarks/`)
+
+Performance measurement tests.
+
+### Demo (`demo/`)
+
+Interactive demonstrations of features. Run with:
+```bash
+cd build
+./mcrogueface ../tests/demo/demo_main.py
+```
+
+## Tips
+
+- **Read tests as examples**: Tests show correct API usage
+- **Use `mcrfpy.step()`**: Avoids timeout issues, makes tests deterministic
+- **Check KNOWN_ISSUES.md**: Documents expected failures and workarounds
+- **Screenshots**: Use `mcrfpy.automation.screenshot("name.png")` after `mcrfpy.step()`
+
+## See Also
+
+- `KNOWN_ISSUES.md` - Current test status and the `mcrfpy.step()` pattern
+- `conftest.py` - Pytest fixtures and custom collector
+- `demo/screens/` - Feature demonstrations (good API examples)