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 Docker container as per the instructions in the Configuring Docker containers topic.

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:
  1. Stop the container by running
    docker stop "CONTAINER  ID"
  2. Uninstall the image by running
    docker rmi -f "image ID"


  1. To run the test without using any agents, start the container:
    $ docker run --rm -e HCL_LICENSING_URL=<URL> HCL_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_LICENSING_URL=<URL> Specifies the URL of the license server, usually,
    HCL_LICENSING_ID=<ID> Specifies the cloud license server ID. If you are using a local license server, 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/ 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.
  2. 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
  3. 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.
  4. Initiate the test runs against the agents in one of the following ways:
    1. To facilitate a run where container agents will automatically connect the workbench container to run a schedule, install the Docker Compose tool.
      1. Create a docker-compose.yml file that specifies similar parameters as mentioned in step 5.
      2. 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.
      version: '2'
          image: <agentImageName>:<imageVersion>
            - MASTER_NAME=<workbenchImageName>
            - AGENT_NAME=<agentImageName>
          image: <agentImageName>:<imageVersion>
            - MASTER_NAME=<workbenchImageName>
            - AGENT_NAME=<agentImageName-2>
          image: <workbenchImageName>:<imageVersion>
          entrypoint: cmdline -workspace /runData/workspaceJuly10 -project 921proj -schedule Schedules/agentSched -results autoResults -stdout -exportlog /runData/agentSchedLogJuly10.txt
               - "7080:7080"
               - "7443:7443"
            - C:\Tests:/Tests
            - C:\runData:/runData
            - TEST_IMPORT_PATH=/Tests/
      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.
    2. 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 MASTER_PORT=PortNumber AGENT_NAME=NameofAgent AGENT_IP=AgentIP imageName:imageVersion
      Table 2. Description of parameters
      Command Description
      -dit Specifies that the agent container runs in the background.
      --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.
  5. 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