Examples

Full Examples

• MenuIT
• MailIT

Example 1: Basic test

Example 2: Choosing Container + DB + Browser and versions

Example 3: Test using Greenmail + Hibernate HBM

Example 4: Passing Test Configuration

Example 5: Specifying explictly dependencies

Example of deploying a 1.10-SNAPSHOT version of org.xwiki.contrib.latex:latex-export (and its dependencies) into a 11.2-SNAPSHOT version of XWiki. In this example the POM of org.xwiki.contrib.latex:latex-export depends on XWiki 10.2. Thus this example demonstrates running the tests in a more recent version of XWiki than the code was built on.

Best Practices

Scenarios

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

Suites

Use JUnit5's @Nested annotation. For example:

Test Reference

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

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

Docker out of Docker

The XWiki's CI is using a Jenkins Agent Docker image to execute the job builds. Thus, the Docker-based functional tests spawn Docker containers (using TestContainers) that execute inside Docker. This is the pattern called DOOD (Docker out of Docker). See TC's best practice about this.

There are some consequences when writing tests for XWiki:

• Never use volume mapping or it won't execute fine. This is because that would require the Jenkins Agent Docker container to have that volume mapping defined too and the mapping would need to use the exact host path and container path. So, in short, it won't work. Instead copy files that you need to have in the container. Adn copy file out if need be. Here's an example from the LaTeX extension on how to achieve this:
  try (GenericContainer container = new GenericContainer("blang/latex:ubuntu")) {
     // Note: we copy files instead of mounting volumes so that this can work when using DOOD
     // (Docker out of Docker).
     MountableFile mountableDirectory = MountableFile.forHostPath("target/latex");
      container.withCopyFileToContainer(mountableDirectory, "/data");
  
      container.withCommand("/bin/sh", "-c", "sleep infinity");
      container.withLogConsumer(new Slf4jLogConsumer(LOGGER));
      container.start();
      Container.ExecResult result = container.execInContainer("pdflatex", "-shell-escape", "index.tex");
      String stdout = result.getStdout();
      LOGGER.info(stdout);
      assertTrue(stdout.contains("Output written on index.pdf"));
  
      container.copyFileFromContainer("/data/index.pdf", "target/latex/index.pdf");
  }

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:

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.

Example:

Existing XWiki instance

If you want to avoid the Docker-based tests to start and stop XWiki every time you re-run the tests (for example when you're developping/debugging something), you can tell the Docker Test framework to not provision an XWiki instance and to use your XWiki instance instead.

This is achieved by specifying @UITest(servletEngine = ServletEngine.EXTERNAL)
or passing the xwiki.test.ui.servletEngine=external system property.

Architecture

See Vincent's blog for more details