Testing in Docker

This guide is intended for XMPP Server developers who are building their server using a continuous integration solution that is capable of launching Docker instances.

The Docker-based approach has been created for those development environments that don’t match any of our other, more specific CI-integrations, but it none-the-less offers the full range of features.

This guide demonstrates how to add XMPP Interoperability and Standards Conformance tests integrated into a build & test pipeline. It is assumed that you already have a pipeline established, and wish to add the additional checks provided by our project.

Docker container images for the XMPP Interop Testing project are published to the GitHub Package / Container registry of our project. Using them can be as simple as this:

docker pull ghcr.io/xmpp-interop-testing/xmpp_interop_tests:latest

docker run \
    --network=host \
    ghcr.io/xmpp-interop-testing/xmpp_interop_tests:latest \
    --domain=shakespeare.lit \
    --adminAccountUsername=juliet \
    --adminAccountPassword=O_Romeo_Romeo

The above assumes that your server is running and reachable on the domain shakespeare.lit and that it is provisioned with an administrative account (one that is allowed to create other users, per XEP-0133) that uses the username juliet and the provided password. You’ll find the full range of available configuration options below.

Configuration

Various options are available when invoking the xmpp_interop_tests, and whilst none of them are absolutely required, the defaults are unlikely to be perfect for everyone.

Exposing XMPP traffic logs

XMPP traffic is logged by the container in its /logs directory. To easily access the XMPP traffic logs, use a bind mount from anywhere on the host machine into the container on the /logs path.

For example, by adding -v "$(pwd)"/xmpplogs:/logs, a directory named xmpplogs (relative to the working directory) on the host is used as a mount for the /logs directory on the container:

$ docker run \
    --network=host \
    -v "$(pwd)"/xmpplogs:/logs \
    ghcr.io/xmpp-interop-testing/xmpp_interop_tests:main \
    --domain=shakespeare.lit \
    --adminAccountUsername=juliet \
    --adminAccountPassword=O_Romeo_Romeo

# Removed a lot of output for brevity.

$ ls ./xmpplogs | wc -l
255

Detecting test failures

Verbose test results are logged on standard-out. To programmatically detect test failures - for example to automatically mark a build as failed - the exit code of the ‘docker run’ execution can be used. Any non-zero exit code indicate that tests have failed:

$ docker run \
    --network=host \
    -v "$(pwd)"/xmpplogs:/logs \
    ghcr.io/xmpp-interop-testing/xmpp_interop_tests:main \
    --domain=shakespeare.lit \
    --adminAccountUsername=juliet \
    --adminAccountPassword=O_Romeo_Romeo

# Removed a lot of output for brevity, but test failures were reported.

$ echo $?
2

For the latest updates to the documentation of the configuration updates, consult the GitHub repository.

Next steps

Now that you have integrated the XMPP Interoperability and Standards Conformance tests into your build pipeline, it is time to start working with the tests!

We’ve compiled the following resources to help you with any run-time challenges that you may run into:

• Choosing what test to run - helps you choose how to disable specific tests (useful when you want to ignore a particular test for some reason).
• Diagnose test failures - explains what you can do to find the reason that test is failing. Did we identify an issue in your server software? Find out!

Splash image courtesy of Bernd 📷 Dittrich, Unsplash