• Based on TestContainers and uses Docker to execute the tests under various Databases, Servlet Engines and Browsers.
  • The only requirements for running these tests is to have Docker installed locally and to have the user under which you run your IDE and the Maven build be able to use the docker executable.
  • Tests get injected XWikiWebDriver and TestUtils instances as test method parameters.
  • Test results is recording in a FLV file in the target directory.
  • A screenshot of the UI when the test is failing is also taken in the target directory.
  • When test execute it's possible to connect to the running VNC server and see the UI by using a VNC client and connect to the VNC URL printed in the console, e.g. vnc://vnc:[email protected]:32936.
  • The version for the platform dependencies is specified using the platform.version property in the pom.xml file executing the tests.
  • The test configuration options can be accessed from tests by specifying a method parameter of type TestConfiguration (see examples below).
    • You can get access to the IP address/port to use to connect to XWiki from the host machine: testConfiguration.getServletEngine().getIP()/getPort()
    • You can get access to the IP address to use to connect to the host machine from inside XWiki: testConfiguration.getServletEngine().getHostIP()
    • You can get access to the IP address/port used internally by XWiki (for example to generate URLs): testConfiguration.getServletEngine().getInternalIP()/getInternalPort()

Configurations options


  • When passing as Java annotation attributes, in functional tests, the format is @UITest(<Option Name> = <Value>)
  • When passing the options as System Properties, the format is -Dxwiki.test.ui.<Option Name>=<Value>
    • Except for passing properties where the format is<Property name>=<Property Value>
    • Except for extraJARs, sshPorts & forbiddenServletEngines which cannot be set from System Properties.
  • System properties have priority over Java annotation attributes
Option NameDefault ValueValid ValuesDescription
  • firefox (Browser.FIREFOX)
  • chrome (Browser.CHROME)
The browser used in the tests. Note that the version of the browser used is controlled by the version of Selenium that is defined in the pom.xml of xwiki-platform-test-docker.
  • mysql (Database.MYSQL)
  • postgresql (Database.POSTGRESQL)
  • hsqldb_embedded (Database.HSQLDB_EMBEDDED)
The database used in the tests
  • tomcat (ServletEngine.TOMCAT)
  • jetty (ServletEngine.JETTY)
  • jetty_standalone (ServletEngine.JETTY_STANDALONE)
  • external (ServletEngine.EXTERNAL)
The Servlet Engine used in the tests. Use external to use your own started and alreayd provisioned XWiki instance.
  • true
  • false
When active, displays more logs in the console (especially container startup logs)
  • true
  • false
When active, displays debug logs in the console
  • true
  • false
By default, database data is not saved between test executions. Note that if you decide to save database data, they'll be saved under a docker user by Docker and you need your local user to be able to remove them if you want to clean your Maven target directory.
  • true
  • false
When offline, the custom XWiki WAR generation and the XWiki provisioning are done solely from your local Maven repository. Otherwise, when artifacts are not present locally or newer SNAPSHOT versions are available, they'll be fetched from Maven remote repositories.
databaseTagLatest supported version by XWikiAny Docker tag available from Dockerhub for the container imageVersion of the database to use. Isn't supported for HSQLDB Embedded since it doesn't run in a Docker container.
servletEngineTagLatest supported version by XWikiAny Docker tag available from Dockerhub for the container imageVersion of the Servlet Engine to use. Isn't supported for Jetty Standalone since it doesn't run in a Docker container.
jdbcDriverVersionLatest version validated by the XWiki dev teamAny version for the specified database that is available on Maven Central, e.g. for MySQL the groupId/artifactId is mysql/mysql-connector-java. 
  • true
  • false
When active a VNC container is started to record a video of the tests and more generally to allow connecting to the UI running the tests. Useful when debugging.
propertiesNo default (empty)Check the *.vm files for the configuration files to see the list of possible values.Velocity properties that are applied when generating XWiki's configuration files: xwiki.cfg, and hibernate.cfg.xml. Example: Tell XWiki that minification is off: or @UITest(properties = { "xwikiPropertiesAdditionalProperties=debug.minify=false" }).
extraJARsNo default (empty)Comma-separated list of <groupId>:<artifactId>There are cases where the module being tested cannot be fully deployed as an extension into a running XWiki and it needs to deploy one or several JARs into WEB-INF/lib. One such example is when an extension includes a Hibernate HBM file, as right now only HBM files located in JARs in WEB-INF/lib are supported.
sshPortsNo default (empty)List of integersThe list of ports that should be SSH-forwarded when connecting from a Docker container to the host (i.e. when using the host.testcontainers.internal. This is in addition to port 8080 which is always added. For example if you need XWiki to send a mail to a SMTP server running on port 3025 on the host, you should add port 3025 to the list.
profilesNo default (empty)Comma-separated list of Maven profile idsWhen specified the defined profiles are active when resolving dependencies from the current POM.
forbiddenServletEnginesNo default (empty)List of ServletEngines enumsList of Servlet Engines for which the tests will be skipped (usually because they'd fail on them).


Full Examples

Example 1: Basic test

public class SeleniumTest
   public void test(XWikiWebDriver driver, TestUtils setup)
            containsString("XWiki - The Advanced Open Source Enterprise and Application Wiki"));
        driver.findElement(By.linkText("XWiki's concept")).click();

Example 2: Choosing Container + DB + Browser and versions

@UITest(database = Database.MYSQL, databaseTag = "5", servletEngine = ServletEngine.TOMCAT, servletEngineTag = "8",
  browser = Browser.CHROME)
public class MenuIT
@UITest(database = Database.POSTGRESQL, databaseTag = "9", servletEngine = ServletEngine.JETTY,
  servletEngineTag = "9", browser = Browser.CHROME)
public class MenuIT
@UITest(database = Database.HSQLDB_EMBEDDED, servletEngine = ServletEngine.JETTY_STANDALONE,
  browser = Browser.FIREFOX)
public class MenuIT

Example 3: Test using Greenmail + Hibernate HBM

@UITest(sshPorts = {
    properties = {
       // Pages created in the tests need to have PR since we ask for PR to send mails so we need to exclude them from
       // the PR checker.
    extraJARs = {
public class MailIT

Example 4: Passing Test Configuration

public void verifyMail(TestUtils setup, XWikiWebDriver webDriver, TestConfiguration testConfiguration)
   throws Exception

Best Practices


Always use scenarios and use JUnit5's @Order(...) annotation. For example:

public class MenuIT
    public void verifyMenuInApplicationsIndex(TestUtils setup)

    public void verifyMenuCreationInLeftPanelWithCurrentWikiVisibility(TestUtils setup)

    public void verifyMenuIsAvailableInAdministration(TestUtils setup) throws Exception


Use JUnit5's @Nested annotation. For example:

public class AllIT
    @DisplayName("Office Import Tests")
    class NestedOfficeImporterIT extends OfficeImporterIT

    @DisplayName("Office Export Tests")
    class NestedOfficeExportIT extends OfficeExportIT

Test Reference

A lot of tests need to create a wiki page for testing. Example to do this:

public void showAndHideEditComments(TestUtils setup, TestReference reference) throws Exception
        ViewPage vp = setup.gotoPage(reference);

More generic way (more verbose but can useful in some cases) using JUnit5's TestInfo class:

public class MailIT
   private String testClassName;

   public void setUp(TestInfo info)
       this.testClassName = info.getTestClass().get().getSimpleName();

Test Resources

You might need test resources to be used in interaction with the wiki (e.g. to upload an attachment). Any test resources placed in src/test/resources is made automatically available to the browser container by mounting the dedicated volume mapped to target/test-classes. Then, in your test, you can use the dedicated method to get access to the files located in target/test-classes.

For example:

String resourceDirPath = testConfiguration.getBrowser().getTestResourcesPath();
File myResourceFile = new File(resourceDirPath, filename);

Test Coverage

Activate support for Clover by setting the xwiki.test.ui.profiles property in the clover profile in the pom.xml file for the test.


     <!-- Add the Clover JAR to the WAR so that it's available at runtime when XWiki executes.
           It's needed because instrumented jars in the WAR will call Clover APIs at runtime when they execute. -->

             <systemProperties combine.children="append">
               <!-- Tell the Docker-based test to activate the Clover profile so that the Clover JAR is added to
                     WEB-INF/lib -->



See Vincent's blog for more details

CI Jobs

There are 3 CI jobs executing Docker-based functional tests:

  • Job 1: run all tests on latest versions of supported configs.
  • Job 2: run smoke tests (ie a few tests only) on all supported configs.
  • Job 3: run smoke tests on unsupported configs (MySQL 8.x, Tomcat 9.x, etc) that we want to support in the future.

Configuration definitions and job sources are all here.

Created by Vincent Massol on 2018/11/25 16:20

Get Connected