Sauce Labs supports Docker images, providing you with a powerful way to orchestrate tests. In order to use Sauce Labs Orchestrate you will need to package your test code and all of its dependencies as a Docker image and publish it to a Docker container registry so that your tests can be run in the Sauce Labs infrastructure.
You can build and push images locally via Docker (Installation Requirements) or as part of your CI process. System requirements vary depending on your intention, so the following reference serves as a general guide.
Building and Pushing Images
- A working Docker installation. For more information, see Docker's Getting Started documentation.
Creating a Dockerfile
To create a custom image, you must create a Dockerfile, which is a text document containing commands that Docker uses to assemble an image.
COPY test-requirements.txt /demo-python
RUN pip install -r test-requirements.txt
COPY ./tests/ /demo-python/tests/
Choosing and Setting a Base Image
Before you create a custom image, you must choose another image from which to extend the custom image. Docker Hub has official, pre-built images for most popular languages and frameworks. Given a particular language or framework, there are many image variants from which to choose. These variants are specified by Docker tags.
For example, if you want to use version 3.5 of the official Alpine image, the full image name is
In your Dockerfile, extend the base image by using the FROM instruction.
Installing Additional Tools
To install any additional tools or run other commands, use the RUN instruction.
RUN apt-get update && apt-get install -y netcat
RUN go get github.com/jstemmer/go-junit-report
Adding Other Files and Directories
To add files and directories that are not present in package managers, use the ADD instruction.
ADD ./workdir/contacts /usr/bin/contacts
ADD ./db/migrations /migrations
After all of the required tools are specified in the Dockerfile it is possible to build the image.
docker build <path-to-dockerfile>
You’ll see how all commands specified in the Dockerfile are executed. If there are any errors they’ll be displayed and you’ll need to fix them before continuing. If the build is successful you’ll have something like this at the very end:
Successfully built e32703162dd4
Congratulations, you’ve just built your first image. Now we need to store it somewhere to make it available for Sauce Labs.
Pushing to a Registry
To allow Sauce Labs to use your custom image, store it in a public Docker Registry. The easiest mechanism is to create an account on Docker Hub because Docker Hub allows you to store unlimited public images for free. If your organization is already using Docker Hub, you can use your existing account.
To use an image with Sauce Labs Orchestrate you must have a public repository. If you want to keep your image private, refer to the Using Docker Authenticated Pulls document for instructions.
The example uses Docker Hub, but it is possible to use different registries, if you prefer. Adapt the example based on the registry you are using.
Docker Hub images, by default, are public; to keep images private, you need to use a private repository. For more information, see Creating a private repository.
Preparing the Image for the Registry
Log in to Docker Hub with your account and create a new repository on the Add repository page. It is best practice to use a pattern similar to
<project-name>-<container-name> for a repository name (for example,
Next, rebuild your image using your account and repository name:
$ docker build -t saucelabs/sl-demo-docker-primary:0.0.1 <path-to-dockerfile>
-t key specifies the name and tag of the new image:
- saucelabs - The account in Docker Hub
- sl-demo-docker-primary - The repository name
- 0.0.1 - The tag (version) of the image. Always update the tag if you change something in a Dockerfile, or you might have unpredictable results.
Pushing the Image to the Registry
To push the image to Docker Hub:
$ docker login
$ docker push saucelabs/sl-demo-docker-primary:0.0.1
First, we use docker login to authenticate in Docker Hub. If you use a registry other than Docker Hub, refer to the related documentation about how to push images to that registry.
Using your Image in Sauce Labs
After the image is successfully pushed, it is available for use in Sauce Orchestrate. Create a saucectl configuration like the one below. For more information, see saucectl Configuration.
- name: run sauce test
entrypoint: "mvn test"
- src: "runsauce.json"
Then run the following:
This only works if the config name follows a specific pattern and resides in a subfolder, for example
If the config name does not follow that pattern, you have to point to the config file explicitly, for example
saucectl run -c myconfig.yml.
The recommended approach for building images is to integrate this as a step in your existing CI pipelines. Below are examples for various CI providers you can reference.
The Sauce Labs demo repos contain GitHub Action code for building images.