Configure your pom files

Maven 3.3.1 or later is required.

We assume that you have a multi module project and the screenshot gallery should be aggregated from several modules and published with GitHub pages. You find a working example of the configuration described here in the Screenshot Maven Plugin project it self.

1. Configuration in the parent `pom`

Define as much as possible in the parent pom to avoid duplicated configuration.

1.1. Specify the following properties

<properties>
    <screenshot-maven-plugin.version>1.0.6-SNAPSHOT</screenshot-maven-plugin.version>
    <screenshotGalleryTarget>${maven.multiModuleProjectDirectory}/gh-pages/target/gallery-src</screenshotGalleryTarget> (1)
</properties>

${maven.multiModuleProjectDirectory} is a Maven built-in property (available since Maven 3.3.1) that always resolves to the directory containing the top-level pom.xml, regardless of which sub-module is being built. Use it as a stable root-relative path instead of maintaining per-module ../.. relative paths.

Specify a common directory for gallery screenshots from different modules.

1.2. Add a plugin element to the pluginManagement part

<pluginManagement>
    <plugins>
        <plugin>
            <groupId>se.bluebrim.maven.plugin</groupId>
            <artifactId>screenshot-maven-plugin</artifactId>
            <version>${screenshot-maven-plugin-version}</version>
            <configuration>
                <goalPrefix>screenshot</goalPrefix>
                <sourceCodeURL>${project.scm.url}/src/main/java</sourceCodeURL>
                <javaDocImageScale>0.6</javaDocImageScale>
                <locales>
                    <localeSpec> (1)
                        <language>en</language>
                        <country>US</country>
                    </localeSpec>
                </locales>
            </configuration>
            <executions>
                <execution>
                    <id>create-gallery</id>
                    <phase>verify</phase> (2)
                    <goals>
                        <goal>gallery</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>${screenshotGalleryTarget}</outputDirectory> (3)
                    </configuration>
                </execution>
            </executions>
        </plugin>
        .
        .
        .
    </plugins>
</pluginManagement>

1 In a previous version of the gallery goal it was possible to specify multiple locales and get a side-by-side view of screenshots. This feature is unavailable for now. Pick one locale at the time.

In this example the screenshot gallery is created in the default maven build cycle. The modules that provides gallery content are build before the gh-pages module by adding them as dependencies to the gh-pages module. You can exclude the gallery generation from the build cycle by specify <phase>none</phase> and then execute with the command:

mvn screenshot:gallery@create-gallery

The short screenshot: prefix requires the goalPrefix configuration shown above. When invoking a goal directly (not through lifecycle) the create-gallery execution configuration is used, so ${maven.multiModuleProjectDirectory} is already resolved and the aggregated gallery.adoc lands in the correct shared directory.

3 Specify a path to the directory where the gallery goal aggregates screenshots from different modules. Screenshot images are stored in a separate directory for each module.

Add a dependency element to the dependencyManagement part

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>se.bluebrim.maven.plugin</groupId>
            <artifactId>screenshot-maven-plugin-api</artifactId>
            <version>${screenshot-maven-plugin.version}</version>
            <scope>test</scope>
        </dependency>
        .
        .
        .
    </dependencies>
</dependencyManagement>

2. Configuration in module `pom`

Add the following to the pom files of modules containing Swing classes that you like to generate screenshots of.

<dependencies>
    <dependency>
        <groupId>se.bluebrim.maven.plugin</groupId>
        <artifactId>screenshot-maven-plugin-api</artifactId>
    </dependency>
    .
    .
    .
</dependencies>

The configuration above makes it possible to annotate test class method with @Screenshot. Since its most convenient to run the javadoc goal from command line you don’t have to add any plugin configuration in the build section. To run the gallery as part of your Maven build add the following in the build section:

<plugins>
    <plugin>
        <groupId>se.bluebrim.maven.plugin</groupId>
        <artifactId>screenshot-maven-plugin</artifactId>
    </plugin>
</plugins>

3. Add a gh-pages module

To create an aggregated screenshot gallery you need a common output directory for all modules that provides content to the gallery. Create a separate module and use its target directory for this purpose. That module also contains the AsciiDoc configuration necessary to process the generated Asciidoc to html. The gh-pages module in this project combines generated and handwritten AsciiDoc and publish it on GitHub pages.

Since other modules writes to the target directory of the gh-pages module before the gh-pages module is build, we must skip the cleaning by adding the following in the pom file:

<build>
    <plugins>
        <plugin>
            <artifactId>maven-clean-plugin</artifactId>
            <configuration>
                <skip>true</skip>
            </configuration>
        </plugin>
        .
        .
    </plugins>
</build>

Instead the cleaning of the gh-pages module is done at the beginning of the build by adding the following to the root parent pom file:

<build>
    <plugins>
        <plugin>
            <artifactId>maven-clean-plugin</artifactId>
            <configuration>
                <filesets>
                    <fileset>
                        <directory>gh-pages/target</directory>
                        <includes>
                            <include>**/*</include>
                        </includes>
                    </fileset>
                </filesets>
            </configuration>
        </plugin>
        .
        .
    </plugins>
</build>

4. Cross-module `targetClass`

The @Screenshot annotation accepts a targetClass parameter that names the class whose JavaDoc will receive the generated image. Since 1.0.6 this class may live in a different Maven module from the test class that creates the screenshot.

// Test class in module: com.example.feature
@Screenshot(targetClass = MyButton.class)  // MyButton is in module: com.example.core.ui
public JComponent createMyButtonScreenshot() {
    return new MyButton("Click me");
}

The plugin resolves the source file of targetClass by:

Searching the source directories of all reactor projects (available when building from the multi-module root).
Falling back to a filesystem sibling scan — walking up from the current project to the common modules parent and scanning every subdirectory for a src/main/java folder.

No extra configuration is needed. Run from the multi-module root to ensure all reactor projects are available:

mvn screenshot:javadoc

5. Test your configuration

Verify the configuration by adding the following classes to one of those modules:

In src/main/java add:

package se.bluebrim.maven.plugin.screenshot.example;

import java.awt.Color;

import javax.swing.BorderFactory;
import javax.swing.ImageIcon;
import javax.swing.JLabel;
import javax.swing.JPanel;

/**
 * The classic "Hello World" used to demonstrate the Screenshot Maven Plugin.
 * The camera image was found at: http://wefunction.com/2008/07/function-free-icon-set
 * <br>
 * <img src="doc-files/HelloWorldPanel.png" alt="Screenshot image of class: HelloWorldPanel">
 *
 * @author Goran Stack
 *
 */
@SuppressWarnings("serial")
public class HelloWorldPanel extends JPanel {

        public HelloWorldPanel()
        {
                JLabel label = new JLabel("Hello World from Screenshot Maven Plugin");
                ImageIcon icon;
                icon = new ImageIcon(getClass().getResource("camera.png"));
                label.setIcon(icon);
                label.setFont(label.getFont().deriveFont(32f));
                label.setForeground(Color.DARK_GRAY);
                add(label);
                setBorder(BorderFactory.createCompoundBorder(BorderFactory.createLineBorder(Color.RED.darker(), 4), BorderFactory.createEmptyBorder(60, 20, 60, 20)));
        }
}

In src/test/java add:

package se.bluebrim.maven.plugin.screenshot.example;

import javax.swing.JComponent;

import se.bluebrim.maven.plugin.screenshot.Screenshot;

public class HelloWorldPanelTest {

        @Screenshot
        public JComponent createScreenShot()
        {
                return new HelloWorldPanel();
        }
}

If you are using Eclipse adding these classes are very simple. Just copy the source from this page and paste it into the src/main or src/test folder in the Package Explorer view. Eclipse will create the package and the class for you.

From the command line run:

mvn screenshot:javadoc

A doc-files folder containing a HelloWorldPanel.png is created at the same location as the source code for HelloWorldPanel class.

The screenshot plugin detect the missing img tag in the Javadoc of HelloWorldPanel class and writes to the console.

[INFO] Missing "<img src="doc-files/HelloWorldPanel.png">" in class:se.bluebrim.maven.plugin.screenshot.example.HelloWorldPanel

To include the screenshot in the Javadoc of the HelloWorldPanel class copy the image tag from Maven console and paste into the Javadoc. You should now be able to see the image as part of the Javadoc.

6. Deploy content to GitHub Pages

Deployment to GitHub Pages is handled automatically by the build.yml GitHub Actions workflow. On every push to master, the workflow:

Runs mvn clean install (which generates the AsciiDoc gallery and HTML output in gh-pages/target/generated-docs).
Uploads the generated docs as a GitHub Pages artifact using actions/upload-pages-artifact.
Deploys the artifact to GitHub Pages using actions/deploy-pages.

6.1. GitHub Pages setup

To enable this for your own repository:

Go to your repository Settings > Pages.
Under Source, select GitHub Actions.
Ensure the workflow has pages: write and id-token: write permissions (already configured in build.yml).

Configure your pom files

1. Configuration in the parent pom

1.1. Specify the following properties

1.2. Add a plugin element to the pluginManagement part

2. Configuration in module pom

3. Add a gh-pages module

4. Cross-module targetClass

5. Test your configuration

6. Deploy content to GitHub Pages

6.1. GitHub Pages setup

1. Configuration in the parent `pom`

2. Configuration in module `pom`

4. Cross-module `targetClass`