From 999bad8a4fd00d1f92f83dfb58f7526b709cd96f Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger <43503240+paullatzelsperger@users.noreply.github.com> Date: Mon, 3 Jul 2023 08:20:30 +0200 Subject: [PATCH] docs: add decision record about using Testcontainers (#3255) --- .../README.md | 23 +++++++++++++++++++ docs/developer/decision-records/README.md | 1 + docs/developer/testing.md | 19 ++++++++------- 3 files changed, 33 insertions(+), 10 deletions(-) create mode 100644 docs/developer/decision-records/2023-06-30-allow-use-of-testcontainers/README.md diff --git a/docs/developer/decision-records/2023-06-30-allow-use-of-testcontainers/README.md b/docs/developer/decision-records/2023-06-30-allow-use-of-testcontainers/README.md new file mode 100644 index 00000000000..10e93711167 --- /dev/null +++ b/docs/developer/decision-records/2023-06-30-allow-use-of-testcontainers/README.md @@ -0,0 +1,23 @@ +# Allow and regulate the usage of Testcontainers + +## Decision + +Using Testcontainers is henceforth allowed, and it is the preferred way to integration-test with third-party software +components. + +## Rationale + +Testcontainers are a self-contained way to run tests against real third-party software products, such as Postgres. Up +until now the EDC guideline was to separate test code from infrastructure, but this rule is now relaxed in that +integration tests may now use Testcontainers. + +However, this does _not_ mean that we should use component tests or integration tests for everything. Or: unit tests are +still the preferred way to test software components, they should continue to make up the largest part of our test code +base. + +## Approach + +- Every test that uses a Testcontainer must be annotated either with `@ComponentTest` or another suitable integration + test annotation. So when tests are run locally on developers' machines by default only unit tests are executed. +- New integration/component tests should use Testcontainers +- Existing component/integration tests are gradually converted over to using Testcontainers diff --git a/docs/developer/decision-records/README.md b/docs/developer/decision-records/README.md index 462a38de37b..029975ea467 100644 --- a/docs/developer/decision-records/README.md +++ b/docs/developer/decision-records/README.md @@ -65,3 +65,4 @@ - [2023-06-05-validation-engine](2023-06-05-validation-engine) - [2023-06-19-change-of-github-labels](2023-06-19-new-issue-triage-process/) - [2023-06-19-onboarding-contributors](2023-06-19-onboarding-contributors/) +- [2023-06-30-allow-use-of-testcontainers](2023-06-30-allow-use-of-testcontainers/) diff --git a/docs/developer/testing.md b/docs/developer/testing.md index d36e399d906..f516ebdb7d3 100644 --- a/docs/developer/testing.md +++ b/docs/developer/testing.md @@ -92,16 +92,15 @@ can also be supplied via system properties. There is no one-size-fits-all guideline whether to perform setup tasks in the `@BeforeAll` or `@BeforeEach`, it will depend on the concrete system you're using. As a general rule of thumb long-running one-time setup should be done in the `@BeforeAll` so as not to extend the run-time of the test unnecessarily. In contrast, in most cases it is **not** -advisable to deploy/provision the external system itself in either of those methods. In other words, provisioning a -CosmosDB or spinning up a Postgres docker container directly from test code should generally be avoided, because it will -introduce code that has nothing to do with the test and may cause security problems (privilege escalation through the -Docker API), etc. - -This does not at all discourage the use of external test environments like containers, rather, the external system -should be deployed in the CI script (e.g. through Github's `services` feature), or there might even be a dedicated test -instance running continuously, e.g. a CosmosDB test instance in Azure. In the latter case we need to be careful to avoid -conflicts (e.g. database names) when multiple test runners access that system simultaneously and to properly clean-up -any residue before and after the test. +advisable to deploy/provision the external system itself in either of those methods. In other words, manually +provisioning a CosmosDB or spinning up a Postgres docker container directly from test code should generally be avoided, +because it will introduce code that has nothing to do with the test and may cause security problems (privilege +escalation through the Docker API), etc. + +Specifically, if possible all external system should be deployed using [Testcontainers](https://testcontainers.com/). +Alternatively, in special situations there might be a dedicated test instance running continuously, e.g. a CosmosDB test +instance in Azure. In the latter case please be careful to avoid conflicts (e.g. database names) when multiple test +runners access that system simultaneously and to properly clean up any residue before and after the test. ### Running them locally