Maven Integration

Applies to ReadyAPI 3.53, last modified on May 15, 2024

If you use Maven in your development environment, you can include ReadyAPI tests in your builds. To do that, command Maven to download and use the ReadyAPI Maven plugin in your project.


To run ReadyAPI tests from Maven, you need the following:

  • The pom.xml file containing a reference to the ReadyAPI Maven plugin. Configure it correctly to get the ReadyAPI plugin from the Maven repository and add a ReadyAPI test to the test phase of the build lifecycle.

    See a sample Maven configuration here. If you already have your own configuration, copy the needed parts to it.

  • A ReadyAPI project file.

  • An appropriate Pro license. For example, if you run functional tests, you need a ReadyAPI Test Pro license. If ReadyAPI cannot find a license when you run it from Maven, it will ask you to activate it.

    Tip: You can use a trial license to try the integration out. To learn how to get it, see Online Activation of a Trial License Without ReadyAPI.

Maven downloads the required files and handles any dependencies.

Configure the execution environment

  • The Java version used by Maven must be the same as the one used in ReadyAPI (JDK 17.0.7 for ReadyAPI 3.53.0)

  • Maven uses a Java Virtual Machine (JVM) to run ReadyAPI tests. This machine uses properties that differ from those specified in the ReadyAPI vmoptions file.

    To specify properties in Maven:

    1. Create a .mvn directory in the Maven project directory.

    2. In the .mvn directory, create the jvm.config file with the following content:

      -Xms128m -Xmx4000m -XX:MinHeapFreeRatio=20 -XX:MaxHeapFreeRatio=40 --illegal-access=permit

    Next time, when you run a Maven build, it will use the specified options to create a virtual machine.

Run tests

To start a test, execute the Maven test command in the folder containing your pom.xml file. This command will run the test and generate reports for it. For example:

C:/Work/MvnSample> mvn test

See an example to learn more about using the pom.xml file for running ReadyAPI tests. To add more test properties, uncomment the corresponding elements (if they exist) or specify additional parameters.

To learn more about known issues and how to work around them, see Troubleshooting.


The Maven plugin supports two types of reports for ReadyAPI tests:

  • ReadyAPI JUnit reports.

    The Surefire Report plugin converts the JUnit XML reports created by ReadyAPI to Surefire HTML reports. Learn more about this plugin in the Apache documentation, and see a sample test that creates such a report.

  • Custom ReadyAPI reports: Require additional configuration, see below.

Fonts in Linux

ReadyAPI reports use some of Microsoft core fonts. Not all Linux installations include these fonts. If you have issues with creating reports:

  1. Install the mscorefonts package applicable for your Linux distributive.

  2. Copy TTF files from /usr/share/fonts/truetype/msttcorefonts to the <ReadyAPI Installation>/jre/lib/fonts directory.

Make sure to specify the <ReadyAPI Installation>/bin/reports directory in the Custom Reports Library field of the ReadyAPI tab in the Preferences window.

Custom ReadyAPI reports require assets and templates that, by default, are not present on test machines where ReadyAPI is not installed.

To work around this issue, retrieve the necessary data from any machine where ReadyAPI is installed:

  1. Copy the <ReadyAPI installation>/bin/reports folder to some location on your test machine.

  2. In ReadyAPI, go to Preferences > ReadyAPI.

  3. Set the path to the reports folder as the value of the Custom reports library option.

  4. Close ReadyAPI.

  5. Copy the <user home directory>/.readyapi/readyapi‑settings.xml file to some location on your test machine.

  6. (Optional) Restore the original value of the Custom reports library option on the Preferences > ReadyAPI tab.

On your test machine, add the following line to the configuration section of the pom.xml file:


If needed, see a sample Maven pom.xml file here.

Maven configuration for SmartBear ID Based Licensing

  1. You may provide your credentials by either enclosing them within the <slmAccessKey>Access_Key</slmAccessKey> tag, or by using the <slmUsername>Username</slmUsername> and <slmPassword>Password</slmPassword> tags.

  2. The server address and access settings for all users can be defined in the readyApiProperties. To enable access for everyone, set it to "true".

    • <readyApiProperties>















    • By default, the SmartBear license server is included and does not require additional configuration. However, if you have installed and configured an offline (on-premise) license server for your ID-based licenses, you need to specify the server address and port information.

See Also


Highlight search results