| name | Testcontainers Reuse (Node) |
| description | Teaches the agent to speed up Node integration tests with Testcontainers reuse — withReuse(true), TESTCONTAINERS_REUSE_ENABLE, the .testcontainers.properties opt-in, stable hashing for Postgres/MySQL/Kafka, and Ryuk/CI caveats. |
| version | 1.0.0 |
| author | thetestingacademy |
| license | MIT |
| tags | ["testcontainers","reuse","docker","integration-testing","postgres","kafka","ryuk","node"] |
| testingTypes | ["integration","e2e"] |
| frameworks | ["testcontainers","vitest","jest"] |
| languages | ["typescript"] |
| domains | ["api","web"] |
| agents | ["claude-code","cursor","github-copilot","windsurf","codex","aider","continue","cline","zed","bolt","gemini-cli","amp"] |
Testcontainers Reuse (Node)
This skill makes the agent use Testcontainers' reuse feature to cut local integration-test startup from seconds to milliseconds, while avoiding the footguns: reuse is an explicit developer opt-in (it is off in CI by design), it requires a stable container configuration to hash, and a reused container is not cleaned up by Ryuk, so test data must be reset by the test, not the container lifecycle.
Use this skill when local integration tests are slow because every run boots a fresh Postgres/MySQL/Kafka, or when the user asks about withReuse, TESTCONTAINERS_REUSE_ENABLE, or "keep the container alive between runs."
Core Principles
- Reuse is opt-in and local-only. It activates only when
withReuse(true) is set AND testcontainers.reuse.enable=true is in the user's ~/.testcontainers.properties (or TESTCONTAINERS_REUSE_ENABLE=true). It should stay off in CI, where clean state matters more than speed.
- Reuse keys on a config hash. Testcontainers hashes the container's configuration (image, ports, env, command, labels). Any change to that config produces a new container. Keep config stable to actually reuse.
- A reused container survives the test run. Ryuk (the resource-reaper) does not kill containers marked for reuse, so they linger for the next run. That is the point — but it means you must reset state between runs.
- Reset data, not the container. Truncate tables, delete topics' messages, or use transactions/savepoints — do not rely on a fresh container per test.
- Reuse and
.stop() are mutually exclusive in intent. Do not call .stop() in teardown for a reused container, or you defeat reuse on the next run.
- Pin images by digest/tag so the hash is deterministic across machines and runs.
Workflow / Patterns
Pattern 1 — Enable reuse globally (one-time developer setup)
Reuse needs a machine-level opt-in. The agent should instruct the user to create this file (it is intentionally not committed):
# ~/.testcontainers.properties
testcontainers.reuse.enable=true
Equivalent for the current shell (useful in scripts, NOT in CI):
export TESTCONTAINERS_REUSE_ENABLE=true
