• Stars
    star
    144
  • Rank 255,590 (Top 6 %)
  • Language
    Clojure
  • License
    Eclipse Public Li...
  • Created over 4 years ago
  • Updated 7 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Control Docker containers from your test lifecycle for Clojure integration tests.

clj-test-containers

Clojars Project

What it is

This library is a lightweight wrapper around the Testcontainers Java library.

What it isn't

This library does not provide tools to include testcontainers in your testing lifecycle. As there are many different test tools with different approaches to testing in the clojure world, handling the lifecycle is up to you.

Integration with test runners

There is an experimental kaocha plugin you can try out

Usage

The library provides a set of functions to interact with the testcontainers. A simple example, how to create a container with a Docker label, could look like this:

(require '[clj-test-containers.core :as tc])

(def container (-> (tc/create {:image-name    "postgres:12.1"
                               :exposed-ports [5432]
                               :env-vars      {"POSTGRES_PASSWORD" "verysecret"}})
                   (tc/bind-filesystem! {:host-path      "/tmp"
                                         :container-path "/opt"
                                         :mode           :read-only})
                   (tc/start!)))

(do-database-testing (:host container)
                     (get (:mapped-ports container) 5432))

(tc/stop! container)

If you'd rather create a container from a Dockerfile in your project, it could look like this:

(require '[clj-test-containers.core :as tc])

(def container (-> (tc/create-from-docker-file {:env-vars      {"FOO" "bar"}
                                                :exposed-ports [80]
                                                :docker-file   "resources/Dockerfile"})
                   (tc/start!)))

If you prefer to use prebuilt containers from the Testcontainers project, you can do it like this

(require '[clj-test-containers.core :as tc])
(:import [org.testcontainers.containers PostgreSQLContainer])

(def container (-> (tc/init {:container     (PostgreSQLContainer. "postgres:12.2")
                             :exposed-ports [5432]})
                   (tc/start!)))

Functions and Properties

create

Creates a testcontainers instance from a given Docker label and returns them

Config parameters:

Key Type Description
:image-name String, mandatory The name and label of an image, e.g. postgres:12.2
:exposed-ports Vector with ints, mandatory All ports which should be exposed and mapped to a local port
:env-vars Map A map with environment variables
:command Vector with strings The start command of the container
:network Map A map containing the configuration of a Docker Network (see: create-network)
:network-aliases Map A list of alias names for the container on the network
:wait-for Map A map containing the wait strategy to use and the condition to check for
:log-to Map A map containing the log strategy to use, e.g. {:log-strategy string}

Result:

Key Type Description
:container org.testcontainers.containers.Container The Testcontainers instance, accessible for everything this library doesn't provide (yet)
:exposed-ports Vector with ints Value of the same input parameter
:env-vars Map Value of the same input parameter
:host String The host for the Docker Container
:network Map The network configuration of the Container, if provided
:wait-for Map The wait-for configuration of the Container, if provided!

Example:

(create {:image-name      "alpine:3.2"
         :exposed-ports   [80]
         :env-vars        {"MAGIC_NUMBER" "42"}
         :network         (create-network)
         :network-aliases ["api-server"]
         :command         ["/bin/sh"
                           "-c"
                           "while true; do echo \"$MAGIC_NUMBER\" | nc -l -p 80; done"]})

Example using wait-for and healthcheck:

(create {:image-name      "alpine:3.2"
         :exposed-ports   [80]
         :env-vars        {"MAGIC_NUMBER" "42"}
         :network         (create-network)
         :network-aliases ["api-server"]
         :wait-for        {:strategy :health}
         :command         ["/bin/sh"
                           "-c"
                           "while true; do echo \"$MAGIC_NUMBER\" | nc -l -p 80; done"]})

init

Initializes a given Testcontainer, which was e.g. provided by a library

Config parameters:

Key Type Description
:container org.testcontainers.containers.GenericContainer, mandatory The name and label of an image, e.g. postgres:12.2
:exposed-ports Vector with ints, mandatory All ports which should be exposed and mapped to a local port
:env-vars Map A map with environment variables
:command Vector with strings The start command of the container
:network Map A map containing the configuration of a Docker Network (see: create-network)
:network-aliases Map A list of alias names for the container on the network
:wait-for Map A map containing the wait strategy to use and the condition to check for
:log-to Map A map containing the log strategy to use, e.g. {:log-strategy string}

Result:

Key Type Description
:container org.testcontainers.containers.Container The Testcontainers instance, accessible for everything this library doesn't provide (yet)
:exposed-ports Vector with ints Value of the same input parameter
:env-vars Map Value of the same input parameter
:host String The host for the Docker Container
:network Map The network configuration of the Container, if provided
:wait-for Map The wait-for configuration of the Container, if provided!

Example:

;; PostgreSQL container needs a separate library! This is not included.
(init {:container     (org.testcontainers.containers.PostgreSQLContainer)
       :exposed-ports [80]
       :env-vars      {"MAGIC_NUMBER" "42"}
       :command       ["/bin/sh"
                       "-c"
                       "while true; do echo \"$MAGIC_NUMBER\" | nc -l -p 80; done"]})

Example using wait-for and a log message:

;; PostgreSQL container needs a separate library! This is not included.
(init {:container     (org.testcontainers.containers.PostgreSQLContainer)
       :exposed-ports [80]
       :env-vars      {"MAGIC_NUMBER" "42"}
       :wait-for      {:strategy :log :message "accept connections"}
       :command       ["/bin/sh"
                       "-c"
                       "while true; do echo \"$MAGIC_NUMBER\" | nc -l -p 80; done"]})

create-from-docker-file

Creates a testcontainer from a Dockerfile

Config parameters:

Key Type Description
:docker-file String, mandatory String containing a path to a Dockerfile
:exposed-ports Vector with ints, mandatory All ports which should be exposed and mapped to a local port
:env-vars Map A map with environment variables
:command Vector with strings The start command of the container
:network Map A map containing the configuration of a Docker Network (see: create-network)
:network-aliases Map A list of alias names for the container on the network
:wait-for Map A map containing the wait strategy to use and the condition to check for
:log-to Map A map containing the log strategy to use, e.g. {:log-strategy string}

Result:

Key Type Description
:container org.testcontainers.containers.Container The Testcontainers instance, accessible for everything this library doesn't provide (yet)
:exposed-ports Vector with ints Value of the same input parameter
:env-vars Map Value of the same input parameter
:host String The host for the Docker Container
:network Map The network configuration of the Container, if provided
:wait-for Map The wait-for configuration of the Container, if provided!

Example:

(create-from-docker-file {:docker-file   "resources/Dockerfile"
                          :exposed-ports [5432]
                          :env-vars      {"MAGIC_NUMBER" "42"}
                          :command       ["/bin/sh"
                                          "-c"
                                          "while true; do echo \"$MAGIC_NUMBER\" | nc -l -p 80; done"]})

start!

Starts the Testcontainer, which was defined by create

Config parameters:

Key Type Description
First parameter:
container-config Map, mandatory Return value of the create function

Result:

Key Type Description
:container org.testcontainers.containers.Container The Testcontainers instance, accessible for everything this library doesn't provide (yet)
:exposed-ports Vector with ints Value of the same input parameter
:env-vars Map Value of the same input parameter
:host String The host for the Docker Container
:id String The ID of the started docker container
:mapped-ports Map A map containing the container port as key and the mapped local port as a value

Example:

(def container (create {:image-name    "alpine:3.2"
                        :exposed-ports [80]
                        :env-vars      {"MAGIC_NUMBER" "42"}}))

(start! container)

stop!

Stops the Testcontainer, which was defined by create

Config parameters:

Key Type Description
First parameter:
container-config Map, mandatory Return value of the create function

Result:

The container-config

Example:

(def container (create {:image-name    "alpine:3.2"
                        :exposed-ports [80]
                        :env-vars      {"MAGIC_NUMBER" "42"}}))

(start! container)
(stop! container)

map-classpath-resource!

Maps a resource from your classpath into the containers file system

Config parameters:

Key Type Description
First parameter:
container-config Map, mandatory Return value of the create function
Second parameter:    
:resource-path String, mandatory Path of your classpath resource
:container-path String, mandatory Path, to which the resource should be mapped
:mode Keyword, mandatory :read-only or :read-write

Result:

The container-config

Example:

(map-classpath-resource! container {:resource-path  "test.sql"
                                    :container-path "/opt/test.sql"
                                    :mode           :read-only})

bind-filesystem!

Binds a path from your local filesystem into the Docker container as a volume

Config parameters:

Key Type Description
First parameter:
container-config Map, mandatory Return value of the create function
Second parameter:    
:host-path String , mandatory Path on your local filesystem
:container-path String, mandatory Path, to which the resource should be mapped
:mode Keyword, mandatory :read-only or :read-write

Result:

The container-config

Example:

(bind-filesystem! container {:host-path      "."
                             :container-path "/opt"
                             :mode           :read-only})

copy-file-to-container!

Copies a file from your filesystem or classpath into the running container

Config parameters:

Key Type Description
First parameter:
container-config Map, mandatory Return value of the create function
Second parameter:    
:path String, mandatory Path to a classpath resource or file on your filesystem
:container-path String, mandatory Path, to which the file should be copied
:type Keyword, mandatory :classpath-resource or :host-path

Result:

The container-config

Example:

(copy-file-to-container! container {:path           "test.sql"
                                    :container-path "/opt/test.sql"
                                    :type           :host-path})

execute-command!

Executes a command in the running container, and returns the result

Config parameters:

Key Type Description
First parameter:
container-config Map, mandatory Return value of the create function
Second parameter:    
command Vector with Strings, mandatory A vector containing the command and its parameters

Result:

Key Type Description
:exit-code int Exit code of the executed command
:stdout String Content of stdout
:stdin String Content of stdin

Example:

(execute-command! container ["tail" "/opt/test.sql"])

create-network

Creates a network. The optional map accepts config values for enabling ipv6 and setting the driver

Config parameters:

Key Type Description
:ipv6 boolean Should the network enable IPv6?
:driver String The network driver used by Docker, e.g. bridge or host

Result:

Key Type Description
:network org.testcontainers.containers.Network The instance of the network
:name String The name of the network
:ipv6 boolean Does the network enable IPv6?
:driver String The network driver used

Example:

;;Create with config
(create-network {:ipv6   false
                 :driver "overlay"})

;;Create with default config
(create-network)

perform-cleanup!

Stops and removes all containers which were created in the JVM, including the REPL session you are in. This is helpful, if you are exploring functionality with containers in the REPL, and create lots of instances on the fly without stopping them. Testcontainers will remove all containers upon JVM shutdown, but the REPL keeps the JVM alive for a long time.

Config parameters:

None

Result:

None

Example:

(perform-cleanup!)

dump-logs

Call on a started container. Provided logging was enabled for a container, returns the given log presentation, e.g. as a string

Key Type Description
container-config Map, mandatory The configuration describing the container for which the log should be retrieved

License

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

More Repositories

1

testcontainers-java

Testcontainers is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.
Java
7,956
star
2

testcontainers-dotnet

A library to support tests with throwaway instances of Docker containers for all compatible .NET Standard versions.
C#
3,774
star
3

testcontainers-go

Testcontainers for Go is a Go package that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done.
Go
3,503
star
4

testcontainers-node

Testcontainers is a NodeJS library that supports tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.
TypeScript
1,849
star
5

testcontainers-python

Testcontainers is a Python library that providing a friendly API to run Docker container. It is designed to create runtime environment to use during your automatic tests.
Python
1,542
star
6

testcontainers-rs

A library for integration-testing against docker containers from within Rust.
Rust
697
star
7

testcontainers-scala

Docker containers for testing in scala
Scala
629
star
8

moby-ryuk

Schedule Moby/Docker containers cleanup after specific delay.
Go
182
star
9

testcontainers-dotnet-legacy

A .net fork of testcontainers - in early development
C#
165
star
10

testcontainers-ruby

Testcontainers for Ruby
Ruby
119
star
11

testcontainers-java-examples

Archived: This repo has been combined into the main testcontainers-java repository
Java
102
star
12

workshop

Java
100
star
13

testcontainers-elixir

Testcontainers is an Elixir library that supports ExUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.
Elixir
95
star
14

testcontainers-php

https://www.testcontainers.org implementation for PHP
PHP
81
star
15

testcontainers-rs-modules-community

Community maintained modules for Testcontainers for Rust
Rust
68
star
16

testcontainers-hs

Docker containers for your integration tests! http://hackage.haskell.org/package/testcontainers
Haskell
57
star
17

testcontainers-spock

Spock extension for using Docker containers in Spock tests. (DEPRECATED, moved to main repo!)
53
star
18

testcontainers-java-spring-boot-quickstart

Testcontainers QuickStarts
Java
50
star
19

testcontainers-jooq-codegen-maven-plugin

jOOQ code generator using Testcontainers
Java
49
star
20

java-local-development-workshop

Java local development workshop
Java
47
star
21

dind-drone-plugin

Plugin for Drone CI v0.8+ to enable use of Testcontainers using Docker-in-Docker
Shell
31
star
22

testcontainers-native

Testcontainers for C/C++/Swift and other native projects, built on the top of Testcontainers for Go
Go
20
star
23

workshop-go

Go
18
star
24

community-module-registry

Testcontainers Community Module Registry
15
star
25

testcontainers-js

A javascript fork of testcontainers - in early development
TypeScript
9
star
26

vnc-recorder

Docker image that can be used to create a sidekick container for recording videos of VNC sessions hosted in other containers
Dockerfile
9
star
27

java-module-workshop

Workshop about making your own Testcontainers module and learning important things
Java
9
star
28

tc-guide-testing-spring-boot-rest-api

Getting started with Testcontainers in a Java SpringBoot Project
Java
8
star
29

tc-guide-testing-spring-boot-kafka-listener

Testing Spring Boot Kafka Listener using Testcontainers Guide
Java
8
star
30

helloworld

A Docker image to support Testcontainers' self-test suites
Go
7
star
31

testcontainers-java-repro

A template repository intended to help create isolated repro examples for Testcontainers issues
Java
7
star
32

testcontainers-showcase

Testcontainers ShowCase
Java
7
star
33

sshd-docker

Docker image with SSH daemon installed
Dockerfile
7
star
34

testcontainers-java-module-oracle-xe

Deprecated repository - moved to https://github.com/testcontainers/testcontainers-java
6
star
35

testcontainers-java-module-localstack

Deprecated repository - moved to https://github.com/testcontainers/testcontainers-java
6
star
36

tc-guide-getting-started-with-testcontainers-for-nodejs

JavaScript
6
star
37

tc-guide-testing-aws-service-integrations-using-localstack

Testing AWS Service Integrations using LocalStack guide
Java
6
star
38

testcontainers-java-module-mssqlserver

Deprecated repository - moved to https://github.com/testcontainers/testcontainers-java
5
star
39

tc-guide-simple-local-development-with-testcontainers-desktop

Simple local development with Testcontainers Desktop guide
Java
5
star
40

tc-guide-getting-started-with-testcontainers-for-dotnet

C#
5
star
41

tc-guide-securing-spring-boot-microservice-using-keycloak-and-testcontainers

Guide for Securing Spring Boot Microservice using Keycloak and Testcontainers
Java
5
star
42

tc-guide-testing-aspnet-core

Getting started with Testcontainers in an ASP.NET Core web app
C#
5
star
43

tc-guide-getting-started-with-testcontainers-for-java

Getting started with Testcontainers for Java guide
Java
4
star
44

testcontainers-java-module-mariadb

Deprecated repository - moved to https://github.com/testcontainers/testcontainers-java
4
star
45

testcontainers-groovy-script

Java
4
star
46

tc-guide-testcontainers-lifecycle

Testcontainers LifeCycle Guide
Java
3
star
47

testcontainers-nocode

3
star
48

tc-guide-testing-rest-api-integrations-using-mockserver

Testing REST API integrations using MockServer Guide
Java
3
star
49

tc-guide-getting-started-with-testcontainers-for-go

Getting started with Testcontainers for Go guide
Go
3
star
50

tc-guide-replace-h2-with-real-database-for-testing

Testing relational database repositories using Testcontainers
Java
2
star
51

tc-guide-testing-rest-api-integrations-using-wiremock

Testing REST API integrations using WireMock Guide
Java
2
star
52

testcontainers-java-module-vault

Deprecated repository - moved to https://github.com/testcontainers/testcontainers-java
2
star
53

tc-guide-working-with-jooq-flyway-using-testcontainers

Working with jOOQ and Flyway using Testcontainers Guide
Java
2
star
54

tc-guide-getting-started-with-testcontainers-for-python

Getting started with Testcontainers for Java guide
Python
2
star
55

tc-guide-testing-micronaut-kafka-listener

Testing Micronaut Kafka Listener using Testcontainers
Java
1
star
56

testcontainers-java-module-dynalite

Deprecated repository - moved to https://github.com/testcontainers/testcontainers-java
1
star
57

tc-guide-testcontainers-in-quarkus-applications

Getting started with Testcontainers in a Quarkus Project
Java
1
star
58

tc-guide-testing-rest-api-integrations-in-micronaut-apps-using-wiremock

Testing REST API Integrations in Micronaut Applications using WireMock
Java
1
star
59

testcontainers-go-fiber

Sample application of testcontainers-go and Go Fiber
Go
1
star
60

tc-guide-template

Template for a Testcontainers Guide
1
star
61

tc-guide-configuration-of-services-running-in-container

Code for Configuring application dependencies Guide
Java
1
star