Rendering Test Framework
Allows you to write Syntax tests for your Parser and/or Renderer.
Adding a new Test Suite
Imagine that you've developed a new Syntax that is named xwiki/2.0. To test it you'd write the following unit test:
@RenderingTestSuite.Scope(value = "xwiki20.specific")
public class XWiki20SpecificTest implements RenderingTests
{
}
Running this will look for *.test files located in the classpath under the xwiki20/specific path (in term of sources files and Maven, this means putting your *.test files in src/main/resources/xwiki20/specific).
Adding Tests
Let's take an example to review the format of the *.test files. Imagine that we have a src/main/resources/xwiki20/specific/bold/bold2.test file with the following content:
.input|xwiki/2.0
.#-----------------------------------------------------
This is **bold ** not bold** bold
.#-----------------------------------------------------
.expect|event/1.0
.#-----------------------------------------------------
beginDocument
beginParagraph
onWord [This]
onSpace
onWord [is]
onSpace
beginFormat [BOLD]
onWord [bold]
onSpace
endFormat [BOLD]
onSpace
onWord [not]
onSpace
onWord [bold]
beginFormat [BOLD]
onSpace
onWord [bold]
endFormat [BOLD]
endParagraph
endDocument
.#-----------------------------------------------------
.expect|xwiki/2.0
.#-----------------------------------------------------
This is **bold ** not bold** bold**
Let's understand what it does:
- Comment lines start with .#.
- Directives start with .. For example:
- .input|xwiki/2.0 is an input directive that specifies the xwiki/2.0 syntax.
- .expect|event/1.0 is an output directive that specifies the event/1.0 syntax (this is a special syntax that makes it easy to print XDOM blocks)
- The RenderingTests code will do the following: for each input directive it can find, it uses the defined input syntax to find a matching Parser and it generates an XDOM from it. Then it looks for all defined output directives and for each one of them, it'll find a Renderer matching the output syntax and render the XDOM with it and verify that the result is the one defined.
If you execute the test suite above you'll get:
The screenshots shows that 2 tests were executed:
- Test 1: Using the xwiki/2.0 input content and verifying that the Parser generates an XDOM that when rendered with the event/1.0 syntax generates the content defined in the test
- Test 2: Using the xwiki/2.0 input content and verifying that the Parser generates an XDOM that when rendered with the xwiki/2.0 syntax generates the content defined in the test
Note that when we have an input content similar to the output content (we want to verify a full round trip, using both Parser and Renderer for a given syntax) we can use the .inputexpect shortcut notation, as in:
.inputexpect|xwiki/2.0
.#-----------------------------------------------------
This is **bold ** not bold** bold
.#-----------------------------------------------------
.expect|event/1.0
.#-----------------------------------------------------
beginDocument
beginParagraph
onWord [This]
onSpace
onWord [is]
onSpace
beginFormat [BOLD]
onWord [bold]
onSpace
endFormat [BOLD]
onSpace
onWord [not]
onSpace
onWord [bold]
beginFormat [BOLD]
onSpace
onWord [bold]
endFormat [BOLD]
endParagraph
endDocument
Advanced
Pattern
If you wish your test suite to only execute a single test (to debug only this test for example), you can add the pattern value in the Scope annotation. For example the following will only execute the /bold2.test test:
public class XWiki20SpecificTest implements RenderingTests
{
}
Transformations
You may want to execute Macro Transformations on the parsed XDOM (to generate a modified XDOM) before doing the verification with the expected output. This can be achieved by adding the .runTransformations directive, as in:
.#-----------------------------------------------------
.input|xwiki/2.1
.# Test the macro in inline mode
.#-----------------------------------------------------
This is inline {{example parameter="hello"/}}
.#-----------------------------------------------------
.expect|xhtml/1.0
.#-----------------------------------------------------
<p>This is inline hello</p>
.#-----------------------------------------------------
.expect|event/1.0
.#-----------------------------------------------------
beginDocument
beginParagraph
onWord [This]
onSpace
onWord [is]
onSpace
onWord [inline]
onSpace
beginMacroMarkerInline [example] [parameter=hello]
onWord [hello]
endMacroMarkerInline [example] [parameter=hello]
endParagraph
endDocument
You can specify the exact list of transformations to execute using the synta:
For example to run only the Macro transformation:
When not specified, all transformations found in the context class loader are executed.
Mocking
You may wish to perform some initialization of mocks before running the tests. This can be achieved by adding a method annotated with @RenderingTestSuite.Initialized and accepting a MockitoComponentManager parameter, as in the following example:
@AllComponents
public class WikiIntegrationTests implements RenderingTests
{
@RenderingTests.Initialized
public void initialize(MockitoComponentManager componentManager) throws Exception
{
componentManager.registerComponent(MockWikiModel.getComponentDescriptor());
// Add InterWiki Definition for links28 test
DefaultRenderingConfiguration renderingConfiguration =
(DefaultRenderingConfiguration) componentManager.getInstance(RenderingConfiguration.class);
renderingConfiguration.addInterWikiDefinition("knownalias", "http://server/common/url/");
}
}
Also notice the usage of the @AllComponents annotation which tells the Rendering Test Site to automatically register all XWiki Components found in the ClassLoader used to load this test. You could also use the @ComponentList({...}) annotation to only register some components. For example:
DefaultBeanManager.class,
DefaultConverterManager.class,
EnumConverter.class,
ConvertUtilsConverter.class
})
