Kaocha Testcontainers Plugin
What does it do?
This is a plugin for the kaocha testrunner. It manages the lifecylce of Testcontainers.
This is a very early work in progress and the configuration or the API might still break.
Who is it for?
Managing the state of Testcontainers in tests manually, e.g. with clj-test-containers, allows us to control in great detail which containers are created and destroyed at what time. As a downside, the setup code for the containers often distracts from the domain we want to test and is repetitive. This plugin helps developers define a set of containers which will be made available for test – either with a global scope for all tests, or with a local scope for each test.
What is still missing?
This is a work in progress. We are currently working on adding additional filters, so the plugin can control in which test types the Testcontainers are used and add namespace filters to the containers to allow for a finer association from containers to tests
How to use it?
This plugin can be registered as a kaocha plugin. The container definition is part of the configuration, too. The :id
specifies the identifier which can be used to later access containers from the tests. :for
determines if the container
should be started for all tests, or should be created for each single test and then discarded afterwards. The :config
contains a container config according to
the create
function of clj-test-containers:
#kaocha/v1
{:tests [{:id :unit
:test-paths ["test"]
:ns-patterns [".*test$"]}
{:id :no-tc
:test-paths ["test"]
:ns-patterns [".*no-tc$"]}]
:kaocha/plugins [:lambdaschmiede.kaocha-tc/plugin]
:lambdaschmiede.kaocha-tc/config [
{:id :postgres-1
:for {:type :all
:tests [:unit]}
:config {:image-name "postgres:12.1"
:exposed-ports [5432]
:env-vars {"POSTGRES_PASSWORD" "verysecret"}}}
{:id :postgres-2
:for {:type :each
:filter ["-test$"]}
:config {:image-name "postgres:12.1"
:exposed-ports [5432]
:env-vars {"POSTGRES_PASSWORD" "verysecret"}}}
{:id :postgres-3
:for {:type :ns
:filter ["test$"]}
:config {:image-name "postgres:12.1"
:exposed-ports [5432]
:env-vars {"POSTGRES_PASSWORD" "verysecret"}}}]}
Note, that we can assign different scopes to the containers via :for
: :postgres-1
will start before a whole test run
and be discarded afterwards, marked by the :all
type. The :filter
vector accepts a list of test-ids for which this
should be run. In this case, the container would be started before the :unit
tests, but not before the :no-tc
tests. postgres
will be started for every single test which name ends in -test
, :postgres-3
will be started for
every test namespace which name ends on test
.
If we now want to access the container and its configuration from within the tests, we can do so with the
function lambdaschmiede.kaocha-tc/get-container
. This function is scoped, so it will only return containers which are
valid for the active test:
(require [clojure.test :refer :all])
(require [lambdaschmiede.kaocha-tc/get-container :refer [get-container]])
(deftest for-each-test
(testing "The 'for each' container exists"
(let [pg-container (get-container :postgres-2)]
(is (some? pg-container))
(is (some? (.getHost (:container pg-container))))
(is (some? (.getMappedPort (:container pg-container) 5432))))))
License
Distributed under the Eclipse Public License either version 2.0 or (at your option) any later version.