Add DESIGN_PRINCIPLES #420
Conversation
| This documents aims to capture the design principles that went into this library. | ||
| It should serve as a reference point when making decisions on what features to include or exclude. | ||
|
|
||
| ## Simple |
There was a problem hiding this comment.
Loved this section, thanks for adding it!
|
|
||
| One of most important goals that we want to adhere to is creating a _simple_ API. | ||
| Overall, this means keeping the API as small as possible to get the task done. | ||
| When in doubt, we'd rather not add flags or configuration options for certain use cases. |
There was a problem hiding this comment.
This is a pretty big point, we like to emphasize for the Testcontainers project as a whole. Testcontainers does not intend to be a generic Docker client or a replacement for the Docker CLI. Instead, we follow an opinionated approach of providing APIs that make using best practices for integration testing easier.
While it is technically possible to map to fixed ports, or specify fixed container names, we believe that this feature is actually not necessary for the intended use cases of Testcontainers, hence we would hesitate to just add all Docker capabilities to the Testcontainers API, without a good reason for the integration testing context.
| When in doubt, we'd rather not add flags or configuration options for certain use cases. | ||
|
|
||
| Tests should be easier to write, easy to understand and easy to maintain. | ||
| `testcontainers` aims to support this as much as possible. |
There was a problem hiding this comment.
The umbrella project is called Testcontainers. The implementation for the individual languages is called Testcontainers for {$lang} and the repository is called testcontainers-${rust}.
In think in this instance, it is indeed referring to Testcontainers in general and to Testcontainers for Rust in particular 🙂
There was a problem hiding this comment.
I intended to refer to the crate name here :D
Would you like it to be rewritten?
| One consequence of this decision is that the container _tag_ is typically not configurable for images that ship with `testcontainers`. | ||
| Whilst an image behind a tag can also change, image authors tend to preserve compatibility there. | ||
| If we were to allow users to change the `tag` of an image, we wouldn't be able to guarantee that it works because we cannot test all combinations. |
There was a problem hiding this comment.
For this, we added the compatible substitute mechanism to Testcontainers for Java: https://www.testcontainers.org/features/image_name_substitution/#manual-substitution
There was a problem hiding this comment.
I am not sure if it is entirely the same. From these docs, I'd say the difference is that testcontainers for Rust doesn't even allow the following line:
DockerImageName.parse("mysql:8.0.24")
Co-authored-by: Andre Hofmeister <9199345+HofmeisterAn@users.noreply.github.com>
|
|
||
| The library should be easy to use. | ||
| For example, users should be able to make their own implementation of `Image` without much boilerplate. | ||
| In fact, the path forward may very well be that we stop shipping a lot of images in the crate and instead require users to create their own images. |
There was a problem hiding this comment.
I highly support this path forward. While yes, there's a lot of often-used containers, the fact anyone can use any container is really the key for me. I use oddball containers and would not expect to upstream them into this crate.
|
Sorry for the long delay, let's make use of this! I am merging this as a signal that we agree on what is in these principles. Help would be much appreciated in the form of:
|
No description provided.