Run Tests

Goal

Run the right tests for the change you are making — unit, service, or system — and read the output in a way that makes failures actionable.

Prerequisites

• Local stack bootstrapped (./dev start infra) so that Testcontainers has a working Docker daemon.
• Familiarity with Testing — especially the "favour service tests over unit tests" and "emulate, don't mock" disciplines.

Steps

1. Run per-service tests

./dev test core        # Go service tests for wordloop-core
./dev test ml          # Python tests + evals for wordloop-ml
./dev test app         # Vitest + React Testing Library for wordloop-app
./dev test             # Everything

Service tests spin up real Postgres and Pub/Sub containers where needed.

2. Run system tests

System tests exercise multiple services together through their real APIs and trace assertions.

./dev test system

These take longer; run them before opening a PR that touches multiple services.

3. Run with race detection (Go)

./dev test core -- -race

Concurrency bugs are easier to find than to debug; run with -race on any change that touches goroutines.

4. Run ML evals

./dev test ml -- --evals

Runs the committed eval set. Regressions above the threshold fail the command.

Verification

• Exit code 0 on the targeted suites.
• Trace assertions pass (no missing spans).
• Coverage report (if enabled) shows the change is exercised.

Troubleshooting

• "Cannot connect to Docker daemon." Start Docker Desktop; verify with ./dev status.
• Testcontainers start slow. First run pulls the Postgres image; subsequent runs use the cached image.
• Flaky test. Flakiness is a bug. File it; do not retry until green.

See Testing for the underlying stance.