Skip to content

Commit 35eb715

Browse files
cppudgeclaude
andcommitted
docs: README accuracy pass + modules quick start (audit group F)
The stale claims the audit pinned: seven wait strategies (was "six", two places), test counts refreshed (~560 unit + ~210 integration), mutual TLS is verified end to end in CI (the tls-e2e dind job - the Remote row and the Known-gaps sentence said otherwise), and the ConanCenter wording now points at the in-review PR conan-io/conan-center-index#30600 instead of "planned right after v0.1.0". Status gains the modules-layer bullet (on main; ships with 0.2.0), and Quick start gains a PostgreSQL module snippet - the 0.2.0 headline feature had no example. Version-specific bits (requires 0.1.0, the Status headline) deliberately stay until the release pass. Opus review: SHIP; the one nit applied (gtest include in the snippet). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0141x8KrNdD9NfmCh1vSMbpg
1 parent 2469654 commit 35eb715

1 file changed

Lines changed: 36 additions & 11 deletions

File tree

README.md

Lines changed: 36 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -46,10 +46,32 @@ TEST(Cache, RedisIsReachable) {
4646
exception hierarchy carrying the HTTP status and resource id. Runnable end-to-end examples live in
4747
[`tests/integration/`](tests/integration).
4848

49+
Or start from a prebuilt **module** — pinned image, the right readiness probe, and connection
50+
strings out of the box (link `testcontainers::modules`):
51+
52+
```cpp
53+
#include <gtest/gtest.h>
54+
#include "testcontainers/modules.hpp"
55+
56+
using namespace testcontainers;
57+
58+
TEST(Db, PostgresAnswersQueries) {
59+
const modules::StartedPostgreSQL pg =
60+
modules::PostgreSQLContainer()
61+
.with_init_script("schema.sql", "CREATE TABLE t(id int);")
62+
.start(); // returns once every init script ran and TCP serves
63+
64+
// pg.connection_string() -> "postgresql://test:test@localhost:<port>/test"
65+
const ExecResult r = pg.exec_sql("SELECT count(*) FROM t");
66+
EXPECT_EQ(r.stdout_data, "0\n");
67+
}
68+
```
69+
4970
## Installation
5071

51-
testcontainers-cpp is a **Conan 2** package. A ConanCenter submission is staged for right after the
52-
`v0.1.0` tag (see [Packaging](#packaging)); until it lands, build the package from this repo into
72+
testcontainers-cpp is a **Conan 2** package. The ConanCenter submission is in review
73+
([conan-io/conan-center-index#30600](https://github.com/conan-io/conan-center-index/pull/30600),
74+
see [Packaging](#packaging)); until it lands, build the package from this repo into
5375
your local Conan cache:
5476

5577
```sh
@@ -113,24 +135,26 @@ modes:
113135
| Linux | unix socket | full unit + integration suite (gcc) |
114136
| Windows | named pipe | full suite against **real Windows containers** (MSVC) |
115137
| macOS | unix socket (Docker Desktop) | `conan create` + unit suite (apple-clang) |
116-
| Remote | `tcp://` / `https://` | TLS unit-tested; end-to-end against a remote daemon not yet verified |
138+
| Remote | `tcp://` / `https://` | mutual TLS end-to-end in CI (a real `--tlsverify` docker:dind daemon) |
117139

118140
## Status
119141

120142
**v0.1.0 — first release; feature-complete core, pre-1.0.** The public API is settled enough to use
121143
but may still evolve before 1.0. The library is exception-based by design (the `DockerError`
122-
hierarchy). Implemented and covered by **~300 unit + ~115 integration** tests against a real daemon,
144+
hierarchy). Implemented and covered by **~560 unit + ~210 integration** tests against a real daemon,
123145
green on Windows (named pipe) and Linux (unix socket):
124146

125147
- `GenericImage` / `GenericBuildableImage` / `Container` / `Network` / `Volume` /
126148
`DockerComposeContainer`
127-
- six wait strategies, `exec` (stdin / tty / streaming), copy to/from container, lifecycle hooks
149+
- seven wait strategies, `exec` (stdin / tty / streaming), copy to/from container, lifecycle hooks
128150
- container reuse, the Ryuk crash-safety reaper, registry auth incl. credential helpers
129151
- host-port exposure (`with_exposed_host_port` — sshd sidecar + SSH tunnel), and the TLS transport
152+
(mutual TLS verified end to end in CI)
153+
- the `testcontainers::modules` layer — Redis, PostgreSQL, MySQL, MariaDB, Kafka, RabbitMQ,
154+
MongoDB (on `main`; ships with 0.2.0)
130155

131-
Known gaps: **end-to-end TLS against a real remote daemon** is the main unverified path (the pure
132-
`TlsConfig` resolution is unit-tested); shared builds are **static-only on Windows** (the
133-
sources carry no symbol-export macros yet). Per-feature limits are tracked in
156+
Known gaps: shared builds are **static-only on Windows** (the sources carry no symbol-export
157+
macros yet). Per-feature limits are tracked in
134158
[`docs/feature-notes.md`](docs/feature-notes.md) and [`docs/TODO.md`](docs/TODO.md).
135159

136160
---
@@ -165,7 +189,7 @@ the Rust reference also makes), with hot polling loops opting into scoped keep-a
165189
healthcheck, static IPv4, copy-to, registry auth) and `GenericBuildableImage` (build from a
166190
Dockerfile + context, live build-log streaming, local-presence `exists`/`inspect` probes).
167191
- **Wait strategies** — log message, fixed duration, exit code, Docker healthcheck, HTTP probe,
168-
listening port; chained under one startup timeout.
192+
listening port, successful in-container command; chained under one startup timeout.
169193
- **Containers** — typed/raw `inspect`, `logs` (snapshot + streaming follow), `exec` (env / cwd /
170194
user / tty / stdin / detached / streaming), copy to/from, IPv4/IPv6 host-port getters.
171195
- **Networking & volumes** — user-defined `Network` (driver, IPAM, aliases) and named `Volume`
@@ -238,8 +262,9 @@ package on Linux, Windows, and macOS. The version lives in exactly one place —
238262
A ConanCenter-shaped recipe is staged verbatim in
239263
[`packaging/conan-center/`](packaging/conan-center/) (release-tarball sources pinned by sha256, no
240264
forced dependency options, verified against a fully compiled default Boost on gcc/clang/msvc). It is
241-
kept byte-in-sync with the in-repo `test_package/` by a CI check. Submission is planned right after
242-
the `v0.1.0` tag; the process and the recipe-vs-recipe split are documented in its
265+
kept byte-in-sync with the in-repo `test_package/` by a CI check. Submitted as
266+
[conan-io/conan-center-index#30600](https://github.com/conan-io/conan-center-index/pull/30600)
267+
(in review); the process and the recipe-vs-recipe split are documented in its
243268
[README](packaging/conan-center/README.md).
244269

245270
## History

0 commit comments

Comments
 (0)