About

Docker runs applications in containers with environment prepared for your application. The smartbear/readyapi-testengine docker image provides you with preconfigured environment with the installed TestEngine that you can use to run ReadyAPI functional tests in container.

Docker image

To run a TestEngine in Docker, use the following image from Docker Hub:

https://hub.docker.com/r/smartbear/readyapi-testengine/

Required license

TestEngine requires a SmartBear ID-based license to run in a docker container. To learn how to do that, see Licensing TestEngine. If you are installing headlessly, you can use the CLI to install an ID-based license.

Hardware requirements

This topic describes how to use Docker with TestEngine on the Hyper-V virtualization platform. To do that, use the same environment you use to run your Docker images. There are no specific requirements for this.

To learn more, see the Docker documentation:

To run TestEngine tools in Docker containers on other virtualization platforms, additional configuration may be required. Please see the corresponding documentation.

Pulling TestEngine image from Docker Hub

To get TestEngine Docker image, pull it from Docker Hub. To do this, use the following command:

docker pull smartbear/readyapi-testengine

Docker command syntax

To run TestEngine in a Docker container, use the following command line:

docker run -p <host-port>:8080 smartbear/readyapi-testengine

Arguments

-v=Extensions Folder:/ext

Specifies the folder whose content should be copied to the /bin/ext folder of the TestEngine installation in the container. Use this argument if your project requires additional libraries, such as database drivers or plugins.

Usage: -v="C:\Work\ReadyAPI Extensions":/ext

Note:

On some systems, you may need to change the path in the following way:

"C:\Work\ReadyAPI Extensions" -> "/host_mnt/C/Work/ReadyAPI Extensions"

-v=TestEngine data:/data

Specifies the folder where you store TestEngine data: test job history, added users, information on activated licenses, and so on. If there is no data, TestEngine creates it. Use this argument to pass TestEngine data between several container runs.

Usage: -v="C:\Work\TestEngine data":/data

Note:

On some systems, you may need to change the path in the following way:

"C:\Work\TestEngine data" -> "/host_mnt/C/Work/TestEngine data"

-e TESTENGINE_PASSWORD=<password>

Specifies the password of the default administrator account when you run a container without TestEngine data, or if it is empty. Also, you set the password when resetting the account by using the ‑e TESTENGINE_RESET_ADMIN_ACCOUNT=true option.

Usage: -e TESTENGINE_PASSWORD=p@ssw0rd

If not specified, TestEngine generates a random password and prints it to the output log. See Default admin account.

-e TESTENGINE_RESET_ADMIN_ACCOUNT=true

Commands TestEngine to reset the password of the default administrator account. To set a specific password instead of the generated one, use the ‑e TESTENGINE_PASSWORD=<password> option.

Usage: -e TESTENGINE_RESET_ADMIN_ACCOUNT=true

-p <host-port>:8080

Required. Binds the container port on which TestEngine runs, to a port on a host machine.

Usage: -p 8082:8080

readyapi-testengine

Required. Specifies the image to create a container from.

Sample full command

docker run -v="C:\Work\ReadyAPI\ext":/ext -p 8082:8080 smartbear/readyapi-testengine

Using Environment Variables in TestEngine Docker Image

TestEngine's Docker image supports a range of environment variables to customize the application's behavior. These variables allow you to define user credentials, roles, JVM options, and license settings, among other configurations.

Supported Environment Variables

Variable	Description
`TestEngineUser`	The username added as an admin user in the TestEngine database.
`TestEnginePassword`	The password associated with the `TestEngineUser`.
`TestEngineUserRole`	Specifies the user's role. Set to `admin` to grant administrator privileges.
`TestEngineVMOptions`	Specifies JVM options.
`SlmAccessKey`	Specifies the access key required when using SmartBear-hosted ID-based licenses or when the license is hosted on an on-premise license server with `Access for Everyone` turned off and authentication enabled.
`ConfigFilePath`	Specifies an optional image-relative path to an alternative configuration file.
`Flags`	A set of feature flags or options used to enable or disable specific functionalities or behaviors within the application at runtime (for example, the flag `groovy.allow.all`).
`TestEngineClassPathExt`	Specifies the location of the `ext` directory for adding additional JAR files.

Syntax for Declaring Environment Variables

To declare Flags and TestEngineVMOptions as lists:

-e Flags='someFlag=someValue,someFlag2=someValue2'
-e TestEngineVMOptions='some.vmoption=someValue,some.vm.option.2=someValue'
For other variables, use a simple declaration:

-e TestEngineUser=someUser

Example Usage

Scenario	Command
User with Admin Role	docker run -p 8080:8080 -e TestEngineUser=newOne -e TestEnginePassword=password -e TestEngineUserRole=admin testengine-test10
User without Admin Role (Default Admin Created)	docker run -p 8080:8080 -e TestEngineUser=newOne -e TestEnginePassword=password testengine-test10
VM Options	docker run -p 8080:8080 -e TestEngineVMOptions=some.vmoption=someValue,some.vm.option.2=someValue testengine-test10
Default Admin with SLM License	docker run -p 8080:8080 -e SlmAccessKey=****----********** testengine-test10
Default Admin with SLM License and New User	docker run -p 8080:8080 -e TestEngineUser=newOne -e TestEnginePassword=password -e SlmAccessKey=****----********** testengine-test10
New Admin User with SLM License	docker run -p 8080:8080 -e TestEngineUser=newOne -e TestEnginePassword=password -e TestEngineUserRole=admin -e SlmAccessKey=****----********** testengine-test10
Default Admin with On-Prem License	docker run -p 8080:8080 -e SlmAccessKey=****----********** -e SlmServer=http://52.200.52.234:40892 testengine-test10
Config File Path	docker run -p 8080:8080 -e ConfigFilePath=/mnt/config.yaml -v C:\TestDocker\test-engine\mnt:/mnt/ testengine-test10
Location of the Ext Directory for Adding JARs	docker run -p 8080:8080 -e TestEngineClassPathExt=/mnt/ext/ -v C:\TestDocker\test-engine\mnt:/mnt/ testengine-test10

Get TestEngine URL running in a Docker container

To work with TestEngine running in a Docker container, you need to know its endpoint:

http://<host-address>:<binded-port>

where —

host-address - Address of the host machine where the container is running.
binded-port - Port on the host machine that you bind to the 8080 port on the container.

For example, if you run a container on a local machine with the following command:

docker run -p 8082:8080 smartbear/readyapi-testengine

TestEngine endpoint is the following:

http://localhost:8082

Troubleshooting

If you cannot run Docker due to the Drive has not been shared error, perform the following steps:

Right-click the Docker icon in the notification area and select Settings:
On the Shared Drives page of the Settings dialog, select all the drives you use to run the Docker container.

If your drives have already been shared, but the error occurs anyway, turn off sharing. After you apply the changes, repeat these steps to share the drives again.

To share your drivers, select them in the list and click Apply:

Click the image to enlarge it.

You may need to enter the credentials of your system account to apply the changes.