Introduction
This guide is intended for XMPP Server developers who are building in GitLab. It demonstrates how to add XMPP Interoperability and Standards Conformance tests integrated into a build & test pipeline. This assumes that you already have a pipeline established, and wish to add the additional checks.
Like all external components in GitLab, this one requires an include statement (with optional inputs). Since this job often requires your own dependencies and customisation, it imports as a template called .xmpp-interop-tests
which is then explicit extended in a job. That job runs the tests, giving junit-esque outputs and debug logs. The only prerequisite is that you’ve got a built server, and have started it.
Assuming you already have a pipeline, and a script to launch your server, adding our GitLab component is as easy as adding a small amount YAML to your pipeline:
include:
- component: gitlab.com/xmpp-interop-testing/xmpp-interop-testing-gitlab-component/interop-testing@v1.6.0
inputs:
domain: 'shakespeare.lit'
adminAccountUsername: 'juliet'
adminAccountPassword: 'O_Romeo_Romeo!'
compliance-tests:
extends: .xmpp-interop-tests
stage: test
This example demonstrates one possible way to provision accounts. It assumes your server is running and accessible at shakespeare.lit
, and that it already has an administrative account (one that is allowed to create other users, per XEP-0133) that uses the username juliet
and the provided password. Other configuration methods are also available, and you can explore the full set of options in the sections below.
A Full Example
Very generically, the job is expected to be part of such a flow in this manner:
- Compile and build server software
- Start server and run test job
Given the isolation of jobs in GitLab, the start of the server and the running of tests must normally be combined, usually by starting the server in the before_script
.
Assume that you have a trivial pre-existing build pipeline that looks like this for compiling and storing builds of an XMPP server:
maven-build:
stage: build
script: ./mvnw package
artifacts:
paths:
- my_xmpp_server
Then you’d add our first example, with tweaks for dependencies and for launching, and end up with this:
maven-build:
stage: build
script: ./mvnw package
artifacts:
paths:
- my_xmpp_server
include:
- component: gitlab.com/xmpp-interop-testing/xmpp-interop-testing-gitlab-component/interop-testing@v1.6.0
inputs:
domain: 'shakespeare.lit'
host: '127.0.0.1'
adminAccountUsername: 'juliet'
adminAccountPassword: 'O_Romeo_Romeo!'
compliance-tests:
extends: .xmpp-interop-tests
stage: test
dependencies:
- maven-build
before_script: "./my_xmpp_server/launch-my-server.sh"
In addition to the first example:
- A
host
option to direct the test engine to resolveshakespeare.lit
as the local server - A
dependencies
section in the test job to wait for the build - A
before_script
to launch the built server prior to testing
Configuration
Various options are available when calling xmpp_interop_tests_action, and whilst none of them are absolutely required, the defaults are unlikely to be perfect for everyone.
For the latest updates to the documentation of the configuration updates, consult the GitLab repository of the GitLab Action.
Option | Description | Default value |
---|---|---|
host | IP address or DNS name of the XMPP service to run the tests on. | 127.0.0.1 |
domain | the XMPP domain name of server under test. | example.org |
timeout | the amount of milliseconds after which an XMPP action (typically an IQ request) is considered timed out. | 5000 (five seconds) |
adminAccountUsername | (optional) The account name of a pre-existing user that is allowed to create other users, per XEP-0133. See: “Provisioning Test Accounts” | - |
adminAccountPassword | (optional) The password of the admin account | - |
accountOneUsername | (optional) The first account name of a set of three accounts used for testing. See: “Provisioning Test Accounts” | - |
accountOnePassword | (optional) The password of the accountOneUsername account. | - |
accountTwoUsername | (optional) The second account name of a set of three accounts used for testing. See: “Provisioning Test Accounts” | - |
accountTwoPassword | (optional) The password of the accountTwoUserName account | - |
accountThreeUsername | (optional) The third account name of a set of three accounts used for testing. See: “Provisioning Test Accounts” | - |
accountThreePassword | (optional) The password of the accountThreeUserName account | - |
disabledTests | (optional) A comma-separated list of tests that are to be skipped. For example: EntityCapsTest,SoftwareInfoIntegrationTest | - |
disabledSpecifications | (optional) A comma-separated list of specifications (not case-sensitive) that are to be skipped. For example: XEP-0045,XEP-0060 | - |
enabledTests | (optional) A comma-separated list of tests that are the only ones to be run. For example: EntityCapsTest,SoftwareInfoIntegrationTest | - |
enabledSpecifications | (optional) A comma-separated list of specifications (not case-sensitive) that are the only ones to be run. For example: XEP-0045,XEP-0060 | - |
logDir | (optional) The directory in which the test output and logs are to be stored. This directory will be created, if it does not already exist. | ./output |
Provisioning Test Accounts
To be able to run the tests, the server that is being tested needs to be provisioned with test accounts. Three different mechanisms can be used for this:
- Admin Account - By configuring the username and password of a pre-existing administrative user, using the
adminAccountUsername
andadminAccountPassword
configuration options, three test accounts will be created using XEP-0133: Service Administration functionality. - Explicit Test Accounts - You can configure three pre-existing accounts that will be used for testing, using the
accountOneUsername
,accountOnePassword
,accountTwoUsername
,accountTwoPassword
,accountThreeUsername
andaccountThreePassword
configuration options. - In-Band Registration - If no admin account and no explicit tests accounts are provided, in-band registration (XEP-0077) will be used to provision accounts.
For more information on provisioning accounts, consult the ‘Test Account Provisioning’ guide.
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 Joel Filipe, Unsplash