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 HCL_ONETEST_LICENSING_URL=<URL> HCL_ONETEST_LICENSING_ID=<server_ID> -v hostTestAssets:/containerTestAssets -v hostImportedData:/containerImportedData imageName:imageVersion cmdline -workspace //containerImportedData/workspace -project projectName -schedule testName -suite TestSuitePathAndName-results autoResults -stdout -exportlog /containerPathExtracted/testlog.txt -protocolinput "distributed.tests=/Tests/AFT_INPUT_XML.xml"

Table 1.
Command	Description
--rm	Removes the container after the run completes.
-e	Sets environment variables.
HCL_ONETEST_LICENSING_URL=<URL>	Specifies the URL of the license server, usually, https://hclsoftware.compliance.flexnetoperations.com.
HCL_ONETEST_LICENSING_ID=<ID>	Specifies the cloud license server ID. If you are using a Local License Server (LLS), do not use this variable. 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.
-protocolInput	Use this argument to run multiple Web UI tests in parallel on different browsers and locations. The tests are distributed across different agent locations. Specify the path to the XML file that lists the test assets, browsers, and agent locations.

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 hcl-onetest-<versionNumber>.tar.gz.
When the image is loaded, the following message is displayed - Loaded image: imageFileName:versionNumber
Create an XML file that lists the agents to be used for the distributed run of multiple tests using many browsers on multiple agent locations. For more information, see Running multiple tests simultaneously from command line.

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:
     - HCL_ONETEST_LICENSING_URL=<URL> HCL_ONETEST_LICENSING_ID=<ID>
      - 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 2. 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