add --reuse flag for container reuse in local dev

[p-datadog]

Summary

When iterating on test code locally, the full container lifecycle adds 30-60+ seconds per run — even when the containers haven't changed at all. This PR adds a --reuse flag that attaches to already-running containers instead of restarting them.

How it works

Just always pass +u during local development:

./run.sh DEFAULT +u   # first time: no containers -> starts them, keeps alive
./run.sh DEFAULT +u   # containers exist -> attaches instantly, runs tests
./run.sh DEFAULT +u   # iterate on tests...

# rebuild tracer
./build.sh ruby --binary-path ~/code/dd-trace-rb

./run.sh DEFAULT +u   # detects stale image -> restarts containers, keeps alive
./run.sh DEFAULT +u   # back to fast iteration

The flag is always safe to use — it falls back to a normal start when containers are missing, stopped, or stale (image was rebuilt). No need to remember when to use it and when not to.

Staleness detection

When --reuse finds existing containers, it compares each container's image ID against the current Docker image. If the image was rebuilt since the container started, the containers are torn down and started fresh automatically. This prevents silently testing against an old container after a rebuild.

What changed

conftest.py — registers --reuse / -u via parser.addoption, following the established pattern alongside --replay, --sleep, etc.

run.sh — new +u/++reuse flag that passes --reuse to pytest. Added to help text.

utils/_context/_scenarios/core.py — _reuse flag read from config.option.reuse in pytest_configure (alongside self.replay); skip log directory wipe when reusing so healthcheck files from the prior run survive.

utils/_context/_scenarios/endtoend.py:

• _attach_or_start_containers(): validates containers are running with the correct image. Attaches if possible (one Docker API call per container); falls back to a normal fresh start if any container is missing, stopped, or stale. After fallback, re-enables reuse on containers so they're kept alive for the next run.
• Refactors _wait_and_stop_containers() into _drain_interfaces() + _stop_containers() — this separation lets reuse drain interface data without stopping containers.

utils/_context/containers.py:

• image_is_stale(): compares running container's image ID against current Docker image.
• configure() gains a reuse parameter — skips killing old containers and loads image info from existing logs instead of Docker.
• stop() and remove() are no-ops in reuse mode, guarded at the leaf level so all callers (including error paths) are covered.

Behavior change in the drain/stop refactor

The original code interleaved draining and stopping: drain library interface, stop weblog, drain buddy interfaces, stop buddies, drain agent interface, stop agent. The refactored version drains all interfaces first, then stops all containers.

This means the agent container keeps running (and potentially receiving data) during the library interface drain, where before it would have been stopped right after its own drain. This is arguably better — more data gets captured — but it's a change in the non-reuse path too. The refactor is a prerequisite for reuse (which needs to drain without stopping), and the behavior difference should be harmless in practice since the drain timeouts are the same either way.

Lifecycle comparison

Normal:        configure -> kill_old -> start -> health -> post_start -> readiness -> [tests] -> drain all -> stop all -> remove
Reuse (hit):   configure(keep) -> attach -> post_start(from logs) -> [tests] -> drain all -> (keep alive)
Reuse (miss):  configure(keep) -> not found -> reconfigure -> start -> ... -> [tests] -> drain all -> (keep alive)
Reuse (stale): configure(keep) -> stale image -> reconfigure -> start -> ... -> [tests] -> drain all -> (keep alive)

Test plan

• Normal run without --reuse — full lifecycle, containers start and stop as before
• +u with no containers running — falls back to normal start, keeps containers alive
• +u with containers running — attaches, runs tests fast, keeps alive
• Rebuild image, then +u — detects stale image, restarts fresh, keeps alive
• +u with stopped containers — falls back to normal start
• Verify interface data is still drained on reuse (test assertions pass)
• Verify ./run.sh +h shows ++reuse in the help output

Generated with Claude Code

[github-actions]

CODEOWNERS have been resolved as:

conftest.py                                                             @DataDog/system-tests-core
run.sh                                                                  @DataDog/system-tests-core
tests/test_the_test/test_docker_scenario.py                             @DataDog/system-tests-core
utils/_context/_scenarios/core.py                                       @DataDog/system-tests-core
utils/_context/_scenarios/endtoend.py                                   @DataDog/system-tests-core
utils/_context/containers.py                                            @DataDog/system-tests-core