feat: introduce container builder api by mbodmer · Pull Request #801 · testcontainers/testcontainers-rs

mbodmer · 2025-06-26T11:41:38Z

Here is a proposal for a builder API.

Please comment and help me improve it if there is interest for it.

resolves #478

netlify · 2025-06-26T11:42:26Z

✅ Deploy Preview for testcontainers-rust ready!

Name	Link
🔨 Latest commit	`1248621`
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-rust/deploys/687a5e30a1acce00087ce211
😎 Deploy Preview	https://deploy-preview-801--testcontainers-rust.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

DDtKey · 2025-06-26T12:59:59Z

Thank you for the contribution 🙏

That's really useful enhancement, I'll take a look soon

I think #478 can be addressed by this change

DDtKey · 2025-07-01T18:41:08Z

Also we could drop/rework our testimages subcrate and utilize the builder in our tests instead

It's better to do as follow-up, but it would be a good exercise to check everything is working

mbodmer · 2025-07-01T19:11:49Z

Also we could drop/rework our testimages subcrate and utilize the builder in our tests instead

It's better to do as follow-up, but it would be a good exercise to check everything is working

Yes, I think this would be a good idea, and I am willing to do this. But first I would like to hear whether the API as I have proposed for now is going in the direction you imagine.

DDtKey · 2025-07-16T16:13:58Z

@mervyn-mccreight may I ask you to take a look at the design too, please?

This PR is extremely useful and I don't want the job to be lost, we need to finalize it

mbodmer · 2025-07-16T20:09:55Z

Would be happy if this and the follow up #804 could be finalized soon, as long as I still remember what I did here :-) Willing to help if anything is missing

mervyn-mccreight

I think it's a good starting point, well done!
I left a few questions that I was wondering about and couldn't find an answer to by myself

testcontainers/src/core/copy.rs

testcontainers/src/runners/sync_runner.rs

mervyn-mccreight · 2025-07-17T11:32:34Z

Thanks for your detailed replies :) I resolved everything, because it's clear to me now.
@DDtKey I'm quite happy with the design, WDYT?

mbodmer · 2025-07-17T11:47:20Z

Thanks for your review.

DDtKey · 2025-07-17T23:56:32Z

Few PRs have been merged (e.g bollard update), could you update the branch and solve conflicts?

Only append to the archive to make the functions reusable in a context of multiple sources in a single archive. Signed-off-by: mbodmer <marc.bodmer@email.ch>

This type will allow for uploading of multiple files and directories in a single tar -> e.g: a docker build context Signed-off-by: mbodmer <marc.bodmer@email.ch>

Signed-off-by: mbodmer <marc.bodmer@email.ch>

To be usable in a library like testcontainer modules we need the core::copy structs to be accessible on the api. Signed-off-by: Marc Bodmer <marc.bodmer@securiton.ch>

Signed-off-by: mbodmer <marc.bodmer@email.ch>

lazy_sync_runner() is now also used by the sync_builder thus it cannot be private anymore. But we don't have to expose it as public API. Signed-off-by: mbodmer <marc.bodmer@email.ch>

Signed-off-by: Marc Bodmer <marc.bodmer@securiton.ch>

mbodmer · 2025-07-18T09:22:41Z

Ok, too bad. Merging was quite a pain and I hope I've not introduced some unintended side effects. Please lets rush with #804, I'd not be really happy having too many conflicts there again.

Signed-off-by: mbodmer <marc.bodmer@email.ch>

Signed-off-by: Marc Bodmer <marc.bodmer@securiton.ch>

DDtKey

Thank you for your contribution! 🚀

I appreciate the effort and don’t see any reason to block this.
We can always revisit the design based on user experience.

As a follow-up, I would greatly appreciate comprehensive documentation coverage. Otherwise, people might not be aware of this feature that has been delivered.

mbodmer · 2025-07-18T19:07:43Z

Yes, I also think documentation would be needed. I will try to improve on it in a later effort, right now I am not in the mood for this :-). But I really see the importance.

mervyn-mccreight · 2025-07-18T23:10:48Z

I'd say lets merge it and do the documentation in a later PR :)
It's more than enough to go through merge pain once (thanks for doing that!)

This PR is based on feat/build-image from PR: #801 --------- Signed-off-by: mbodmer <marc.bodmer@email.ch> Signed-off-by: Marc Bodmer <marc.bodmer@securiton.ch>

## 🤖 New release * `testcontainers`: 0.24.0 -> 0.25.0 (⚠ API breaking changes) ### ⚠ `testcontainers` breaking changes ```text --- failure enum_variant_added: enum variant added on exhaustive enum --- Description: A publicly-visible enum without #[non_exhaustive] has a new variant. ref: https://doc.rust-lang.org/cargo/reference/semver.html#enum-variant-new impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.41.0/src/lints/enum_variant_added.ron Failed in: variant ClientError:BuildImage in /tmp/.tmp8ymZuo/testcontainers-rs/testcontainers/src/core/client.rs:71 variant ClientError:BuildImage in /tmp/.tmp8ymZuo/testcontainers-rs/testcontainers/src/core/client.rs:71 variant LogSource:BothStd in /tmp/.tmp8ymZuo/testcontainers-rs/testcontainers/src/core/logs.rs:32 --- failure trait_method_added: pub trait method added --- Description: A non-sealed public trait added a new method without a default implementation, which breaks downstream implementations of the trait ref: https://doc.rust-lang.org/cargo/reference/semver.html#trait-new-item-no-default impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.41.0/src/lints/trait_method_added.ron Failed in: trait method testcontainers::core::ImageExt::with_ready_conditions in file /tmp/.tmp8ymZuo/testcontainers-rs/testcontainers/src/core/image/image_ext.rs:184 trait method testcontainers::core::ImageExt::with_health_check in file /tmp/.tmp8ymZuo/testcontainers-rs/testcontainers/src/core/image/image_ext.rs:206 trait method testcontainers::ImageExt::with_ready_conditions in file /tmp/.tmp8ymZuo/testcontainers-rs/testcontainers/src/core/image/image_ext.rs:184 trait method testcontainers::ImageExt::with_health_check in file /tmp/.tmp8ymZuo/testcontainers-rs/testcontainers/src/core/image/image_ext.rs:206 ``` <details><summary>Changelog</summary> <blockquote> ## [0.25.0] - 2025-07-27 ### Details #### Bug Fixes - Make tls features optional ([#806](#806)) - Add `Send` trait to `stderr` & `stdout` of `ExecResult` ([#809](#809)) - Added new parse rule for correctly parsing ports without protocol specifier ([#812](#812)) #### Features - Allow ready conditions customization via ImageExt ([#794](#794)) - Allow to wait for log line on either stdout or stderr ([#795](#795)) - Add `Container*::exit_code` ([#791](#791)) - Add `Container*::is_running` ([#790](#790)) - Add custom health check support for containers ([#816](#816)) - Introduce container builder api ([#801](#801)) #### Miscellaneous Tasks - [❗] Update bollard to 1.19.1 ([#817](#817)) #### Refactor - Testimages and tests to use builder API ([#804](#804)) </blockquote> </details> --- This PR was generated with [release-plz](https://github.com/release-plz/release-plz/). Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

mbodmer force-pushed the feat/build-image branch from 4b918d9 to 405aab8 Compare July 1, 2025 19:10

mbodmer mentioned this pull request Jul 2, 2025

refactor: testimages and tests to use builder API #804

Merged

mervyn-mccreight reviewed Jul 17, 2025

View reviewed changes

testcontainers/src/core/copy.rs Show resolved Hide resolved

testcontainers/src/core/copy.rs Show resolved Hide resolved

testcontainers/src/runners/sync_runner.rs Outdated Show resolved Hide resolved

mbodmer and others added 12 commits July 18, 2025 10:29

refactor: Factor out tar archive creation in CopyDataSource

0ba58c4

Only append to the archive to make the functions reusable in a context of multiple sources in a single archive. Signed-off-by: mbodmer <marc.bodmer@email.ch>

feat: add CopyToContainerCollection

6ae3212

This type will allow for uploading of multiple files and directories in a single tar -> e.g: a docker build context Signed-off-by: mbodmer <marc.bodmer@email.ch>

feat: add build_image() to client

0677faf

Signed-off-by: mbodmer <marc.bodmer@email.ch>

feat: add buildable trait and async builder

e57eb5d

Signed-off-by: mbodmer <marc.bodmer@email.ch>

fix: fix build options and use buildkit

587db3c

Signed-off-by: mbodmer <marc.bodmer@email.ch>

feat: add SyncBuilder

31f1efc

Signed-off-by: mbodmer <marc.bodmer@email.ch>

revert: uses needed with --all-features

f0a2342

Signed-off-by: mbodmer <marc.bodmer@email.ch>

chore: satisfy rustfmt

29b380c

Signed-off-by: mbodmer <marc.bodmer@email.ch>

refactor: make copy structs public

b7178eb

To be usable in a library like testcontainer modules we need the core::copy structs to be accessible on the api. Signed-off-by: Marc Bodmer <marc.bodmer@securiton.ch>

refactor: Add BuildContextBuilder to replace public copy::*

9ed35e2

Signed-off-by: mbodmer <marc.bodmer@email.ch>

fix: make lazy_sync_runner() pub(crate)

7a55e40

lazy_sync_runner() is now also used by the sync_builder thus it cannot be private anymore. But we don't have to expose it as public API. Signed-off-by: mbodmer <marc.bodmer@email.ch>

fix: fix code after merging

f3c5c9d

Signed-off-by: Marc Bodmer <marc.bodmer@securiton.ch>

mbodmer force-pushed the feat/build-image branch from 39683fd to f3c5c9d Compare July 18, 2025 09:19

mbodmer and others added 2 commits July 18, 2025 14:33

fix: improve debugability for image building

4d9fcd5

Signed-off-by: mbodmer <marc.bodmer@email.ch>

fix: rustfmt

1248621

Signed-off-by: Marc Bodmer <marc.bodmer@securiton.ch>

DDtKey approved these changes Jul 18, 2025

View reviewed changes

mervyn-mccreight changed the title ~~feat: builder API proposal~~ feat: introduce container builder api Jul 19, 2025

mervyn-mccreight merged commit 99d746e into testcontainers:main Jul 19, 2025
18 checks passed

github-actions bot mentioned this pull request Jul 27, 2025

chore: release v0.25.0 #823

Merged

DDtKey mentioned this pull request Sep 22, 2025

rustls/ring is always active even with aws-lc-rs feature #843

Closed

Comments

Conversation

mbodmer commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for testcontainers-rust ready!

Uh oh!

DDtKey commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DDtKey commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mbodmer commented Jul 1, 2025

Uh oh!

DDtKey commented Jul 16, 2025

Uh oh!

mbodmer commented Jul 16, 2025

Uh oh!

mervyn-mccreight left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mervyn-mccreight commented Jul 17, 2025

Uh oh!

mbodmer commented Jul 17, 2025

Uh oh!

DDtKey commented Jul 17, 2025

Uh oh!

mbodmer commented Jul 18, 2025

Uh oh!

DDtKey left a comment

Choose a reason for hiding this comment

Uh oh!

mbodmer commented Jul 18, 2025

Uh oh!

mervyn-mccreight commented Jul 18, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mbodmer commented Jun 26, 2025 •

edited

Loading

netlify bot commented Jun 26, 2025 •

edited

Loading

DDtKey commented Jun 26, 2025 •

edited

Loading

DDtKey commented Jul 1, 2025 •

edited

Loading