Extensions

Extensions allow you to add functionality to Concordion, for example implementing new commands, listening to events, or modifying the Concordion output.

For full details, see the extension specifications. See also the classes in org.concordion.api.extension and the fixtures that demonstrate it.

Adding extensions to Concordion

Extensions are added to Concordion by:

Annotating the fixture class with @org.concordion.api.extension.Extensions. This annotation is parameterised with a list of extension, and/or extension factory, classes to be installed. For example:
```
@RunWith(ConcordionRunner.class)
@Extensions({LoggingTooltipExtension.class, TimestampFormatterExtension.class})
public class MyTest {
...
```
Or annotating public fields in the fixture class with @org.concordion.api.extension.Extension. This allows the extensions to be configured per class instance. For example:
```
...
@Extension
public ConcordionExtension extension = new ScreenshotExtension().setScreenshotTaker(camera);
...
```
Or by setting the system property "concordion.extensions" to a comma separated list of extension, and/or extension factory, classes. For example:
```
java -Dconcordion.extensions="org.concordion.ext.LoggingTooltipExtension,com.acme.MyExtension" ..
```

For further details see the extension configuration specification.

Building Your Own Extension

Extensions must implement the ConcordionExtension interface, which allows extensions to hook into the Concordion build phase through the ConcordionExtender interface.

Example - adding custom CSS

Amongst other features, the ConcordionExtender interface provide a means for adding CSS, JavaScript or arbitrary resources to the Concordion output folder.

The following example extension copies /my_concordion.css from the classpath to the root folder of the Concordion output, and links to it from the Concordion output HTML.

package com.acme;

public class MyCssExtension implements ConcordionExtension {
    @Override
    public void addTo(ConcordionExtender concordionExtender) {
        concordionExtender.withLinkedCSS("/my_concordion.css", new Resource("/my_concordion.css"));
    }
}

Note: if you have already declared a link to the CSS file in your HTML, you should use concordionExtender.withResource() rather than concordionExtender.withLinkedCSS() to avoid a duplicate declaration.

If you'd prefer to embed the CSS in the HTML, use concordionExtender.withEmbeddedCSS(). Similar methods exist for including JavaScript in the output, or you can use withResource() to copy images or other resources to the output.

Other examples

For examples that listen to events and add new commands, see the concordion-extensions source code.

concordion-extensions Library

The concordion-extensions project is a pre-built extensions library containing:

a ScreenshotExtension to add screenshots to Concordion output,
a LoggingTooltipExtension to add logging information as tooltips to the Concordion output,
a TimestampFormatterExtension to change the footer of the Concordion output to show hours, minutes and seconds,
a TranslatorExtension to modify the text of exception messages,
and an EmbedExtension to embed HTML in the Concordion output.

Installation

The extensions are packaged in the concordion-extensions jar, which can be downloaded from the Download page. You will need to ensure that both the concordion-extensions and concordion jars are on your classpath. The Concordion jar must be v1.4.1 or later.

Installing from Maven Central

Alternatively, this project is available in Maven Central, with a group id of org.concordion and an artifact id of concordion-extensions.

Example Project

The extensions example project demonstrates the Screenshot, Logging Tooltip and Translator extensions using Concordion and Selenium WebDriver for end-to-end browser testing.

This project can be downloaded from the concordion-extension downloads page (the concordion-extensions-demo zip file), or can be obtained from the source repository. It includes Gradle and Maven builds to download dependencies and build the project. See the README.html file in the download for instructions.

Issues and Discussion

Feel free to discuss concordion-extensions on the main Concordion mailing list.

Issues should be reported to the concordion-extensions issue list.