# Test Suite Overview

## Test hierarchy

Three tiers:

- **`tests/unit/`** — pure Python, no GPU. Covers isolated logic (pending edits, sync plan construction, flag masks, equilibrium helpers).
- **`tests/integration/`** — requires GPU. Covers the full body topology sync pipeline (recompile, DDF patch, unified obs/act) and stream API.
- **`tests/validation/`** — requires GPU, long-running (hours). Physics regression against Kan99b, Sah04, and sensor accuracy references.

## Running tests

```
conda run -n pycuda_3_10 python -m pytest <test_path> -v
```

| What you want to verify | Command |
|---|---|
| Body module logic after refactor | `pytest tests/unit/ -v` |
| sync_bodies pipeline (no DDF patch) | `pytest tests/integration/test_sync_bodies_skeleton.py -v` |
| DDF patch after add/remove | `pytest tests/integration/test_ddf_patch.py -v` |
| Unified action/obs + stream API | `pytest tests/integration/test_unified_obs.py -v` |
| Full body add/remove e2e | `pytest tests/integration/test_body_sync_e2e.py -v` |
| All integration tests | `pytest tests/integration/ -v` |
| All tests (unit + integration) | `pytest tests/unit/ tests/integration/ -v` |
| Physics regression | `python tests/validation/run_kan99b_rotating_cylinder.py` |

## Per-file coverage

| File | GPU | Tests | What it covers |
|---|---|---|---|
| `test_pending_edits.py` | No | 14 | stage_add / stage_remove / has_pending_edit / clear_pending_edits lifecycle |
| `test_sync_plan.py` | No | 16 | build_flags_for, build_compact_lists_for, build_next_objects, build_sync_plan, commit_pending |
| `test_body_flags.py` | No | 6 | FRC_REGION / SENSOR_FLAG / OBSTACLE bits for each body type |
| `test_equilibrium.py` | No | 4 | compute_feq_d2q9 and compute_macro_from_ddf numerical correctness |
| `test_sync_bodies_skeleton.py` | Yes | 7 | sync_bodies flow: recompile, esopull guard, step count preservation, pending discard |
| `test_ddf_patch.py` | Yes | 5 | DDF patch after add/remove: finite forces, released region is fluid |
| `test_unified_obs.py` | Yes | 5 | host-only set_body, auto transfer, stream API, DRL loop pattern |
| `test_body_sync_e2e.py` | Yes | 2 | Full add -> remove -> checkpoint -> load -> run cycle |

## Notes

- `pycuda.autoinit` is required for all integration tests (selects GPU 0 by default; set `CUDA_VISIBLE_DEVICES` to change).
- The curved boundary kernel produces NaN in obstacle-adjacent fluid cells over long runs; DDF patch tests use 50-step verification windows.