Get test reports with Maven plugin

Introduction

Restlet Client allows you to use exported tests as an input for Maven plugin which generates JUnit-like reports and allows you to hook custom URLs where to get notified before or/and after a unit test is completed.

Get started in seconds

Open the project, service or scenario you want to test and click on the Export to maven button.

All you have to do then is download the full package, extract it and run mvn test in the extracted folder.

More configuration options

Choose the requests to run

The maven plugin takes a JSON configuration file as a parameter and runs it. That configuration file really is just an export of your repository or a subset of it.

If you want to run a specific set of tests, you can click on export on the bottom of the left panel of the Requests view, tab Repository and check the boxes that match the requests/scenarios etc... you want to run.

Place the downloaded JSON near the pom.xml you downloaded (see get started) and make sure to configure the pom.xml to use that JSON file (more information on that below).

POM example

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>my-first-api-test</artifactId>
  <version>1.2.3</version>

  <build>
    <plugins>
      <plugin>
        <groupId>com.restlet.client</groupId>
        <artifactId>maven-plugin</artifactId>
        <version>2.9.0</version>
        <executions>
          <execution>
            <phase>test</phase>

            <goals>
              <goal>test</goal>
            </goals>
            <configuration>
              <file>/path/to/json/configuration/file.json</file>
              <licenseKey>ENTER_YOUR_LICENSE_KEY_HERE</licenseKey>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

  <pluginRepositories>
    <pluginRepository>
      <id>nexus-public</id>
      <name>Nexus Release Repository</name>
      <url>http://maven.restlet.com</url>
    </pluginRepository>
  </pluginRepositories>
</project>

Plugin configuration

This Maven plugin comes with a number of parameters to tweak its behavior.

Name Type Mandatory Default Description
file File Yes X file path pointing to the Restlet Client export file
selectedEnvironment String No X a name of an environment to be used
licenseKey String Yes X A valid license key (see the "Get a license key" paragraph below)
stopOnFailure boolean No false stops processing build if an error/failure occurs
httpClientTimeoutInMs Integer false 60000 Time before HTTP time-out in milliseconds
variables Properties No X custom variables
xhrEmulation boolean No true Mimics the extension behaviour by adding headers automatically added by the browser, like accept-*
followRedirects String No NONE Indicates whether or not the Maven plugin should follow the redirections as it is possible through the extension settings in the browser. Possible values are NONE or ALL
beforeTest URL No X URL where to send a notification before a test starts
afterTest URL No X URL where to send a notification after a test is completed
begin URL No X URL where to send a notification before first test is executed
end URL No X URL where to send a notification after last test is completed
useMavenProxies boolean No false Indicates whether or not the proxy configured in ~/.m2/settings.xml should be used for your test's HTTP calls

To change them, modify the tag configuration in your pom.xml, see a configuration example below.

<configuration>
  <file>/path/to/json/configuration/file.json</file>
  <selectedEnvironment>QA</selectedEnvironment>
  <licenseKey>ENTER_YOUR_LICENSE_KEY_HERE</licenseKey>
  <stopOnFailure>true</stopOnFailure>
  <httpClientTimeoutInMs>30000</httpClientTimeoutInMs>
  <xhrEmulation>false</xhrEmulation>
  <followRedirects>ALL</followRedirects>
  <beforeTest>https://my-ci-api.com/api1/notifications</beforeTest>
  <afterTest>https://my-ci-api.com/api1/notifications</afterTest>
</configuration>

Get a license key

At start, the Restlet Client Maven plugin checks whether the user has recorded a license key. In case the license is missing or invalid, the user is asked to get one and configure it. Such license key is granted to users that purchase a team plan or above, and can be found in the Billing page.

Just copy/paste this value as the licenseKey parameter of the pom.xml file:

Get license key

In-build API test use case

The following examples will focus on the configuration block which can be found in the previous example.

Use a specific environment

In Restlet Client, a consistent set of variables is called an "environment". The user is able to setup several environments (for example, one for the production environment, one for the local environment, etc). If this functionality was used to build the scenario then it is possible to indicate to the maven-plugin which environment should be used.

For instance if a scenario is based on the localhost environment then the following configuration block would be used:

<configuration>
  <file>${project.basedir}/test.json</file>
  <selectedEnvironment>localhost</selectedEnvironment>
</configuration>

Override environment variables

The user can also override an environment variable.

Let's imagine that the API port is not the same on the test environment as on the development environment, then it is possible to override the environment port variable to provide the right value: 13337.

This is done by using the following configuration:

<configuration>
  <file>${project.basedir}/test.json</file>
  <selectedEnvironment>localhost</selectedEnvironment>
  <variables>
    <property>
      <name>port</name>
      <value>13337</value>
    </property>
  </variables>
</configuration>

Use specific proxy configuration

Use the system proxy configuration

If the proxy is configured system-wide, then just launch the plugin with a simple:

mvn test -Djava.net.useSystemProxies=true

Please note that this argument is available on recent Windows systems and on Gnome 2.x systems, for more information refer to the official Oracle documentation.

Maven proxy configuration

The Maven plugin can reuse the Maven's installation proxy configuration, defined in your settings.xml, simply by using the following configuration:

<configuration>
  <file>${project.basedir}/test.json</file>
  <useMavenProxies>true</useMavenProxies>
</configuration>

Please note that for now, the nonProxyHosts is not supported in the Maven plugin.

More information about Maven proxy configuration can be found on the dedicated documentation.

JVM proxy configuration

The proxy configuration can also be configured at runtime using the standard JVM arguments. For the official documentation on JVM networking arguments, please refer to Oracle Networking Properties.

Beware that JVM proxy configuration will be applied to all the JVM which will impact all the requests performed even by other Maven plugins and or targets.

HTTP proxy configuration

If your proxy is using the http protocol then the following arguments are available:

Name Default Description
http.proxyHost "" The hostname, or address, of the proxy server
http.proxyPort 80 The port number of the proxy server
http.proxyUser "" If the proxy used basic authentication, the authentication's username
http.proxyPassword "" If the proxy used basic authentication, the authentication's password
http.nonProxyHosts localhost|127.*|[::1] [Not supported] Indicates the hosts that should be accessed without going through the proxy

Given the previous arguments, the maven plugin can be used:

mvn test -Dhttp.proxyHost=192.168.1.127
HTTPS proxy configuration

If your proxy is using the https protocol then the following arguments are available:

Name Default Description
https.proxyHost "" The hostname, or address, of the proxy server
https.proxyPort 443 The port number of the proxy server
http.proxyUser "" If the proxy used basic authentication, the authentication's username
http.proxyPassword "" If the proxy used basic authentication, the authentication's password
http.nonProxyHosts localhost|127.*|[::1] [Not supported] Indicates the hosts that should be accessed without going through the proxy

Given the previous arguments, the maven plugin can be used:

mvn test -Dhttps.proxyHost=192.168.1.127

Notifications format

Before/After test notifications

  
POST [url]
Content-Type: application/json
…
  
  
{
   “name” : [test name],
   “event” : [BeforeTest|AfterTest],
   “result” : [Ok|Failure|Error] 	<- present only if event=afterTest
}
  

Begin/End notifications

  
POST [url]
Content-Type: application/json
…
  
  
{
   “event” : [Begin|End]
}