Running automated tests with containerized workbench and agents from Docker

To simplify the deployment piece of Continuous Testing, you can use built Docker images to deploy the workbench and the agents and start testing in no time. You need not install the workbench and the agents on different machines. You can deploy the Docker images and use Docker commands to play back tests.

Before you begin

You must have configured the Docker container. See Configuring Docker containers.

You must already have exported the test assets to a location from where Docker can import them. For information about exporting the test assets, see Copying test assets with dependencies.

Note: The version number of the container images and the desktop products must match. If you have previous version of the container image, uninstall it and install the current version. To uninstall the image, use these commands:

Stop the container by running
```
docker stop "CONTAINER  ID"
```
.
Uninstall the image by running
```
docker rmi -f "image ID"
```
.

Procedure

To run the test without using any agents, start the container:

$ docker run --rm -e RATIONAL_LICENSE_FILE=PORT@HOST -v hostTestAssets:/containerTestAssets -v hostImportedData:/containerImportedData imageName:imageVersion cmdline -workspace //containerImportedData/workspace -project projectName -schedule testName -results autoResults -stdout -exportlog /containerPathExtracted/testlog.txt


Command	Description
--rm	Removes the container after the run completes.
-e	Sets environment variables.
RATIONAL_LICENSE_FILE=<PORT>@<HOST>	Specifies the port number of Rational License Key Server, usually 27000, and the server IP address. The floating license for the product and VT-packs must be on the license server.
`hostTestAssets`:`/containerTestAssets`	Specifies the folder location on the host machine and the container containing the compressed test assets (Zip format). Use both the locations to map one or more shared volumes to transfer data such as test assets, logs, and execution results between the host and the container.
`hostImportedData`:`/containerImportedData`	Specifies the workspace location on the host machine and the container containing the test assets that are not compressed. Results from the test execution are saved to the directory you specify on the host machine.
TEST_IMPORT_PATH=<PATH>	Specifies the location of the compressed test assets to be imported into the container. The location path is on the container side and not the host. For example, `/containerTestAssets/archiveName.zip`. The volume and path names are user defined and should be consistent.
imageName:imageVersion	Specifies the name of the image and its version to run.
cmdline	Specifies the existing command line arguments to define the location of the workspace, project name, test or schedule name, results file name, and the location of the exported logs.

After the test run completes, check the hostImportedData on the host machine to view the exported log.

To run the tests on containerized agents, load the agent images into the Docker repository:
```
tar --wildcards --to-command='docker load' -xzf <workbenchImageName> 'images/'*
```
For example, the workbench image name could be ibm-rtw-<versionNumber>.tar.gz.
When the image is loaded, the following message is displayed - Loaded image: imageFileName:versionNumber
Specify the agent details in the workbench. You can do this in one of the two ways:
- Specify all of the details in the local workbench and export the test assets to the directory that will be used by the containers to choose the tests.
- Bring up the workbench UI in the container to specify the agents in the schedule editor. To bring up the workbench UI in the container, install and configure an X11 server such as Xming on your host machine and specify -e DISPLAY=<IP>:0.0 parameter in the docker run command. The IP is the IP address of your host machine. For information about how to install and configure Xming, see its product documentation.
Note:
- If you use 'localhost' instead of the IP address with the default Docker settings, the container will forward the display to itself. If your IP is assigned via DHCP it is liable to change and you will need to update your container’s environment variable accordingly.
- Do not use underscores in the agent names.
To map a User Group with a specific agent, assign a static IP to the agent. To assign an IP to the agent, use the NODE_IP parameter along with the docker run command.

Note: Ensure that this IP matches with the IP specified for the Location asset in the workbench.

Initiate the test runs against the agents in one of the following ways:

To facilitate a run where container agents will automatically connect the workbench container to run a schedule, install the Docker Compose tool.

Create a docker-compose.yml file that specifies similar parameters as mentioned in step 5.
To run the tests, in the command prompt, navigate to the directory containing the yml file and run:
docker-compose up

In addition to the parameters in step 5, you must also specify the following two parameters in the yml file:

MASTER_NAME: Specify the name of the workbench container.
AGENT_NAME: Specify the name of the agent. The agent name defined in the schedule must match with the name of the agent container.

Sample compose file:

#SIMPLE DOCKER COMPOSE FILE/TEMPLATE
#BE SURE TO REPLACE ANY PROJECT-SPECIFIC NAMES/PATHS AND LICENSING VARIABLES WITH YOUR OWN VALUES
version: '2'
services:
  agent1:
    image: <agentImageName>:<imageVersion>
    environment:
      - MASTER_NAME=<workbenchImageName>
      - AGENT_NAME=<agentImageName>
    
  agent2:
    image: <agentImageName>:<imageVersion>
    environment:
      - MASTER_NAME=<workbenchImageName>
      - AGENT_NAME=<agentImageName-2>
    
  workbench:
    image: <workbenchImageName>:<imageVersion>
    entrypoint: cmdline -workspace /runData/workspaceJuly10 -project 921proj -schedule Schedules/agentSched -results autoResults -stdout -exportlog /runData/agentSchedLogJuly10.txt
    ports:
         - "7080:7080"
         - "7443:7443"
    volumes:
      - C:\Tests:/Tests
      - C:\runData:/runData
    environment:
      - RATIONAL_LICENSE_FILE=27000@<IP>
      - TEST_IMPORT_PATH=/Tests/agentProj.zip

Note: Docker Compose is included with some versions of Docker. The tool automates some network configurations and makes it easier to coordinate multiple containers. To check whether you have it, run docker-compose --version.

Start the agent containers by passing the following command as many times as you want the number of agents for the run. To start four agents, pass the command four times.

docker run -it -e MASTER_NAME=IP_ADDRESS -e MASTER_PORT=PortNumber -e AGENT_NAME=NameofAgent -e AGENT_IP=AgentIP imageName:imageVersion

Table 1. Description of parameters
Command	Description
-dit	Specifies that the agent container runs in the background.
-e	Sets environment variables.
--rm	Specifies to clean up the container and remove the file system when the container exits.
MASTER_NAME	Specifies the IP or host name of the workbench.
MASTER_PORT	Specifies the port number of the workbench. If you use the default port number of 7080, this command is optional.
AGENT _NAME	Specifies the name of the agent. When there are multiple agents running the test, the agent names helps you in identifying the results the agent is associated with.
AGENT_IP	Specifies the IP address of the agent.
imageName:imageVersion	Specifies the name and version of the image.

Verify whether the schedule has completed successfully. If you used an option such as -exportlog to output results to the shared volume, check the corresponding directory on your host machine that was mapped to hostImportedData to retrieve the exported data.

What to do next

If the test or schedule has completed successfully, the agent will likely be running. You might have to explicitly stop the agent by running

docker stop containerID

If you used Docker Compose tool to run the tests, you can stop the agents when the workbench container exits by running

docker-compose up --abort-on-container-exit