This image is ready to go and ships with already installed:
docker pull taconsol/sakuli:<IMAGE_TAG>Tech previews of Sakuli containers are published as latest.
We highly recommend specifying the exact version of Sakuli for productive tests/checks.
Containers are tagged according to Sakuli versions, so in order to use Sakuli v2.4.0-1 in a test, one would pull the following image:
docker pull taconsol/sakuli:2.1.2You can find a list of available tags on Dockerhub
Docker allows to pass parameters when starting a new container:
docker run \
--rm \
-p 5901:5901 \
-p 6901:6901 \
[--shm-size=2G] \
taconsol/sakuli:2.4.0-1Parameters:
invalid session id errors due to crashed browsers.Sakuli Test Containers run as non-root user, the default UID is 1000.
In general, the structure of a containerized Sakuli test does not differ from any other Sakuli test. No changes are required when executing a test inside a container. The only configuration we have to provide, is information about how and which suite should be executed.
The default behaviour of a Sakuli Test Container is to run npm test to execute a test suite,
so to run a custom test we have to:
npm test within the test suite or projectThere are various ways to provide test sources to a container:
When running a Docker container it is possible to mount a file or directory on the Docker host into a container. This mechanism can be used to provide a Sakuli projects to a Sakuli container:
docker run \
-v /path/to/test/project/on/host:/sakuli_project \
taconsol/sakuli:2.4.0-1 /bin/bashBy adding the -v parameter we’re mounting the root folder of a Sakuli project at /path/to/test/project/on/host on our host machine to /sakuli_project inside the container.
We are now able to execute a test suite inside the container via sakuli run /sakuli_project/test_suite_folder.
Bind mounts are easy to use and very useful during development.
For further information, please refer to the Docker documentation on bind mounts
Instead of starting the test suite manually via /bin/bash, you could use the default entry point of the container.
To be able to do so, you have to specify the environment variable SAKULI_TEST_SUITE containing the path of the test suite to execute inside the container.
docker run \
-v /path/to/test/project/on/host:/sakuli_project \
-e SAKULI_TEST_SUITE=/sakuli_project/test_suite_folder \
taconsol/sakuli:2.4.0-1Once you have a test suite which should be put into work. Binding mounts might become cumbersome and makes it hard to reproduce certain state of the test project, suite or case. To ensure a reproducible environment, it would be feasible to build an explicit Docker image for test execution.
We can do so by creating our own Dockerfile next to our project directory:
FROM taconsol/sakuli:2.4.0-1
ADD . \$HOME/sakuli_project
ENV SAKULI_TEST_SUITE \$HOME/sakuli_project/testsuite-aUsing this Dockerfile, we can now build our own test image by running the following command where the dockerfile is located:
docker build -t name-of-my-image .We can now run the newly built image via:
docker run name-of-my-imageWhen working with added files and folders inside a container, one has to ensure correct file permissions for added files.
Available from v2.4.0
The Sakuli container provides a mechanism to clone a git repository containing a sakuli project at container start and subsequently executing a testsuite within it:
docker run -e GIT_URL=<REPOSITORY URL> -e GIT_CONTEXT_DIR=<RELATIVE PATH TO TESTSUITE> taconsol/sakuli:2.4.0-1GIT_URL specifies the URL of the repository to be cloned. To access a private repository, please ensure, your git service provides the possibility to authenticate via URL parameters.
This is possible with common git services like GitHub, Gitlab and Bitbucket.
To authenticate with a token on GitHub, use: https://<token>@github.com/<username>/<repository.git>.
GIT_CONTEXT_DIR is necessary to specify the path to the sakuli test suite inside the cloned repository.
npm testThe main configuration file of a npm project is its package.json file.
Within this file it’s possible to configure npm-scripts, a handy way to execute scripts inside an npm project.
An empty project initialised via npm init already contains one script: npm test
...
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
...
npm test is the default way of executing tests in a npm project, so Sakuli tests should be executed this way, too!
Since Sakuli is available in the container, we can run our test by simply calling sakuli run ... on npm test.
As your test suites are located within the same folder as our package.json, so a test suite can be run via:
...
"scripts": {
"test": "sakuli run /path/to/your/test/suite"
},
...
Reusing the package.json on project level comes with one limitation: You have only one “test” script available. If you decide to put multiple test suites into one project, we recommend putting a package.json on suite level as well.
{
"name": "test-suite",
"version": "1.0.0",
"scripts": {
"test": "sakuli run ."
}
}
Please notice that this is just suitable if you plan to execute the suite in the container.
This topic covers possible errors when running containerized Sakuli tests.
(Available from v2.5.0)
In case your test project requires additional dependencies, it’s possible to run npm install before executing the Sakuli test.
...
"scripts": {
"test": "npm i && sakuli run /path/to/your/test/suite"
},
...
The Container supports package installation, configurable via the environment variable
INSTALL_PACKAGES=true. This will install all packages defined in your package.json at container startup.
Note: Package versions installed inside the container will be overwritten by the version defined in the
package.json.
This might cause unexpected behavior, if overwriting e.g. Sakuli itself(@sakuli/cli)or forwarders. By installing third-party packages, the functionality of the packages and Sakuli itself can be impaired.
Sakuli test containers allow to configure specific details of their runtime environment.
Sakuli containers provide access to running containers via VNC on ports 5901 and 6901. By specifying port forwarding (-p) it is possible to configure which ports will be used to connect to a running container on the host system.
docker run --rm -p 5901:5901 -p 6901:6901 taconsol/sakuli:2.4.0-1The example above forwards container ports 5901 and 6901 to the same ports on the host system.
docker run --rm -p 5000:5901 -p 6000:6901 taconsol/sakuli:2.4.0-1In this example container port 5901 is forwarded to port 5000 on the host system, port 6901 is forwarded to port 6000 on the host system.
localhost:5000 would be used to connect to the container via VNC client, on localhost:6000 a webVNC view is available in the browser.
The default password to access a container via VNC is
vncpassword. It is highly recommended changing this password in production environments. See section #5.2 for details.
The following VNC environment variables can be overwritten at the docker run phase to customize your desktop environment inside the container:
VNC_COL_DEPTH, default: 24 // Color depth
VNC_RESOLUTION, default: 1280x1024 // Screen resolution
VNC_PW, default: vncpassword // VNC password
VNC_VIEW_ONLY, default: false // Run in view only mode, no keyboard / mouse interaction possibleFor example, the password for VNC could be set like this:
~\$ docker run -p 5901:5901 -p 6901:6901 -e VNC_PW=my-new-password taconsol/sakuli:2.4.0-1Per default all container processes will be executed with user id 1000.
Using root (user id 0): Add the --user flag to your docker run command:
~\$ docker run -it -p 5901:5901 -p 6901:6901 --user 0 taconsol/sakuli:2.4.0-1
Using user and group id of host system Add the --user flag to your docker run command:
~$ docker run -it -p 5901:5901 -p 6901:6901 --user $(id -u):\$(id -g) taconsol/sakuli:2.4.0-1
Internal infrastructure often uses custom certificates with own root CAs etc.
Things like untrusted certificates cause Sakuli tests to fail, since no connection to a seemingly insecure host will be established (InsecureCertificateError).
Unfortunately, browsers use their own certificate store, which requires some additional work to add custom certificates.
In order to add custom certificates to a Sakuli container, one has to provide two things:
SAKULI_TRUSTED_CERT_DIR which holds the path to the directory where certificates for import are located inside the containerIf the environment variable has been set, a startup script will pick up all certificates contained in the given folder
and import each of them to all available browser certificate stores within $HOME, supporting both cert8.db databases
for older browser versions as well as cert9.db files for recent browser versions.
~$ docker run -v /path/to/certificates/:/certificate_import -e SAKULI_TRUSTED_CERT_DIR=/certificate_import/ taconsol/sakuli:2.4.0-1By default, a Firefox test uses a new, blank profile for each test suite execution. In order to pick up the added certificates,
a Firefox profile containing the appropriate certificate database has to be specified via
selenium.firefox.profile=/path/to/profile/folder in testsuite.properties. In order to make this process easier, a
dedicated Firefox profile for use with certificates is located at /headless/firefox-certificates to be used, instead
of the generated profiles in /headless/.mozilla/firefox/long_random_id.default.
Attention: If this property is not set, added certificates will have no effect.
There are use cases that cannot be covered with the standard Linux based Sakuli container e.g. testing software that is
only available for Microsoft Windows or automating processes in SAP. If you still want to leverage the flexibility and
scalability of a container based Sakuli execution, we provide the sakuli-remote-connection container. This image
ships with a remmina installation to connect to a remote Windows machine using RDP.
To start remmina with a prepared configuration, please ensure to mount the required config file into the container using a volume or to create a base image with the configuration installed.
Sakuli check:
(async () => {
const remmina = new Application(`remmina --connect <path/to/remmina/config.rdp>`);
try {
await remmina.open();
await env.sleep(2); //wait for remmina to open
await env.type(Key.TAB)
.type(Key.TAB)
.type(Key.ENTER); //accept certificate
await env.paste("<Username>")
.type(Key.TAB)
.pasteAndDecrypt("<encryptedPassword>")
.type(Key.TAB)
.paste("<Domain>")
.type(Key.TAB)
.type(Key.TAB)
.type(Key.ENTER); //login to windows host
// perform actions on host
await remmina.close();
} catch (e) {
await testCase.handleException(e);
} finally {
await testCase.saveResult();
}
})();
Sample config.rdp:
screen mode id:i:2
session bpp:i:64
compression:i:1
keyboardhook:i:2
displayconnectionbar:i:1
disable wallpaper:i:1
disable full window drag:i:1
allow desktop composition:i:0
allow font smoothing:i:0
disable menu anims:i:1
disable themes:i:0
disable cursor setting:i:0
bitmapcachepersistenable:i:1
full address:s:35.158.200.121
audiomode:i:2
microphone:i:0
redirectprinters:i:0
redirectsmartcard:i:0
redirectcomports:i:0
redirectsmartcards:i:0
redirectclipboard:i:1
redirectposdevices:i:0
autoreconnection enabled:i:1
authentication level:i:0
prompt for credentials:i:1
negotiate security layer:i:1
remoteapplicationmode:i:0
alternate shell:s:
shell working directory:s:
gatewayhostname:s:
gatewayusagemethod:i:4
gatewaycredentialssource:i:4
gatewayprofileusagemethod:i:0
precommand:s:
promptcredentialonce:i:1
drivestoredirect:s:
To execute test actions on the RDP host, we recommend to use keyboard shortcuts instead of image recognition to increase stability. In case you want to use Sakuli browser interaction in your check, it is required to install a Selenium Server on the Windows host and configure Sakuli to connect the browser functionality with the Selenium Server.
| Environment Variable | Default Value | Description |
|---|---|---|
| SAKULI_TEST_SUITE | Path to Sakuli testsuite to be executed | |
| VNC_COL_DEPTH | 24 | Color depth of container monitor |
| VNC_RESOLUTION | 1280x1024 | Screen resolution of container |
| VNC_PW | vncpassword | Password to access NoVNC/VNC connection |
| VNC_VIEW_ONLY | false | Enable/Disable view-only mode |
| SAKULI_TRUSTED_CERT_DIR | Directory containing custom certificates for import | |
| GIT_URL | URL of git repository | |
| GIT_CONTEXT_DIR | Path to Sakuli testsuite within the git repository | |
| DEBUG | false | Enables debug mode for container startup |
| INSTALL_PACKAGES | false | Installs packages defined in the package.json at container startup (Available from v2.5.0) |
| LANGUAGE | en_US:en | Changes Language for Chrome (available values: en_US:en, de_DE:de) (System variable of Ubuntu) (available in tech preview) |
| LC_ALL | en_US.UTF-8 | Changes Language for Firefox (available values: en_US.UTF-8, de_DE.utf-8) (System variable of Ubuntu) (available in tech preview) |