Modifying JVM Settings

Applies to ReadyAPI 3.56, last modified on November 21, 2024
Note: We have identified some use cases where ReadyAPI Windows users required broader character encoding through UTF-8. To set encoding to UTF-8, you need to make one configuration change to <readyapi-installation-folder>\bin\ReadyAPI.vmoptions. Insert a new line at the end and add -Dfile.encoding=UTF-8. Save, close the file, and open ReadyAPI. For additional details on setting the encoding to UTF-8, refer to this page.

When ReadyAPI runs, it passes a number of parameters to the Java virtual machine to prepare the environment. You can modify these parameters according to your needs.

Setting Command Line and JVM Options

Depending on how you run ReadyAPI, it passes the parameters from different locations:

Running ReadyAPI via... Passes parameters from...
Executable The helper .vmoptions file.
Command line The .bat/.sh script.

Note: To modify JVM options for command-line runners (testrunner.bat/.sh, loadtestrunner.bat/.sh, and so on) use the approach described for the ReadyAPI command line.

For the description of the JVM parameters, see Java Virtual Machine Parameters.

Note: Now users can use a file named readyapi-install.vmoptions to specify JVM options that ReadyAPI will incorporate post-installation. The file must be in the same directory as the ReadyAPI installer. This is introduced so that system administrators can set up necessary options for end users.

Running ReadyAPI via Executable

The ReadyAPI installer creates a *.vmoptions file that contains default arguments for the Java virtual machine. Here is a sample snippet of that file:

-Xms128m
-Xmx4096m
-Dsoapui.properties=soapui.properties
-Dgroovy.source.encoding=iso-8859-1
...

Open this file with any text editor and modify any parameter that you need. If the parameter is absent, you can add it.

The last line in the .vmoptions file must be followed by a new line.

Running ReadyAPI via Command Line

When you use the .bat or .sh file to run ReadyAPI, the Java virtual machine uses parameters specified in the script file. These parameters are stored in the JAVA_OPTS variable.

When the script calls Java, it passes the specified parameters as command-line arguments. You can find the desired parameter and modify it according to your needs. If the parameter is absent, you can add it.

Here is how variables look like in script files:

  • In the .bat file:

    set JAVA_OPTS=-Xms128m -Xmx%READY_XMX% -XX:MinHeapFreeRatio=20 -XX:MaxHeapFreeRatio=40 -XX:MaxPermSize=256m -Dsoapui.properties=soapui.properties

  • In the .sh file:

    JAVA_OPTS="-Xms128m -Xmx$READY_XMX -XX:MinHeapFreeRatio=20 -XX:MaxHeapFreeRatio=40 -XX:MaxPermSize=256m -Dsoapui.properties=soapui.properties

Adding New Parameters

To append a new parameter to the already specified parameters, specify the JAVA_OPTS variable itself before specifying the desired parameter. For example:

  • In the .bat file:

    set JAVA_OPTS=%JAVA_OPTS% -Dsoapui.browser.disabled="true"

  • In the .sh file:

    JAVA_OPTS="$JAVA_OPTS -Dsoapui.browser.disabled=true"

Add a parameter for parsing legacy JDBC connection strings’

As of Java 17.0.3 and from adopting 17.0.4 in ReadyAPI 3.41.0, the '_' characters are no longer allowed in JDBC connection strings.

If your existing tests have the '_' in their JDBC connection string, please add and use these JVM option:

  • when using the command line - Dcom.sun.jndi.ldapURLParsing="legacy"
  • when using *.vmoptions or vmoptions.txt file - Dcom.sun.jndi.ldapURLParsing=legacy

JVM option to prevent Vmoptions overwrite

You can now configure the Vmoptions file to prevent it from being updated or overwritten during ReadyAPI upgrades.

During the ReadyAPI installation process, a new empty file called "userDefinedVmOptions.vmoptions" is installed in the <user_home_dir>/.readyapi directory, if it was not present before.

For new installations of ReadyAPI (version 3.46.1 and later), the ReadyAPI.vmoptions file is stored locally in the <readyapi_installation_dir>/bin folder. At the end of this file, there is a line that includes userDefinedVmOptions.vmoptions. Any options added to the userDefinedVmOptions.vmoptions file are included within the local ReadyAPI.vmoptions file automatically. Users do not need to take additional action. Any user-specific additions should be made to the userDefinedVmOptions.vmoptions file.

For older ReadyAPI versions (prior to 3.46.1), the userDefinedVmOptions.vmoptions file is not created or included automatically. If users want to use shared vmoptions in their older versions, they can manually include it by adding a line like -include-options C:\Users\<user_directory>\.readyapi\userDefinedVmOptions.vmoptions in their local ReadyAPI.vmoptions file. ReadyAPI ignores any unrecognized options in the file.

If users uninstall ReadyAPI or update an existing installation that includes this change, the userDefinedVmOptions.vmoptions file remains in the .readyapi directory with all the specified options. Similarly, if users reinstall ReadyAPI, the file will still be present in the .readyapi folder with all the previously specified options, unless the user manually deletes it.

Note:

  • The default path of *.vmoptions file during installation is usually: C:\Program Files\SmartBear\ReadyAPI-3.4x.x\bin.

  • The default path of userDefinedVmOptions.vmoptions file during installation is usually: C:\Users\<UserName>\.readyapi.

Specifying Properties via Command Line

Using command-line arguments, you can modify system and global properties.

To specify system properties, use the -D argument:

-Dproperty.name=value

To specify global properties, use the -G argument:

-Gproperty_name=value

Also, you can load a list of properties from a file. To do this, use the following argument:

-Dsoapui.properties=file name

Note: The file name is a path to a file that contains properties to load.

By using command-line arguments, you can specify properties of a specific project, test suite, test case or virtual service. To do this, use the following pattern:

-Dsoapui.properties.testitem=file name

  • testitem – The name of the desired test item with spaces removed.

  • file name – The path to the file that contains the list of properties.

For example, to specify properties for “TestSuite 1”, use the following line:

-Dsoapui.properties.TestSuite1=testsuite1.properties

This will affect any test item the name of which matches this pattern. For example, the argument above will also affect test items with names “Test Suite 1”, “Test Suite1” or “T est S uite 1”, and so on.

See Also

Java Virtual Machine Parameters
JVM Settings

Highlight search results