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.
If you are comfortable with Maven, you can start by generating a Crawljax project. The generated sample project includes the example plugin used in this tutorial.
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.
<tr>
<td>PreCrawlingPlugin</td>
<td>Before loading the URL</td>
<td>Goto a login URL and log in</td>
</tr>
<tr>
<td>OnUrlLoadPlugin</td>
<td>After the initial URL is (re)loaded</td>
<td>Reset back-end state</td>
</tr>
<tr>
<td>OnFireEventFailedPlugin</td>
<td>Afte firing an event</td>
<td>Root-cause analysis when the fired event fails</td>
</tr>
<tr>
<td>DomChangeNotifierPlugin</td>
<td>After firing an event</td>
<td>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.</td>
</tr>
<tr>
<td>OnInvariantViolationPlugin</td>
<td>When an invariant violation is detected</td>
<td>Root-cause analysis, report the failed invariant</td>
</tr>
<tr>
<td>OnNewStatePlugin</td>
<td>When a new state is detected during crawling</td>
<td>Take screenshots, validate DOM tree</td>
</tr>
<tr>
<td>OnRevisitStatePlugin</td>
<td>When a state is revisited</td>
<td>Benchmarking, analysis</td>
</tr>
<tr>
<td>PreStateCrawlingPlugin</td>
<td>Before a new state is crawled</td>
<td>Logging candidate elements</td>
</tr>
<tr>
<td>PostCrawlingPlugin</td>
<td>After the crawling</td>
<td>Generating test cases from the state-flow graph</td>
</tr>
</tbody>
| Type | Executed | Examples |
|---|---|---|
| ProxyServerPlugin | Before the crawling, at the initialization of the core | Loading a custom proxy configuration in the used browser |
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 save each dynamic DOM state as a static HTML page. 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 save it to a file:
package com.crawljax.plugins;
import java.io.FileWriter;
import com.crawljax.core.CrawlSession;
import com.crawljax.core.plugin.OnNewStatePlugin;
public class SamplePlugin implements OnNewStatePlugin {
@Override
public void onNewState(CrawlSession session) {
try {
String dom = session.getBrowser().getDom();
String fileName = session.getCurrentState().getName() + ".html";
FileWriter fw = new FileWriter(fileName, false);
fw.write(dom);
fw.close();
} catch (Exception e) {
e.printStackTrace();
}
}
}You can use this plugin by adding it to your CrawljaxConfiguration instance in your “runner class”. This is done using the addPlugin method it provides. Note that in each execution point, the plugins are executed in the same order in which they are added using the addPlugin method.