seleniumExecuteTests

Description

Enables UI test execution with Selenium in a sidecar container.

This step is Jenkins-only.

The step executes a closure (see example below) connecting to a sidecar container with a Selenium Server.

When executing in a

• local Docker environment, please make sure to set Selenium host to selenium in your tests.
• Kubernetes environment, plese make sure to set Seleniums host to localhost in your tests.

Proxy Environments

If work in an environment containing a proxy, please make sure that localhost/selenium is added to your proxy exclusion list, e.g. via environment variable NO_PROXY & no_proxy. You can pass those via parameters dockerEnvVars and sidecarEnvVars directly to the containers if required.

Prerequisites

none

Example

seleniumExecuteTests (script: this) {
    git url: 'https://github.com/xxxxx/WebDriverIOTest.git'
    sh '''npm install
        node index.js'''
}

Example test using WebdriverIO

Example based on http://webdriver.io/guide/getstarted/modes.html and http://webdriver.io/guide.html

Configuration for Local Docker Environment

var webdriverio = require('webdriverio');
var options = {
    host: 'selenium',
    port: 4444,
    desiredCapabilities: {
        browserName: 'chrome'
    }
};

Configuration for Kubernetes Environment

var webdriverio = require('webdriverio');
var options = {
    host: 'localhost',
    port: 4444,
    desiredCapabilities: {
        browserName: 'chrome'
    }
};

Test Code (index.js)

// ToDo: add configuration from above

webdriverio
    .remote(options)
    .init()
    .url('http://www.google.com')
    .getTitle().then(function(title) {
        console.log('Title was: ' + title);
    })
    .end()
    .catch(function(err) {
        console.log(err);
    });

Parameters

name	mandatory	default	possible values
buildTool	no	npm	maven, npm, bundler
containerPortMappings	no	[selenium/standalone-chrome:[[containerPort:4444, hostPort:4444]]]
dockerEnvVars	no
dockerImage	no	buildTool=maven:maven:3.5-jdk-8 buildTool=npm:node:lts-bookworm buildTool=bundler:ruby:2.5.3-stretch
dockerName	no	buildTool=maven:maven buildTool=npm:npm buildTool=bundler:bundler
dockerOptions	no
dockerWorkspace	no	buildTool=maven:<empty> buildTool=npm:/home/node buildTool=bundler:<empty>
failOnError	no	true	true, false
gitBranch	no
gitSshKeyCredentialsId	no	``	Jenkins credentials id
script	yes
seleniumHubCredentialsId	no
sidecarEnvVars	no
sidecarImage	no	selenium/standalone-chrome
sidecarName	no	selenium
sidecarVolumeBind	no	[/dev/shm:/dev/shm]
stashContent	no	[tests]
testRepository	no

• buildTool - Defines the tool which is used for executing the tests
• containerPortMappings - Map which defines per docker image the port mappings, e.g. containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]].
• dockerEnvVars - Environment variables to set in the container, e.g. [http_proxy: 'proxy:8080'].
• dockerImage - Name of the docker image that should be used. Configure with empty value to execute the command directly on the Jenkins system (not using a container). Omit to use the default image (cf. default_pipeline_environment.yml) Overwrite to use custom Docker image.
• dockerName - Kubernetes only: Name of the container launching dockerImage. SideCar only: Name of the container in local network.
• dockerOptions - Docker only: Docker options to be set when starting the container (List or String).
• dockerWorkspace - Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME.
• failOnError - With failOnError the behavior in case tests fail can be defined.
• gitBranch - Only if testRepository is provided: Branch of testRepository, defaults to master.
• gitSshKeyCredentialsId - Only if testRepository is provided: Credentials for a protected testRepository
• script - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.
• seleniumHubCredentialsId - Defines the id of the user/password credentials to be used to connect to a Selenium Hub. The credentials are provided in the environment variables PIPER_SELENIUM_HUB_USER and PIPER_SELENIUM_HUB_PASSWORD.
• sidecarEnvVars - as dockerEnvVars for the sidecar container
• sidecarImage - as dockerImage for the sidecar container
• sidecarName - as dockerName for the sidecar container
• sidecarVolumeBind - as dockerVolumeBind for the sidecar container
• stashContent - Specific stashes that should be considered for the step execution.
• testRepository - Define an additional repository where the test implementation is located. For protected repositories the testRepository needs to contain the ssh git url.

Step configuration

We recommend to define values of step parameters via config.yml file.

In following sections of the config.yml the configuration is possible:

parameter	general	step/stage
buildTool	X	X
containerPortMappings	X	X
dockerEnvVars	X	X
dockerImage	X	X
dockerName	X	X
dockerOptions	X	X
dockerWorkspace	X	X
failOnError	X	X
gitBranch	X	X
gitSshKeyCredentialsId	X	X
script
seleniumHubCredentialsId	X	X
sidecarEnvVars	X	X
sidecarImage	X	X
sidecarName	X	X
sidecarVolumeBind	X	X
stashContent	X	X
testRepository	X	X

Dependencies

The step depends on the following Jenkins plugins

• credentials-binding
• docker
• git
• kubernetes
• pipeline-utility-steps
• workflow-basic-steps
• workflow-cps-global-lib
• workflow-durable-task-step

The kubernetes plugin is only used if running in a kubernetes environment. Transitive dependencies are omitted.

The list might be incomplete.

Consider using the ppiper/jenkins-master docker image. This images comes with preinstalled plugins.

Side effects

none

Exceptions

none