Re-work public API to be Container centric

[thomaseizinger]

Since its inception, testcontainers-rs had an API that focused on first creating a Client before one could run a Container. This was deemed acceptable as a Client is typically only created once at the top of the test.

Recent feature requests such as #354, show some of the limitations of this API. One of the primary design goals of testcontainers-rs is to have a really small API such that creating and running a new container is as easy as possible.

To accommodate feature requests such as #354 but still adhere to this design goal, I am thinking to re-design the API to something like this:

use testcontainers::RunViaCli; // Extension trait for running an image using the `Cli` client.

let container = MyImage::default().run();

use testcontainers::RunViaHttp; // Extension trait for running an image using the `Http` client.

let container = MyImage::default().run().await;

The client would be started on-demand and kept in a global variable with a Weak reference so that it shuts down once all containers are gone. The client itself would likely be made completely private to the crate to further reduce the public API (which allows us to make more changes without breaking compatibility).

We'd have to flesh out some details on how to configure the individual clients if they can no longer be constructed directly but that is not too important for this topic.

// CC several people who had issues with the current API in the past: @soulseekeer24 @lcmgh @marlon-sousa @jhershberg @pronvis @ufoscout

Any feedback / input on this idea is much appreciated.

[marlon-sousa]

Hello,

I strongly encourage this implementation.

While this crate was aimed at isolated tests, it is too good and people's needs (beyond this should be this or that way) are too extensive. All the needs can take advantage of this crate should the proposed architecture be implemented.

Real life some times goes further than what "important people", personal believes or famous theories have to say, mature environments should consider all, and I mean really all things a matter of trade offs ratter than right or wrong.

This said, the proposed change will allow a vast range of testing needs to succeed, using an ergonomic, fast and well encapsulated strategy. Everyone wins, nobody is left behind and, independently of what we think testing should be like, everyone can just use the crate for whatever strategies they need to use. This is what a really good crate should be, and your crate just happens to be great, otherwise people would just switch for shell scripts or for invoking process around using std::process::Command instead of coming here and asking for help.

I for example am running a set of integration tests that run sequentially and all use the same database, thus I need to start a container when tests start to work and stop it when the suite ends.

I tried to encapsulate the client and the containers created by this client together, because I wanted to provide a encapsulated interface to the test engine where one just need to start the containers and either stop them or let drop do it when tests ended.

Independently of what "important people" or "important books" say, this is the best strategy for this specific scenarios, I am confident, and so are my team members given the requirements we have. Being able to transparently use the crate on this strategy would really be great. This would also not break the isolation scenarios, which I and others can very well use when appropriate.

[endertunc]

Is anyone actively working on this issue?

As personal side project, I am currently re-writing this repository in more container-centric way. I am getting inspiration from both testcontainers-go and testcontainers-node which uses very similar container-centric design/approach.

Probably it's a bit premature to ask this but I was wondering if Re-work public API could also be interpreted as re-write?

Current work I am doing would basically be a new library and I was wondering how would people react to such dramatic update. We might be able to find middle ground at some point but I just wanted to test the water.

[thomaseizinger]

Is anyone actively working on this issue?

No.

As personal side project, I am currently re-writing this repository in more container-centric way. I am getting inspiration from both testcontainers-go and testcontainers-node which uses very similar container-centric design/approach.

Probably it's a bit premature to ask this but I was wondering if Re-work public API could also be interpreted as re-write?

I don't think anything around the Image trait needs to change and neither do the clients. "All" we need is invert the dependency between clients and containers by transparently starting the client in the background. My first idea would have been to keep it in a thread-local or static variable and use Arc + Weak to check how many copies of the client are still alive (inside running Containers).

Current work I am doing would basically be a new library and I was wondering how would people react to such dramatic update. We might be able to find middle ground at some point but I just wanted to test the water.

I think it makes sense to be compatible with the Image trait.

[thomaseizinger]

In general though, I am open to big PRs / re-writes although I'd prefer if they are broken down into smaller ones and that we have a reasonable upgrade path for users.

Meta: If we end up landing such a series of PRs where you wrote most / all of the code, I think it makes sense to also make you a maintainer :)

[endertunc]

Hi @thomaseizinger thanks for your reply. I will try to discover the possibilities you mentioned before going full re-write 👍 re-writes are never a good idea anyway :)

[blandger]

Any progress on issue ?? Is it still in draft by #503 ? just curious...

[thomaseizinger]

Any progress on issue ?? Is it still in draft by #503 ? just curious...

Yes. What is on GitHub is the current state :)
Nobody is actively working on this to my knowledge.

[endertunc]

I was suppose to follow up on the draft but life happened so I didn't have much time to look in to it. I will try to make some time for it and let's see how far we can go 👍

[DDtKey]

JFYI: we gonna deprecate the Cli client (#563), and I'd like to actualize this proposal.