Writing a plugin

Alex Nederlof edited this page Mar 28, 2014 · 18 revisions

Crawljax can easily be extended through plugins. Any programmer with basic Java knowledge can write plugins using the documentation on this page.

Plugin Template Generator

It is possible to generate a Crawljax project template through the Crawljax Maven archetype.

When using maven, all Crawljax plugins should inherit from plugins parent pom.

Types of Plugins

The main interface is Plugin, which is extended by the different types of plugins. Each plugin type serves as an extension point that is called in a different phase of the Crawljax execution. To write a plugin you should implement one of the following plugin types.

Type Executed Examples
PreCrawlingPlugin Before loading the URL Goto a login URL and log in, Loading a custom proxy configuration to intercept the request/response
OnUrlLoadPlugin After the initial URL is (re)loaded Reset back-end state
OnFireEventFailedPlugin Afte firing an event Root-cause analysis when the fired event fails
DomChangeNotifierPlugin After firing an event Notify the crawler if the state after the event is a new state (boolean). Can be used to override the default dom comparison of Crawljax.
OnInvariantViolationPlugin When an invariant violation is detected Root-cause analysis, report the failed invariant
OnNewStatePlugin When a new state is detected during crawling Take screenshots, validate DOM tree
OnRevisitStatePlugin When a state is revisited Benchmarking, analysis
PreStateCrawlingPlugin Before a new state is crawled Logging candidate elements
PostCrawlingPlugin After the crawling Generating test cases from the state-flow graph

Furthermore, if your plugin generates output in the form of files, it should implement the GenerateOutput inteface. This class gives you an easy way to get the absolute path the end-user would like to save any output files to.


Imagine we would like to log each dynamic DOM state as a static HTML page. This is demoed in ourAdvanced example. We can easily add this functionality to Crawljax by creating a plugin that implements the OnNewStatePlugin interface. When a new state is visited the onNewState method is called with a session object as its parameter. This allows us to get the current DOM from the browser and log it to the console:

public class SamplePlugin implements OnNewStatePlugin {

    public void onNewState(CrawlerContext context, StateVertex newState) {
        // This will print the DOM when a new state is detected. You should see it in your console.
        LOG.info("Found a new dom! Here it is:\n{}", context.getBrowser().getStrippedDom());

    public String toString() {
        return "Our example plugin";

You can enable this plugin using the addPlugin method in the configuration builder.

Plugin Examples

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.