Pytest-docker-tools

Reusable Containers

Previously reusable containers were never replaced. Once they existed, that was it. So if you changed the fixture in code you had to manually clean up the previous fixture before continuing. This becomes even more annoying if you want to use this feature in your CI environment. This release tracks how stale a docker fixture is and replaces it if it becomes stale. This automatically handles the following cases:

* Your co-worker has bumped a tag in a `fetch()` fixture, for example to use postgres 14 and its new JSON syntax. You git pull and your tests start failing. Sometimes this might not be obvious and the breakage might be some time after the root cause.
* You make a change to some code that triggers a `build()` fixture. Right now the build will still run, but the old container with the old image will be used.

In these sorts of situations instead of reusable containers saving you time, they cost time. And if the root cause isn't obvious, it might be a lot of time.

pytest-docker-tools now tags fixtures it makes with the label `pytest-docker-tools.signature`. This is a hash of the parameters used to create the fixture. When this signature changes, pytest-docker-tools knows the fixture is stale and replaces it.

⚠️ This is a breaking change. No code changes are needed to use 3.0.0, but existing reusable containers may be deleted and recreated automatically as they will be considered stale by the new code.

Reusable containers

**Warning** breaking change. The labels used to track reusable containers have changed. Your containers may need to be removed manually when migrating to this release.

This release fleshes out "reusable containers" and applies the same logic to networks and volumes.

Image caching

Image building can be slow. For some images, its by far the slowest part of your test cycle. Optimising your image build for layer reuse can help. But after many iterations your machine will acrue many iterations of your image as well. To keep the benefits of layer reuse but also keep housekeeping simple we recommend tagging your images when using `build` fixtures. This means that when you run `docker image prune` old versions of your image are deleted and the current version is kept.

python
from pytest_docker_tools import build

my_image = build(
path='db',
tag='localhost/myproject:latest'
)


If you make 20 changes to your project that cause 20 builds you will now see 20 images in `docker images ls`. Only one will be tagged `localhost/myproject:latest`. And when you run `docker image prune` that one image will be kept and the other 19 will be removed.

There is a problem, though. Multi-stage builds. You can't tag your building stages, so running `docker image prune` will delete your builder stages. These are often the slowest parts of the multi-stage build, and now you have to rebuild them.

As of pytest-docker-tools 2.0.0 `build()` gains a `stages` property. It lets you tag your builders.

python
from pytest_docker_tools import build

my_image = build(
path='db',
tag='localhost/myproject:latest',
stages={
'builder': 'localhost/myproject:builder'
}
)


Now when you prune the latest versions of your build stages and your final target image are all preserved. And the old versions are thrown away. Better build speeds, and you don't need a bigger hard drive.