API improvements roadmap #1581

Tracking issue for an API review of testcontainers 12.2.0 and its modules: correctness bugs in the public API, gaps against the Java, Go and .NET implementations, and changes that would make the library nicer to use.

The issues are grouped into tracks that can be worked on in parallel. Each issue ends with a Dependencies section that uses three terms:

• Blocked by: cannot usefully start before the other issue lands.
• Stack on: changes the same code. Open it as a stacked pull request on top of the other one (gh stack).
• Coordinate with: overlapping lines or a shared decision. Whoever lands second rebases.

Stacks

Chains where the order matters. Everything else is independent.

• withEnvironment: Replace the existing entry when withEnvironment sets a key twice #1519 → Accept numbers and booleans in withEnvironment #1543
• start() and builder state: Make start() safe to call more than once on the same container #1520 first, then in parallel Add an escape hatch for raw container create options #1550, Let a configured container be cloned and customised with functions #1556, Expose host ports per container instead of globally #1557, and Add lifecycle hooks that do not need a subclass #1554 → Emit lifecycle events with timings #1555
• Reuse: Include host config and copied files in the container reuse hash #1522 → Give reusable containers a stable identity and a way to prune them #1552 → Make container reuse safe across processes #1553, and Include host config and copied files in the container reuse hash #1522 → Unify the copy-to-container methods and add reading a file from a container #1547
• exec: Stop splitting string commands on spaces in exec #1525 and Declare option fields as optional instead of wrapping the types in Partial #1531 → Extend exec: reject on failure, stdin, streaming output and a timeout #1548
• Compose flags: Keep a custom project name when withNoRecreate() is used #1524 → Accept a boolean in the no-argument flag setters #1530
• Wait strategies: Stop the container startup timeout overriding a wait strategy's own timeout #1523, Let Wait.forListeningPorts() wait on specific ports #1533 and Make the port optional in Wait.forHttp #1534 first, then Pass the started container to WaitStrategy.waitUntilReady #1558 → Add a function-based wait strategy #1559 and Support AbortSignal in start(), exec and other long-running calls #1560, then Apply one startup deadline from container start to ready #1582
• Networks: Support network options on Network #1535 → Remove the Uuid test seam from public constructors #1561, and Take network aliases with the network, and allow more than one network #1536 → Provide in-network connection details from modules #1567
• Configuration and diagnostics: Add programmatic configuration #1569 → Add pluggable image name substitution #1570, and Say why no container runtime was found #1571 → Add a doctor command #1572
• Entry point: Pass the started container to WaitStrategy.waitUntilReady #1558 and Remove the Uuid test seam from public constructors #1561 → Separate module-author internals from the user-facing entry point #1562; Export the types used in public method signatures #1528 → Track the public API surface in CI #1580
• Module shape: Make start() safe to call more than once on the same container #1520 and Add lifecycle hooks that do not need a subclass #1554 → Remove the need for AbstractStartedContainer wrappers in modules #1563, after the started-container additions

Next major

Labelled major: #1521, #1558, #1561, #1562, #1563, #1582.

Labelled patch or minor but with a behaviour change to decide on: #1523, #1527, #1529, #1557, #1577.

Tracks

Foundations

• Agree a deprecation path for API changes #1518 (can start now)
• Track the public API surface in CI #1580
• Add TSDoc to the public API and publish an API reference #1579 (can start now)
• Load feature-specific dependencies on first use #1577 (can start now)
• Add a shared contract test for modules #1576 (can start now)

Builder state and start()

• Replace the existing entry when withEnvironment sets a key twice #1519 (can start now)
• Accept numbers and booleans in withEnvironment #1543
• Make start() safe to call more than once on the same container #1520 (can start now)
• Add an escape hatch for raw container create options #1550
• Let a configured container be cloned and customised with functions #1556
• Expose host ports per container instead of globally #1557
• Add lifecycle hooks that do not need a subclass #1554
• Emit lifecycle events with timings #1555
• Make repeated with* calls merge consistently #1527 (can start now)
• Accept a boolean in the no-argument flag setters #1530
• Add the missing builder methods to the TestContainer interface #1529 (can start now)
• Declare option fields as optional instead of wrapping the types in Partial #1531 (can start now)

Reuse

• Call the lifecycle hooks and log consumer when a container is reused #1521 (can start now)
• Include host config and copied files in the container reuse hash #1522 (can start now)
• Give reusable containers a stable identity and a way to prune them #1552
• Make container reuse safe across processes #1553

Wait strategies

• Stop the container startup timeout overriding a wait strategy's own timeout #1523 (can start now)
• Let Wait.forListeningPorts() wait on specific ports #1533 (can start now)
• Make the port optional in Wait.forHttp #1534 (can start now)
• Pass the started container to WaitStrategy.waitUntilReady #1558 (can start now)
• Add a function-based wait strategy #1559
• Support AbortSignal in start(), exec and other long-running calls #1560
• Apply one startup deadline from container start to ready #1582

Started containers

• Stop splitting string commands on spaces in exec #1525 (can start now)
• Extend exec: reject on failure, stdin, streaming output and a timeout #1548
• Add getLogs() and a line-based log consumer #1544 (can start now)
• Add inspect() and state accessors to started containers #1545 (can start now)
• Add endpoint and URL helpers for mapped ports #1546 (can start now)
• Unify the copy-to-container methods and add reading a file from a container #1547
• Add pause(), unpause() and kill() to started containers #1549 (can start now)
• Make stopped containers restartable, or drop the empty stopped types #1541 (can start now)
• Type-check the ports passed to getMappedPort #1583 (can start now)

Errors, logging and diagnostics

• Throw typed errors with a cause #1532 (can start now)
• Say why no container runtime was found #1571 (can start now)
• Add a doctor command #1572
• Make the logger replaceable #1568 (can start now)
• Add programmatic configuration #1569 (can start now)
• Add pluggable image name substitution #1570

Networks, volumes and groups

• Support network options on Network #1535 (can start now)
• Take network aliases with the network, and allow more than one network #1536 (can start now)
• Provide in-network connection details from modules #1567
• Add named volumes #1564 (can start now)
• Start a group of containers with dependencies and shared cleanup #1565 (can start now)

Images and Compose

• Pass the image to ImagePullPolicy.shouldPull #1537 (can start now)
• Make an image built from a Dockerfile usable with modules #1551 (can start now)
• Keep a custom project name when withNoRecreate() is used #1524 (can start now)
• Address Compose containers by service name #1540 (can start now)
• Accept an in-memory Compose definition #1573 (can start now)

Public surface (next major)

• Export the types used in public method signatures #1528 (can start now)
• Remove the Uuid test seam from public constructors #1561
• Separate module-author internals from the user-facing entry point #1562
• Remove the need for AbstractStartedContainer wrappers in modules #1563

Modules

• Use octal file modes in the Redis and Valkey modules #1526 (can start now)
• Converge connection getter and command helper names across modules #1538 (can start now)
• Take named options in PostgreSqlContainer.withSSL #1539 (can start now)
• Add withInitScripts to the SQL database modules #1574 (can start now)
• Add the modules that other implementations have #1575 (can start now)

Docs and tooling

• Document and align the units of sizes and durations #1542 (can start now)
• Ship test-runner helpers for Vitest, Jest and node:test #1578 (can start now)

Dependency graph

Hard dependencies only (blocked by, stack on).

graph LR
  n63["#1582"]
  n62["#1567"]
  n56["#1580"]
  n52["#1557"]
  n51["#1554"]
  n50["#1556"]
  n49["#1552"]
  n48["#1553"]
  n47["#1570"]
  n46["#1569"]
  n45["#1555"]
  n44["#1572"]
  n43["#1571"]
  n38["#1560"]
  n37["#1543"]
  n35["#1536"]
  n33["#1550"]
  n32["#1548"]
  n31["#1547"]
  n27["#1563"]
  n26["#1559"]
  n25["#1558"]
  n22["#1535"]
  n14["#1530"]
  n12["#1531"]
  n11["#1561"]
  n10["#1562"]
  n08["#1528"]
  n07["#1525"]
  n06["#1524"]
  n05["#1520"]
  n04["#1519"]
  n02["#1522"]
  n06 --> n14
  n04 --> n37
  n02 --> n31
  n07 --> n32
  n12 --> n32
  n05 --> n33
  n02 --> n49
  n02 --> n48
  n49 --> n48
  n05 --> n51
  n51 --> n45
  n05 --> n50
  n05 --> n52
  n25 --> n26
  n25 --> n38
  n22 --> n11
  n25 --> n10
  n11 --> n10
  n05 --> n27
  n51 --> n27
  n35 --> n62
  n46 --> n47
  n43 --> n44
  n08 --> n56
  n25 --> n63
  n38 --> n63

43 of 64 issues have no hard dependency.