Testcontainers

I did not come in here expecting to read such effusive praise for testcontainers. If you’re coming from a place where docker wasn’t really a thing I can see how it looks beautiful. And in a fair amount of use cases it can be really nice. But if you want it to play well with any other containerized workflow, good freaking luck.<p>Testcontainers is <i>the</i> library that convinced me that shelling out to docker as an abstraction via bash calls embedded in a library is a bad idea. Not because containerization as an abstraction is a bad idea. Rather it’s that having a library that custom shell calls to the docker CLI as part of its core functionality creates problems and complexity as soon as one introduces other containerized workflows. The library has the nasty habit of assuming it’s running on a host machine and nothing else docker related is running, and footguns itself with limitations accordingly. This makes it not much better than some non dockerized library in most cases and oftentimes much much worse.

Test containers is such a game changer for integration testing, they have language specific docker apis that make it trivial to bring up containers and verify that they are fully initialized and ready to accept connections.<p>Pretty much every project I create now has testcontainers for integration testing :)<p>I setup CI so it lints, builds, unit tests then integration tests (using testcontainers)<p><a href="https:&#x2F;&#x2F;github.com&#x2F;turbolytics&#x2F;latte&#x2F;blob&#x2F;main&#x2F;.github&#x2F;workflows&#x2F;ci.yml#L22">https:&#x2F;&#x2F;github.com&#x2F;turbolytics&#x2F;latte&#x2F;blob&#x2F;main&#x2F;.github&#x2F;workf...</a><p>Their language bindings provide nice helper functions for common database operations (like generating a connection uri from a container user)<p><a href="https:&#x2F;&#x2F;github.com&#x2F;turbolytics&#x2F;latte&#x2F;blob&#x2F;main&#x2F;internal&#x2F;source&#x2F;metric&#x2F;mongodb&#x2F;integration_test.go#L16">https:&#x2F;&#x2F;github.com&#x2F;turbolytics&#x2F;latte&#x2F;blob&#x2F;main&#x2F;internal&#x2F;sour...</a><p>I use them in $day job use them in side projects use them everywhere :)

Not sure how I hadn&#x27;t encountered this before, I LOVE this pattern.<p>I find integration tests that exercise actual databases&#x2F;Elasticsearch&#x2F;Redis&#x2F;Varnish etc to be massively more valuable than traditional unit tests. In the past I&#x27;ve gone to pretty deep lengths to do things like spin up a new Elasticsearch index for the duration of a test suite and spin it down again at the end.<p>It looks like Testcontainers does all of that work for me.<p>My testing strategy is to have as much of my application&#x27;s functionality covered by proper end-to-end integration-style tests as possible - think tests that simulate an incoming HTTP request and then run assertions against the response (and increasingly Playwright-powered browser automation tests for anything with heavy JavaScript).<p>I&#x27;ll use unit tests sparingly, just for the bits of my code that have very clear input&#x2F;output pairs that afford unit testing.<p>I only use mocks for things that I don&#x27;t have any chance of controlling - calls to external APIs for example, where I can&#x27;t control if the API provider will be flaky or not.

I didn&#x27;t quite understand why this was made. We create our local test environments using docker-compose, and so I read:<p>&gt; Creating reliable and fully-initialized service dependencies using raw Docker commands or using Docker Compose requires good knowledge of Docker internals and how to best run specific technologies in a container<p>This sounds like a &lt;your programming language&gt; abstraction over docker-compose, which lets you define your docker environment without learning the syntax of docker-compose itself. But then<p>&gt; port conflicts, containers not being fully initialized or ready for interactions when the tests start, etc.<p>means you&#x27;d still need a good understanding of docker networking, dependencies, healthchecks to know if your test environment is ready to be used.<p>Am I missing something? Is this basically change what&#x27;s starting your docker test containers?

I looked at testcontainers and ended up rolling my own version. One issue I had is that Docker is a very leaky abstraction. I needed to write one test and have it run in all these scenarios:<p>- on a Mac<p>- on a Linux VM<p>- in a Docker container on a Linux VM, with a Docker socket mounted<p>The networking for each of these is completely different. I had to make some opinionated choices to get code that could run in all cases. And running inside Docker prevented the test from being able to mount arbitrary files into the test containers, which turns out to be a requirement often. I ended up writing code to build a new image for each container, using ADD to inject files.<p>I also wanted all the tests to run in parallel and spit out readable logs from every container (properly associated with the correct test).<p>Not sure if any of these things have changed in testcontainers since I last looked, but these are the things I ran into. It took maybe a month of off and on tweaking, contrary to some people here claiming it can be done in an hour. As always, the devil is in the details.<p>edit: I did end up stealing ryuk. That thing can’t really be improved upon.

&gt; No more need for mocks or complicated environment configurations. Define your test dependencies as code, then simply run your tests and containers will be created and then deleted.<p>Wait what? They think you don&#x27;t need unit tests because you can run integration tests with containers?<p>It&#x27;s trivial to set up a docker container with one of your dependencies, but starting containers is painful and slow.

<p><pre><code> Testcontainers is awesome and all the hate it gets here is undeserved. Custom shell scripts definitely can&#x27;t compete. For example one feature those don&#x27;t have is &quot;Ryuk&quot;: A container that testcontainers starts which monitors the lifetime of the parent application and stops all containers when the parent process exits. It allows the application to define dependencies for development, testing, CI itself without needing to run some command to bring up docker compose beforehand manually. One cool usecase for us is also having a ephemeral database container that is started in a Gradle build to generate jOOQ code from tables defined in a Liquibase schema.</code></pre>

I dont understand how this is better than a docker-compose.yml with your dependencies, which plays nicer with all other tooling.<p>Especially if there are complex dependencies between required containers it seems to be pretty weak in comparison. But i also only used it like 5 years ago, so maybe things are significantly better now.

Pulling up infra to run unit tests is an anti-pattern. This is a great tool for integration tests, though.

Its great but I find it harder to debug. And I have to say, I usually dont need it. Typically i just have some command which spins everything up from docker-compose files. I prefer this over putting configuration in code like you often do with test containers. You can also load from docker compose files but at that point the test container API isn’t really doing much.<p>Its pretty much required when you want to setup&#x2F;teardown in between tests though. This just usually isnt the case for me.

I&#x27;ve been using Docker containers for integration testing for last few years. I usually roll my own custom solution in Go using the <a href="https:&#x2F;&#x2F;github.com&#x2F;ory&#x2F;dockertest">https:&#x2F;&#x2F;github.com&#x2F;ory&#x2F;dockertest</a> package though that adds necessary functionality around running migrations, creating kafka topics, or similar. Will definitely need to check out this next time I&#x27;m writing a test package

I was intrigued to see that they have PyPI packages for a ton of different things - like <a href="https:&#x2F;&#x2F;pypi.org&#x2F;project&#x2F;testcontainers-postgres" rel="nofollow">https:&#x2F;&#x2F;pypi.org&#x2F;project&#x2F;testcontainers-postgres</a><p>That wheel file is only 2.9KB, so I grabbed a copy to see how it works. I&#x27;ve put the contents in a Gist here: <a href="https:&#x2F;&#x2F;gist.github.com&#x2F;simonw&#x2F;c53f80a525d573533a730f5f28858f84" rel="nofollow">https:&#x2F;&#x2F;gist.github.com&#x2F;simonw&#x2F;c53f80a525d573533a730f5f28858...</a><p>It&#x27;s pretty neat - it depends on testcontainers-core, sqlalchemy and psycopg2-binary and then defines a PostgresContainer class which fires up a &quot;postgres:latest&quot; container and provides a helper function for getting the right connection URL.

You can do something similar with docker compose, driving the system from the outside. Create dockerized versions of dependencies like the database, build and run tests, and then run tests against the production app container. It&#x27;s particularly useful for testing a set of microservices.<p>See <a href="https:&#x2F;&#x2F;github.com&#x2F;cogini&#x2F;phoenix_container_example">https:&#x2F;&#x2F;github.com&#x2F;cogini&#x2F;phoenix_container_example</a> for a full example. This blog post describes it in detail: <a href="https:&#x2F;&#x2F;www.cogini.com&#x2F;blog&#x2F;breaking-up-the-monolith-building-testing-and-deploying-microservices&#x2F;" rel="nofollow">https:&#x2F;&#x2F;www.cogini.com&#x2F;blog&#x2F;breaking-up-the-monolith-buildin...</a>

This is a very nice project, but it&#x27;s awful that they&#x27;re blurring the line of unit test and integration test. They are very different and both very important.<p>Things in the software world are very trendy. If this starts a trend of making people think that they&#x27;re writing unit tests when they are writing integrations tests, we are fucked.<p>If I need to change code that you wrote I need a lightning fast way to figure out that I haven&#x27;t broken your code according to the tests that you wrote. That&#x27;s unit tests.<p>My changes might break the whole system. That&#x27;s integration tests. I just to run that once and then I can go back to unit tests while I fix the mess I&#x27;ve made.

If your project uses Nix, checkout services-flake for running services via Nix.<p><a href="https:&#x2F;&#x2F;github.com&#x2F;juspay&#x2F;services-flake">https:&#x2F;&#x2F;github.com&#x2F;juspay&#x2F;services-flake</a><p>We actually do this in Nammayatri, an OSS project providing &quot;Uber&quot; for autos in India.<p><a href="https:&#x2F;&#x2F;github.com&#x2F;nammayatri&#x2F;nammayatri">https:&#x2F;&#x2F;github.com&#x2F;nammayatri&#x2F;nammayatri</a><p>There is a services-flake module allowing you to spin the entire nammayatri stack (including postgres, redis, etc.) using a flake app. Similarly, there&#x27;s one for running load test, which is also run in Jenkins CI.

Unit test suppose to be fast. Especially during coding. I wonder how this is necessary &amp; not affecting the test feedback speed

I read through the docs and am still confused about what this actually does beyond running a single docker run command in the background and returning control to your code when the container is up.

Reading through the comments, I&#x27;m quite shocked to see how many deterrent conversations are happening without any understanding of the underlying tech stacks being tested. Testcontainers can be fantastic, especially when you are facing test environment overhead challenges, <i>assuming</i> you have the appropriate architectures &#x2F; service boundaries to support it. I believe there is more code out there in existence with architectures that make using Testcontainers more challenging than it is worth.

I see testcontainers being used in tests making the test code style feel more like typical unit tests with fake implementations for system components. Which is misleading as these are more on the integration testing side typically. In essence this is another DSL (per language) for managing containers locally. And this DSL comes in addition to whatever system is actually used for managing containers in production for the project.

Something that improved developer experience by far and also sped up our builds is starting the container dependencies via docker-compose and connect to it for integration testing. This allows reuse of containers, you can connect to it after&#x2F;during an integration test to debug without having to keep searching for ports constantly.<p>With TestContainers - I&#x27;ve perceived that running integration tests &#x2F; a single test repeatedly locally is extremely slow as the containers are shut down when the java process is killed. This approach allows for this while also allowing to keep it consistent - example, just mount the migrations folder in the start volume of your DB container and you have a like-for-like schema of your prod DB ready for integration tests.<p>I&#x27;ve found the <a href="https:&#x2F;&#x2F;github.com&#x2F;avast&#x2F;gradle-docker-compose-plugin&#x2F;">https:&#x2F;&#x2F;github.com&#x2F;avast&#x2F;gradle-docker-compose-plugin&#x2F;</a> very useful for this.

I think it’s a step in the right direction. There’s probably a few uses cases where the dependent system is configured much differently in your “test container” vs production instance. But if the aim is to programmatically spin up dependencies and provide 99% guarantee that your app&#x2F;workflows will work, then this seems it can do the job.<p>One small note: test run time will probably increase. If a person has an outdated computer, I suspect they will have a hard time running the IT suite. Especially if it’s a complicated system with more than one dependency.

&gt; Each test gets a fresh, clean instance of the browser, without having to worry about variations in plugins or required updates.<p>Except where everyone is saying that&#x27;s too slow and instead they have a long-lived instance which they manually teardown each time. That&#x27;s even what the examples do (some, at least, I didn&#x27;t check them all).<p>If you&#x27;ve already bought into the container world then why not embrace a few more. For everyone else, not sure there&#x27;s much point in extra complexity (they call it simplicity) or bloat.

Wow ... the syntax reminds me so much of aspire (microsoft new &quot;composer&quot;-syntax). Makes a lot of sense.<p>Why not keep this information in code .. often the developers are ending up doing those task anyway. (not recommended .. but seen it so many times)<p>Link: Microsoft aspire (<a href="https:&#x2F;&#x2F;learn.microsoft.com&#x2F;en-us&#x2F;dotnet&#x2F;aspire&#x2F;get-started&#x2F;aspire-overview" rel="nofollow">https:&#x2F;&#x2F;learn.microsoft.com&#x2F;en-us&#x2F;dotnet&#x2F;aspire&#x2F;get-started&#x2F;...</a>)

I found test containers to be slow to startup last year. It wasn’t worth the effort considering how long it took to run compared to traditional spring IT h2 hibernate.

If you build inside docker, running tests that use docker is a pain.<p>Go has a lot of in-memory versions of things for tests, which run so much quicker than leaning on docker. Similarly, I found C# has in-memory versions of deps you can lean on.<p>I really feel that test containers, although solving a problem, often introduces others for no great benefit

&gt; <i>Unit tests with real dependencies</i><p>That&#x27;s an integration test. These are integration tests. You&#x27;re literally testing multiple units (e.g., Redis, and the thing using Redis) to see if they&#x27;re integrating.<p>Why do we even have words.<p>These are valuable in their own right. They&#x27;re just complicated &amp; often incredibly slow compared to a unit test. Which is why I prefer mocks, too: they&#x27;re speedy. You just have to get the mock right … and that <i>can</i> be tricky, particularly since some APIs are just woefully underdocumented, or the documentation is just full of lies. But the mocks I&#x27;ve written in the past steadily improve over time. Learn to stop worrying, and love each for what they are.<p>(Our CI system actually used to pretty much directly support this pattern. Then we moved to Github Actions. GHA has &quot;service containers&quot;, but unfortunately the feature is too basic to address real-world use cases: it assumes a container image can just … boot! … and only talk to the code via the network. Real world use cases often require serialized steps between the test &amp; the dependencies, e.g., to create or init database dirs, set up certs, etc.)

I see a lot of people commenting to use docker-compose instead.<p>Testcontainers does have a docker compose integration [1].<p>1. <a href="https:&#x2F;&#x2F;java.testcontainers.org&#x2F;modules&#x2F;docker_compose&#x2F;" rel="nofollow">https:&#x2F;&#x2F;java.testcontainers.org&#x2F;modules&#x2F;docker_compose&#x2F;</a>

I tried to use Testcontainers just last week but ended up using simple docker commands instead. I didn’t find an easy way to connect an already running set of containers started via docker compose. Was straightforward to do with a set of scripts that just call docker exec.

About 7 years ago I wrote conex, which is basically testcontainers for Go, with first class integration with the Go&#x27;s official testing framework:<p><a href="https:&#x2F;&#x2F;github.com&#x2F;omeid&#x2F;conex">https:&#x2F;&#x2F;github.com&#x2F;omeid&#x2F;conex</a>

I am using <a href="https:&#x2F;&#x2F;github.com&#x2F;ory&#x2F;dockertest">https:&#x2F;&#x2F;github.com&#x2F;ory&#x2F;dockertest</a> for tests, specifically for databases. Is there any advantage to use Testcontainers?

This looks pretty useful! Question on the nginx container. For my tests, this container is only useful when files are mounted into the container. For example, it needs an nginx.conf passed in. How do I do this with NginxContainer?

Yes [1].<p>1. <a href="https:&#x2F;&#x2F;www.atomicjar.com&#x2F;2023&#x2F;06&#x2F;running-testcontainers-tests-using-github-actions&#x2F;" rel="nofollow">https:&#x2F;&#x2F;www.atomicjar.com&#x2F;2023&#x2F;06&#x2F;running-testcontainers-tes...</a>

Somewhat related: anyone here using AWS Neptune graphql database? How do you develop locally against Neptune? Apart from Localstack, is there a way to mock Neptune for local testing and development?

My team maintain a lot of flink connectors, We&#x27;ve changed external test resources to testcontainer as much as possible, it makes things simple and saves money as well.

Interesting. I would say this should not be any close to the &quot;unit test&quot;, but I see it doesn&#x27;t matter anymore.

Integrated this in an afternoon. It was surprisingly simple and works great locally and also inside GitHub actions to do psql integration tests of our core app.

Never heard of this, also the label in footer for careers said &quot;We&#x27;re hiring&quot; but then lists no open positions :&#x2F;

Does this work with podman or is it docker only?

Forgive the question... but... why can&#x27;t &#x27;test&#x27; containers be &#x27;prod&#x27; containers?

Can I run this in GitHub Actions?

No thanks, I will continue to roll my own to control it full, at home and at work.

Duke as the logo for java?

I&#x27;m surprised this is getting so much attention. I thought this just standard practice at this point? If you use things like Gitlab CI then you get this via the `services` in your pipeline. The CI job itself runs in a container too.<p>I use a very similar thing via pytest-docker: <a href="https:&#x2F;&#x2F;github.com&#x2F;avast&#x2F;pytest-docker">https:&#x2F;&#x2F;github.com&#x2F;avast&#x2F;pytest-docker</a> The only difference seems to be you declare your containers via a docker-compose file which I prefer because it&#x27;s a standard thing you can use elsewhere.

I never really liked testcontainers. Too complicated. And I don&#x27;t want to have my tests make too many assumptions about what level of control there is over their environment. IMHO it&#x27;s just the wrong place to be messing with docker.<p>I don&#x27;t like layering abstractions on top of abstractions that were fine to begin with. Docker-compose is pretty much perfect for the job. An added complexity is that the before&#x2F;after semantics of the test suite in things like JUnit are a bit handwavy and hard to control. Unlike testng, there&#x27;s no @BeforeSuite (which is really what you want). The @BeforeAll that junit has is actually too late in the process to be messing around with docker. And more importantly, if I&#x27;m developing, I don&#x27;t want my docker containers to be wasting time restarting in between tests. That&#x27;s 20-30 seconds I don&#x27;t want to add on top of the already lengthy runtime of compiling&#x2F;building, firing up Spring and letting it do it&#x27;s thing before my test runs in about 1-2 seconds.<p>All this is trivially solved by doing docker stuff at the right time: before your test process starts.<p>So, I do that using good old docker compose and a simple gradle plugin that calls it before our tests run and then again to shut it down right after. If it&#x27;s already running (it simply probes the port) it skips the startup and shut down sequence and just leaves it running. It&#x27;s not perfect but it&#x27;s very simple. I have docker-compose up most of my working day. Sometimes for days on end. My tests don&#x27;t have to wait for it to come up because it&#x27;s already up. On CI (github actions), gradle starts docker compose, waits for it to come up, runs the tests, and then shuts it down.<p>This has another big advantage that the process of running a standalone development server for manual testing, running our integration tests, and running our production server are very similar. Exactly the same actually; the only difference configuration and some light bootstrapping logic (schema creation). Configuration basically involves telling our server the hosts and ports of all the stuff it needs to run. Which in our case is postgres, redis, and elasticsearch.<p>Editing the setup is easy; just edit the docker compose and modify some properties. Works with jvm based stuff and it&#x27;s equally easy to replicate with other stuff.<p>There are a few more tricks I use to keep things fast. I have ~300 integration tests that use db, redis, and elasticsearch. They run concurrently in under 1 minute on my mac. I cannot emphesize how important fast integration tests are as a key enabler for developer productivity. Enabling this sort of thing requires some planning but it pays off hugely.<p>I wrote up a detailed article on how to do this some years ago. <a href="https:&#x2F;&#x2F;www.jillesvangurp.com&#x2F;blog&#x2F;2016-05-25-functional-tests-and-flakyness.html" rel="nofollow">https:&#x2F;&#x2F;www.jillesvangurp.com&#x2F;blog&#x2F;2016-05-25-functional-tes...</a><p>That&#x27;s still what I do a few projects and companies later.

Testcontainers aren&#x27;t even compatible with kubernetes, that&#x27;s a tool from the past.

Not everything can be placed in a docker which seem as a requirement.

been doing this for years, I would not say this gets rid of testing though.<p>Running integration tests are significantly more complicated to write and take longer to run.<p>There is also race conditions present that you need to account for programmatically.. Such as waiting for a db to come up and schema to be applied. Or waiting for a specific event to occur in the daemon.<p>That being said, this looks like a decent start. One thing that seems to be missing is the ability to tail logs and assert specific marks in the logs. Often you need to do an operation and wait until you see an event.

works on my container