Configure TestEngine

Note

Starting with TestEngine 1.34.0, the Allowed File Paths and Allowed Connection Targets settings are deprecated. These settings no longer affect TestEngine behavior and are ignored even if configured through API or the readyapi-testengine.yaml file. In earlier TestEngine versions, these settings continue to work as before.

TestEngine general settings

TestEngine API allows you to view and modify the following settings:

  • Allowed paths (Deprecated)

    A list of paths to which TestEngine has access.

    Note

    Starting with TestEngine 1.34.0, this setting is no longer used by TestEngine. Any values defined through the API or configuration file are ignored. For earlier versions, this setting restricts the local file paths TestEngine can access.

  • Allowed connection targets (Deprecated)

    A list of endpoints to which TestEngine can send requests. The default value is * that allows any connection targets.

    Tip

    The setting supports the * wildcard symbol in the leftmost position. For example, you can specify the *.smartbear.com connection target to allow connections to all the subdomains of the smartbear.com domain.

    Note

    Starting with TestEngine 1.34.0, this setting is no longer used by TestEngine. Any values defined through the API or configuration file are ignored. In earlier versions, you can use the * wildcard symbol in the leftmost position (for example, *.smartbear.com) to allow all subdomains of a given domain.

  • Allowed incoming connection targets

    TestEngine

    Tip

    The setting supports the * wildcard symbol in the leftmost position. For example, you can specify the *.smartbear.com connection target to allow connections to all the subdomains of the smartbear.com domain.

    Important

    This setting is not available in the Web UI. To view or set the setting, use TestEngine’s API.

  • Maximum days to keep

    Test jobs created earlier than this date will be removed if you omit the before parameter when removing old test jobs.

  • Maximum jobs to keep

    Specifies the maximum number of jobs to keep when you omit the before parameter when removing old test jobs.

  • Allow test steps connecting to databases using JDBC

    When this setting is set to false (by default), TestEngine blocks all the JDBC connections. It means JDBC test steps and JDBC data sources will not work. Set it to true to enable them.

    Important

    When you enable this option, a malefactor can read information from local file-based databases.

You can edit them by using TestEngine API or Web UI.

Configuring via API

View settings

To get the current TestEngine settings, use the following command:

GET  http://<testengine-host>:8080/api/v1/settings

Authentication

The request must be authenticated by a TestEngine administrator.

For more details on SwaggerHub, refer to the ReadyAPI TestEngine API – Update Server Settings section.

Example

curl
curl -u user:password -X GET "http://localhost:8080/api/v1/settings"

In this example:

  • -u user:password

    Authenticates the request with the user’s credentials. This user must have admin permissions.

  • -X GET

    Specifies the GET method.

  • "http://localhost:8080/api/v1/settings"

    The endpoint of the request.

ReadyAPI

Tip

We recommend that you create a project using the TestEngine Swagger definition. It will make request creation easier. Otherwise, create the needed request from scratch.

  1. Select the GET request to the /settings resource:

    Configuring TestEngine: Selecting get settings request

  2. Open the Auth panel.

  3. Select the Basic (Built-in) authorization type.

    Tip

    If you use the same credentials in several requests, use authorization profiles.

  4. Specify the user credentials. This user must have admin permissions:

    Activate the license: Add authorization

  5. Send the request and see the response:

    Configuring TestEngine: getting TestEngine settings. settings request

Set settings

To modify TestEngine settings, use the following command:

PUT  http://<testengine-host>:8080/api/v1/settings

  • Body

    A JSON object containing one or more of the following settings. See the possible elements in the SwaggerHub specification. The omitted settings will not be modified.

    Important

    In TestEngine 1.34.0 and later, the following settings in the API request are accepted but ignored:

    • allowedFilePaths

    • allowedConnectTargets

    These settings remain present for backward compatibility but have no effect.

    For example:

    {
    "allowedFilePaths" : [
        "C:\\Work\\Tests\\Petstore"
    ],
    "allowedConnectTargets" : [
        "*.swagger.io"
    ]
}

  • Authentication

    The request must be authenticated by a TestEngine administrator.

For more details on SwaggerHub, refer to the ReadyAPI TestEngine API – Update Server Settings section.

Example

curl
curl -H "Content-Type: application/json" -d @settings.json -u user:password -X PUT "http://localhost:8080/api/v1/settings"

In this example:

  • -H "Content-Type: application/json"

    Specifies the Content-Type header that tells TestEngine the type of the payload content.

  • -d @settings.json

    Specifies payload for the request. This example refers to the settings.json file containing the settings to be set.

  • -u user:password

    Authenticates the request with the user’s credentials. This user must have admin permissions.

  • -X PUT

    Specifies the PUT method.

  • "http://localhost:8080/api/v1/settings"

    The endpoint of the request.

ReadyAPI

Tip

We recommend that you create a project using the TestEngine Swagger definition. It will make request creation easier. Otherwise, create the needed request from scratch.

  1. Select the PUT request to the /settings resource:

    Configuring TestEngine: Selecting post settings request

  2. Specify the desired settings as a payload for the request:

    Configuring TestEngine: Specifying payload

  3. Open the Auth panel.

  4. Select the Basic (Built-in) authorization type.

    Tip

    If you use the same credentials in several requests, use authorization profiles.

  5. Specify the user credentials. This user must have admin permissions:

    Activate the license: Add authorization

  6. Send the request and see the response:

    Configuring TestEngine: modifying TestEngine settings. settings request

Configuring via Web UI

  1. Go to the home page of TestEngine:

    http://<testengine-host>:<port>/

    For example, if TestEngine is installed on your local machine and you run it on the default port, use the following link:

    http://localhost:8080/

  2. Open the Server tab and modify the needed settings:

    Configuring TestEngine: Open the Settings tab

    To add a new entry to a list, click Add New Path or Add New Target and specify the needed path or connection target.

    To remove an entry from a list, click Remove the test job.

Change connection settings

To change the default TestEngine connection settings (the protocol and port), edit the readyapi-testengine.yaml configuration file in any text editor.

Important

We do not recommend that you modify other settings in the file, since it may cause errors.

Note

In TestEngine 1.34.0 and later, the settings related to allowed file paths and allowed connection targets in readyapi-testengine.yaml are ignored. The structure of the YAML file remains unchanged for compatibility with older TestEngine versions.

The file location depends on the operating system and on the permissions TestEngine or its installer has:

  • Windows

    <user folder>/.readyapi/readyapi-testengine.yaml

  • Linux and macOS

    If you installed TestEngine or ran it with root access:

    /etc/readyapi-testengine.yaml

    If you installed TestEngine without root access:

    /.readyapi/readyapi-testengine.yaml

Important

You need to restart TestEngine after modifying the file to apply the changes.

readyapi-testengine.yaml
Comments

server:

applicationConnectors:

TestEngine connection settings.

- type: http

port: 8080

These settings configure connections established through the HTTP protocol.

Integer. The port TestEngine will listen on for HTTP requests. Default: 8080.

#Uncomment these settings to enable communication with TestEngine through the HTTPS protocol.

# - type: https

# port: 8443

Integer. The port the service will listen on for HTTPS requests. Default: 8443.

# keyStorePath: example.keystore

The path to the Java keystore containing the TestEngine certificate.

# keyStorePassword: example

The password for accessing the keystore.

# validateCerts: false

Whether TestEngine validates certificates. If it is true, TestEngine will not start if the certificate has expired or is invalid.

Groovy restrictions

By default, Groovy scripting has limitations on writing data to properties and files. If you need fully functional Groovy scripts in your tests, you can turn off these restrictions.

Important

Turning off the restrictions can cause security vulnerabilities.

Note

Starting with TestEngine 1.34.0, Groovy scripts work without limitations. The -Dgroovy.allow.all=true VM option is no longer required. In earlier versions, you needed to enable unrestricted Groovy access by setting the groovy.allow.all system property.

To turn off the limitations, you need to set the groovy.allow.all system property to true. The way you do this depends on how you run TestEngine:

Executable file

  1. Go to the TestEngine installation folder.

  2. Open the ReadyAPITestEngine.vmoptions file in any text editor.

  3. Add the following line at the end of the file:

    -Dgroovy.allow.all=true

    Important

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

  4. Save the file and restart TestEngine.

Command line

When you use the .bat or .sh file to run TestEngine, add the system property to the script file:

  1. Open the script file (readyapi-testengine.bat/sh).

  2. Go to the last but one line and insert the system property between the JAVA_OPT variable and the -cp option:

    • .bat file:

      "%JAVA%" %JAVA_OPTS% -Dgroovy.allow.all=true -cp "%CLASSPATH%" com.smartbear.ready.testserver.ReadyApiTestServerMain %*

    • .sh file:

      "$JAVA $JAVA_OPTS -Dgroovy.allow.all=true -cp $READY_API_CLASSPATH com.smartbear.ready.testserver.ReadyApiTestServerMain "$@"

Docker

If you run TestEngine in a Docker container, pass the system property to the JVM_OPT_GROOVY environment variable:

Environment variable

Value

JVM_OPT_GROOVY

-Dgroovy.allow.all=true

For example, if you use the docker run command to start a container, add the -e JVM_OPT_GROOVY=-Dgroovy.allow.all=true option to the command:

docker run -e JVM_OPT_GROOVY=-Dgroovy.allow.all=true -p 8082:8080 -it smartbear/readyapi-testengine

Relative Paths to Project Resources

By default, ReadyAPI uses absolute paths to files. This approach must change when you use the same test on multiple machines or share it with multiple users because not all of them will have the files you need in the same place. To solve this issue, use the Resource Root project property.

Use alternative configuration file

By default, TestEngine uses the configuration file described above. You can make TestEngine use an alternative settings file.

To do this, run the TestEngine executable with the -c (--cfg) <arg> argument. For example:

Windows
testengine.exe --cfg C:\Work\alt-testengine-config.yaml
Linux/macOS
testengine.sh --cfg ~/alt-testengine-config.yaml

To avoid errors, copy the settings file to the needed place, then run TestEngine with the -c (--cfg) option, and change settings by using web UI or API if possible.

Deprecated settings

Starting with TestEngine 1.34.0, the following settings are deprecated:

  • Allowed File Paths (allowedFilePaths)

  • Allowed Connection Targets (allowedConnectTargets)

These settings are no longer used by TestEngine and are managed by the user’s own environment or network configuration. They remain available in the API and configuration file for backward compatibility, but have no effect. In earlier TestEngine versions, these settings continue to work as before.

See Also

In this section:
© 2025
Publication date: