docs: document the pytest test suite in testing.md

testing.md only described the dummy-module example run; add a section on the
actual test suite — the structural / property / synthetic-FITS tiers, where
the tests live, that CI runs them inside the dev image as the single gate, and
how to run them yourself (in the image as CI does, or via pytest in a dev
checkout). Keep the example-pipeline smoke run as a quick "is it alive" check.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cailmdaley

docs/source/testing.md

@@ -1,27 +1,72 @@
 # Testing
 
-After reading through the [basic execution](basic_execution.md) and
-[configuration](configuration.md) instructions it may be helpful to run a few
-tests.
+ShapePipe has two complementary ways to check that things work: the automated
+**test suite** (run by CI, and by you during development) and a **smoke run** of
+the bundled example pipeline.
 
-ShapePipe includes some dummy modules for testing purposes
+## The automated test suite
 
-- `python_example_runner` : an example of a module written entirely in Python
-- `serial_example_runner` : an example of a module that is run in serial mode
-- `execute_example_runner` : an example of a module that calls a system
-  executable
+The test suite runs with [pytest](https://docs.pytest.org/) and lives in two
+trees:
 
-None of these modules do anything particularly interesting, but they can be run
-to test that ShapePipe is up and running.
+- `tests/unit/` — **structural** tests, one parametrized case per file: every
+  shell script parses (`bash -n`), every example config parses, every
+  `shapepipe.*` submodule imports, every `[project.scripts]` entry handles
+  `-h`, and every `*_runner.py` carries its `@module_runner` metadata. Cheap,
+  broad, and good at catching the dumb-but-real regressions (a syntax error, a
+  broken import, a renamed entry point).
+- `src/shapepipe/tests/` — **unit, property-based, and integration** tests for
+  the analytic surface: pure helpers and geometry (coordinate round-trips,
+  postage-stamp shapes, the MegaCam CCD flip), tested both by example and with
+  [Hypothesis](https://hypothesis.readthedocs.io/) property tests where a
+  function has a clear invariant. Integration tests that need the astromatic
+  binaries (Source Extractor, PSFEx) build synthetic FITS on the fly rather
+  than requiring survey data.
 
-The [example](https://github.com/CosmoStat/shapepipe/tree/develop/example)
-directory contains an example config file called `config.ini` that runs all of
-these dummy modules. ShapePipe can be run with this config file as follows
+**CI is the single gate.** On every pull request and every push to `develop`,
+`.github/workflows/deploy-image.yml` builds the dev image and runs the suite
+*inside it* — so the tests exercise exactly the environment that ships. A green
+check means the container actually works.
+
+### Running it yourself
+
+The supported way is inside the dev image (it carries the `test` extra and the
+astromatic binaries), exactly as CI does:
+
+```bash
+docker run --rm -e HYPOTHESIS_PROFILE=ci \
+    ghcr.io/cosmostat/shapepipe:develop pytest -rX
+```
+
+From a development checkout (e.g. inside an Apptainer sandbox with the repo
+bind-mounted), run pytest directly:
+
+```bash
+pytest                       # the whole suite, with coverage reported
+pytest tests/unit            # just the fast structural tier
+```
+
+The `ci` Hypothesis profile is deterministic (fixed seed, capped examples) so CI
+is fast and reproducible; running without it locally explores more widely.
+Coverage is reported (`--cov-report=term-missing`) but not gated.
+
+## Smoke test — the example pipeline
+
+To confirm a fresh install runs end to end, the
+[example](https://github.com/CosmoStat/shapepipe/tree/develop/example) directory
+contains a `config.ini` that chains a few dummy modules:
+
+- `python_example_runner` — a module written entirely in Python
+- `serial_example_runner` — a module run in serial mode
+- `execute_example_runner` — a module that calls a system executable
+
+None do anything scientifically interesting, but running them confirms ShapePipe
+is up:
 
 ```bash
 shapepipe_run -c ./example/config.ini
 ```
 
-The output of this run will be saved to `./example/output`. If you want a
-more concrete understanding of what each of the configuration options does you
-can modify `config.ini` and see what happens.
+Output is saved to `./example/output`. Inside the container, the
+`shapepipe_run_example` wrapper does the same against a writable copy of the
+example tree, so it works even on a read-only (apptainer/SIF) filesystem.