A tiny Docker appliance for running cross-repo integration tests; Crossdock is:
- Portable - runs anywhere Docker is installed, eg Travis & locally.
- General - can be used to test sets of libraries and microservices.
- Flexible - test all combinations of behaviors using custom matrix axis.
- Decentralized - each repo can configure and run Crossdock independently from the others.
- Light - run Crossdock for every commit on every repo in parallel.
- Easy - run integration tests on a large project without installing every component.
Crossdock is published in Docker Hub and is meant to be used with Docker Compose directly from your repos.
Given the following docker-compose.yml
:
crossdock:
image: crossdock/crossdock
dns_search: . # Ensures unified DNS config.
links:
- alpha
- omega
environment:
- WAIT_FOR=alpha,omega
- AXIS_CLIENTS=alpha,omega
- AXIS_SPEED=fast,slow
- BEHAVIOR_DANCE=clients,speed
- BENAVIOR_RUN=clients,speed
alpha:
image: breerly/hello-server
dns_search: .
ports:
- 8080
environment:
- HELLO_PORT=8080
- HELLO_MESSAGE=ok
omega:
image: breerly/hello-server
dns_search: .
ports:
- 8080
environment:
- HELLO_PORT=8080
- HELLO_MESSAGE=ok
Running Crossdock will initiate tests for clients alpha
and omega
for
every combination of behavior
and speed
:
$ docker-compose run crossdock
Beginning matrix of tests...
STATUS | CLIENT | RESPONSE | SPEED | BEHAVIOR
+--------+--------+----------+-------+----------+
PASSED | alpha | ok | fast | dance
PASSED | alpha | ok | fast | run
PASSED | alpha | ok | slow | dance
PASSED | alpha | ok | slow | run
PASSED | omega | ok | fast | dance
PASSED | omega | ok | fast | run
PASSED | omega | ok | slow | dance
PASSED | omega | ok | slow | run
There are scenarios where you don't want to run the full cross-product of the axes a behavior depends on. To accommodate this, crossdock supports filtering of test cases.
For any behavior, a SKIP_$name
environment variable may be declared, where
$name
is the name of the behavior, specifying a list of zero or more filters
separated by commas.
filter1,filter2,...,filterN
Each filter consists of zero or more axis matchers separated by +
.
axis1:value1+axis2:value2+...+axisN:valueN
A filter matches a test case of a behavior if all axis matchers specified in the filter match the parameters for that behavior. A test case for a behavior is skipped if any of the filters specified for it match the parameters.
For example,
SKIP_RUN=clients:alpha+speed=slow,clients:omega+speed=fast
The above states that test cases of the RUN
behavior should be skipped when
one of the following is true:
clients
isalpha
andspeed
isslow
; orclients
isomega
andspeed
isfast
- Write Test Client
- Run Crossdock
- Publish Test Client
- Integrate Other Repos
- Add Other Test Axis
- Run During Continuous Integration
Cheers.