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.

Example 6: Passing extension overrides

The following tells the Extension Manager to use the existing core extension com.google.code.findbugs:annotations whenever the extension com.google.code.findbugs:jsr305 is requested.

Note that in the XWiki build, these extension overrides are defined in the top level XWiki Platform POM and for this specific case it's defined as:

Another example:

Example 7: Execute a test on main and subwiki

It can be interresting to verify that a test scenario works both on main and subwiki to catch context related bugs or simply things which were designed too much with main wiki in mind. A @ParameterizedTest source is available to automate this.

The following example executes the test copyPage twice, once with the main wiki in input and the second time with an automatically created wiki as input and indicate that the extension org.xwiki.platform:xwiki-platform-index-tree-macro is required in the subwiki:

This tool relies on wiki creation job, so you will need to include the following modules to your instance:

Example 8: Login multiple users at the same time

Best Practices

Scenarios

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

Suites

Use JUnit5's @Nested annotation. For example:

XWiki 12.8+ When using nested tests, only configure any @UITest parameter in the nested tests themselves and not in the parent (e.g. at the AllIT level the @UITest annotation should be empty). This is because @UITest annotation parameters are automatically merged.

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");
  }

Stdout/stderr validation errors

We have a check that verifies if functional tests output some invalid content to stdout/stderr. If your test contains such errors it'll fail and then you have 3 options:

• It's a normal and expected output from the test (for ex the test verifies an error condition and it's expected it will raise a stack trace in the console). In this case add an expectation in the test. For example:
  public void wrongTemplate(LogCaptureConfiguration logCaptureConfiguration)
  {
     ...
      logCaptureConfiguration.registerExpected( "Possible break-in attempt!",
         "Error getting resource [null]");
  }
• It's a non-expected error. You then have 2 sub-choices:
  • Fix the problem (the best and recommended solution!)
  • Increase the technical debt by adding an exclude. For example:
    logCaptureConfiguration.registerExcludes(
       "java.lang.IllegalStateException: Response is committed");

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:

Code Resources

You might need custom test code deployed to the XWiki webapp for the test (to override some components for example). Any classes that land into target/classes will be copied to the webapp's WEB-INF/classes directory. Thus you can, for example, put sources in src/main/* to see it deployed in the webapp.

Test Logging

You might want to activate some debug logs specific to the test. This can be achieved by providing a logback-override.xml file in your src/test/resources directory of your Maven project.

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.

A common use case is to debug a failing test. Here's what you can do:

Run a single test

For example to run the NestedResetPasswordIT tests from an AllIT test class defined as:

You'd use:

Notes:

• Using -Dit.test=*NestedResetPasswordIT* is not going to work well for some reason (we still need to debug this to understand why it doesn't work as expected).
• Using -Dit.test=ResetPasswordIT makes the Maven Surefire plugin use the individual test instead of AllIT, even though the top level Commons POM says that only the AllIT class is included by default.

See also the Existing XWiki instance section.

Dynamic Configuration

Some tests may require a dynamic configuration. For example:

• Active Installs tests require to set the activeinstalls2.pingURL configuration property in xwiki.properties dynamically since the Ping URL changes for each test (it's the URL to an ElasticSearch docker container with a mapped port that changes to avoid impacting other tests).
• The client-side PDF Export tests also need to set a export.pdf.dockerNetwork configuration property in xwiki.properties dynamically for similar reasons.

To support these cases, it's possible to execute some Java code that will run before your tests execute and that will provide a TestConfiguration pushed in the JUnit5 Global Test Context, which will then be merged automatically by the XWiki Docker Test framework.

Example

And then:

Ignore Browsers

Architecture

See Vincent's blog for more details