Writing a plugin

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.

Example

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 {

    @Override
    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());
    }

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

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

Plugin Examples

• Example plugin
• Overview plugin
• Proxy plugin