Skip to content

Commit 7a961ef

Browse files
OliverNoconOliverNocon
authored
seleniumExecuteTests - add step to run Selenium tests (#318)
It comes with an extension to executeDocker and executeDockerOnKubernetes to run sidecar containers. This helps to execute Selenium tests using two Docker images: 1. Execution runtime for tests (e.g. node image) 2. Selenium instance which holds Selenium server + browser * add documentation & some name cleanup * include PR feedback * add step documentation to structure
1 parent d0d4cac commit 7a961ef

12 files changed

+735
-80
lines changed

‎documentation/docs/images/k8s_env.png

9.43 KB
Loading

‎documentation/docs/steps/dockerExecute.md

+75-15
Original file line numberDiff line numberDiff line change
@@ -2,32 +2,73 @@
22

33
## Description
44

5-
Executes a closure inside a docker container with the specified docker image.
5+
Executes a closure inside a docker container with the specified docker image.
66
The workspace is mounted into the docker image.
77
Proxy environment variables defined on the Jenkins machine are also available in the Docker container.
88

99
## Parameters
1010

11-
| parameter | mandatory | default | possible values |
12-
| -------------------|-----------|-----------------------------------|----------------------------|
13-
| `script` | no | empty `globalPipelineEnvironment` | |
14-
| `dockerImage` | no | '' | |
15-
| `dockerEnvVars` | no | [:] | |
16-
| `dockerOptions` | no | '' | |
17-
| `dockerVolumeBind` | no | [:] | |
11+
| parameter | mandatory | default | possible values |
12+
| ----------|-----------|---------|-----------------|
13+
|script|yes|||
14+
|containerPortMappings|no|||
15+
|dockerEnvVars|no|`[:]`||
16+
|dockerImage|no|`''`||
17+
|dockerName|no|||
18+
|dockerOptions|no|`''`||
19+
|dockerVolumeBind|no|`[:]`||
20+
|dockerWorkspace|no|||
21+
|jenkinsKubernetes|no|`[jnlpAgent:s4sdk/jenkins-agent-k8s:latest]`||
22+
|sidecarEnvVars|no|||
23+
|sidecarImage|no|||
24+
|sidecarName|no|||
25+
|sidecarOptions|no|||
26+
|sidecarVolumeBind|no|||
27+
|sidecarWorkspace|no|||
1828

1929
* `script` defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration.
20-
* `dockerImage` Name of the docker image that should be used. If empty, Docker is not used.
21-
* `dockerEnvVars` Environment variables to set in the container, e.g. [http_proxy:'proxy:8080']
30+
* `containerPortMappings`: Map which defines per docker image the port mappings, like `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]`
31+
* `dockerEnvVars`: Environment variables to set in the container, e.g. [http_proxy:'proxy:8080']
32+
* `dockerImage`: Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.
33+
* `dockerName`: only relevant for Kubernetes case: Name of the container launching `dockerImage`
2234
* `dockerOptions` Docker options to be set when starting the container. It can be a list or a string.
2335
* `dockerVolumeBind` Volumes that should be mounted into the container.
36+
* `dockerWorkspace`: only relevant for Kubernetes case: specifies a dedicated user home directory for the container which will be passed as value for environment variable `HOME`
37+
* `sidecarEnvVars` defines environment variables for the sidecar container, similar to `dockerEnvVars`
38+
* `sidecarImage`: Name of the docker image of the sidecar container. Do not provide this value if no sidecar container is required.
39+
* `sidecarName`: as `dockerName` for the sidecar container
40+
* `sidecarOptions`: as `dockerOptions` for the sidecar container
41+
* `sidecarVolumeBind`: as `dockerVolumeBind` for the sidecar container
42+
* `sidecarWorkspace`: as `dockerWorkspace` for the sidecar container
2443

2544

2645
## Kubernetes support
27-
If the Jenkins is setup on a Kubernetes cluster, then you can execute the closure inside a container of a pod by setting an environment variable `ON_K8S` to `true`. However, it will ignore both `dockeOptions` and `dockerVolumeBind` values.
46+
If the Jenkins is setup on a Kubernetes cluster, then you can execute the closure inside a container of a pod by setting an environment variable `ON_K8S` to `true`. However, it will ignore `containerPortMappings`, `dockerOptions` and `dockerVolumeBind` values.
2847

2948
## Step configuration
30-
none
49+
50+
We recommend to define values of step parameters via [config.yml file](../configuration.md).
51+
52+
In following sections the configuration is possible:
53+
54+
| parameter | general | step | stage |
55+
| ----------|-----------|---------|-----------------|
56+
|script||||
57+
|containerPortMappings||X|X|
58+
|dockerEnvVars||X|X|
59+
|dockerImage||X|X|
60+
|dockerName||X|X|
61+
|dockerOptions||X|X|
62+
|dockerVolumeBind||X|X|
63+
|dockerWorkspace||X|X|
64+
|jenkinsKubernetes|X|||
65+
|sidecarEnvVars||X|X|
66+
|sidecarImage||X|X|
67+
|sidecarName||X|X|
68+
|sidecarOptions||X|X|
69+
|sidecarVolumeBind||X|X|
70+
|sidecarWorkspace||X|X|
71+
3172

3273
## Return value
3374
none
@@ -38,7 +79,7 @@ none
3879
## Exceptions
3980
none
4081

41-
## Example 1: Run closure inside a docker container
82+
## Example 1: Run closure inside a docker container
4283

4384
```groovy
4485
dockerExecute(dockerImage: 'maven:3.5-jdk-7'){
@@ -48,7 +89,7 @@ dockerExecute(dockerImage: 'maven:3.5-jdk-7'){
4889
## Example 2: Run closure inside a container in a kubernetes pod
4990

5091
```sh
51-
# set environment variable
92+
# set environment variable
5293
export ON_K8S=true"
5394
```
5495
@@ -58,7 +99,26 @@ dockerExecute(script: this, dockerImage: 'maven:3.5-jdk-7'){
5899
}
59100
```
60101
61-
In the above example, the `dockerEcecute` step will internally invoke [dockerExecuteOnKubernetes](dockerExecuteOnKubernetes.md) step and execute the closure inside a pod.
102+
In the above example, the `dockerEcecute` step will internally invoke [dockerExecuteOnKubernetes](dockerExecuteOnKubernetes.md) step and execute the closure inside a pod.
103+
104+
## Example 3: Run closure inside a container which is attached to a sidecar container (as for example used in [seleniumExecuteTests](seleniumExecuteTests.md):
105+
106+
```groovy
107+
dockerExecute(
108+
script: script,
109+
containerPortMappings: [containerPortMappings:'selenium/standalone-chrome':[containerPort: 4444, hostPort: 4444]],
110+
dockerImage: 'node:8-stretch',
111+
dockerName: 'node',
112+
dockerWorkspace: '/home/node',
113+
sidecarImage: 'selenium/standalone-chrome',
114+
sidecarName: 'selenium',
115+
) {
116+
git url: 'https://github.wdf.sap.corp/XXXXX/WebDriverIOTest.git'
117+
sh '''npm install
118+
node index.js
119+
'''
120+
}
121+
```
62122
63123
64124

‎documentation/docs/steps/dockerExecuteOnKubernetes.md

+71-18
Original file line numberDiff line numberDiff line change
@@ -4,29 +4,64 @@
44

55
Executes a closure inside a container in a kubernetes pod. Proxy environment variables defined on the Jenkins machine are also available in the container.
66

7-
## Prerequisites
7+
## Prerequisites
88
* The Jenkins should be running on kubernetes.
9-
* An environment variable `ON_K8S` should be created on Jenkins and initialized to `true`.
10-
9+
* An environment variable `ON_K8S` should be created on Jenkins and initialized to `true`. This could for example be done via _Jenkins_ - _Manage Jenkins_ - _Configure System_ - _Global properties_ - _Environment variables_
10+
11+
![Jenkins environment variable configuration](../images/k8s_env.png)
12+
1113
## Parameters
1214

13-
| parameter | mandatory | default | possible values |
14-
| -------------------|-----------|-----------------------------------|----------------------------|
15-
| `script` | no | empty `globalPipelineEnvironment` | |
16-
| `dockerImage` | yes | | |
17-
| `dockerEnvVars` | no | [:] | |
18-
| `dockerWorkspace` | no | '' | |
19-
| `containerMap` | no | [:] | |
15+
| parameter | mandatory | default | possible values |
16+
| ----------|-----------|---------|-----------------|
17+
|script|yes|||
18+
|containerCommands|no|||
19+
|containerEnvVars|no|||
20+
|containerMap|no|`[:]`||
21+
|containerName|no|||
22+
|containerPortMappings|no|||
23+
|containerWorkspaces|no|||
24+
|dockerEnvVars|no|`[:]`||
25+
|dockerImage|yes|||
26+
|dockerWorkspace|no|`''`||
27+
|jenkinsKubernetes|no|`[jnlpAgent:s4sdk/jenkins-agent-k8s:latest]`||
28+
|stashExcludes|no|`[workspace:nohup.out]`||
29+
|stashIncludes|no|`[workspace:**/*.*]`||
2030

2131
* `script` defines the global script environment of the Jenkins file run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration.
32+
* `containerCommands` specifies start command for containers to overwrite Piper default (`/usr/bin/tail -f /dev/null`). If container's defaultstart command should be used provide empty string like: `['selenium/standalone-chrome': '']`.
33+
* `containerEnvVars` specifies environment variables per container. If not provided `dockerEnvVars` will be used.
34+
* `containerMap` A map of docker image to the name of the container. The pod will be created with all the images from this map and they are labled based on the value field of each map entry.
35+
Example: `['maven:3.5-jdk-8-alpine': 'mavenExecute', 'selenium/standalone-chrome': 'selenium', 'famiko/jmeter-base': 'checkJMeter', 's4sdk/docker-cf-cli': 'cloudfoundry']`
36+
37+
* `containerName`: optional configuration in combination with containerMap to define the container where the commands should be executed in
38+
* `containerPortMappings`: Map which defines per docker image the port mappings, like `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]`
39+
* `containerWorkspaces` specifies workspace (=home directory of user) per container. If not provided `dockerWorkspace` will be used. If empty, home directory will not be set.
2240
* `dockerImage` Name of the docker image that should be used. If empty, Docker is not used.
2341
* `dockerEnvVars` Environment variables to set in the container, e.g. [http_proxy:'proxy:8080']
2442
* `dockerWorkspace` Docker options to be set when starting the container. It can be a list or a string.
25-
* `containerMap` A map of docker image to the name of the container. The pod will be created with all the images from this map and they are labled based on the value field of each map entry.
26-
Ex `['maven:3.5-jdk-8-alpine': 'mavenExecute', 'famiko/jmeter-base': 'checkJMeter', 's4sdk/docker-cf-cli': 'cloudfoundry']`
2743

2844
## Step configuration
29-
none
45+
46+
We recommend to define values of step parameters via [config.yml file](../configuration.md).
47+
48+
In following sections the configuration is possible:
49+
50+
| parameter | general | step | stage |
51+
| ----------|-----------|---------|-----------------|
52+
|script||||
53+
|containerCommands||X|X|
54+
|containerEnvVars||X|X|
55+
|containerMap||X|X|
56+
|containerName||X|X|
57+
|containerPortMappings||X|X|
58+
|containerWorkspaces||X|X|
59+
|dockerEnvVars||X|X|
60+
|dockerImage||X|X|
61+
|dockerWorkspace||X|X|
62+
|jenkinsKubernetes|X|||
63+
|stashExcludes||X|X|
64+
|stashIncludes||X|X|
3065

3166
## Return value
3267
none
@@ -39,36 +74,54 @@ none
3974

4075
## Example 1: Run a closure in a single container pod
4176
```sh
42-
# set environment variable
77+
# set environment variable
4378
export ON_K8S=true"
4479
```
4580
4681
```groovy
4782
dockerExecuteOnKubernetes(script: script, dockerImage: 'maven:3.5-jdk-7'){
48-
sh "mvn clean install"
83+
sh "mvn clean install"
4984
}
5085
```
5186
5287
In the above example, a pod will be created with a docker container of image `maven:3.5-jdk-7`. The closure will be then executed inside the container.
5388
5489
## Example 2: Run a closure in a multi-container pod
5590
```sh
56-
# set environment variable
91+
# set environment variable
5792
export ON_K8S=true"
5893
```
5994

6095
```groovy
6196
dockerExecuteOnKubernetes(script: script, containerMap: ['maven:3.5-jdk-8-alpine': 'maven', 's4sdk/docker-cf-cli': 'cfcli']){
6297
container('maven'){
63-
sh "mvn clean install"
98+
sh "mvn clean install"
6499
}
65100
container('cfcli'){
66101
sh "cf plugins"
67102
}
68103
}
69104
```
70105

71-
In the above example, a pod will be created with multiple Docker containers that are passed as a `containerMap`. The containers can be chosen for executing by referring their labels as shown in the example.
106+
In the above example, a pod will be created with multiple Docker containers that are passed as a `containerMap`. The containers can be chosen for executing by referring their labels as shown in the example.
72107

108+
## Example 3: Running a closure in a dedicated container of a multi-container pod
73109

110+
```sh
111+
# set environment variable
112+
export ON_K8S=true"
113+
```
74114
115+
```groovy
116+
dockerExecuteOnKubernetes(
117+
script: script,
118+
containerCommands: ['selenium/standalone-chrome': ''],
119+
containerMap: ['maven:3.5-jdk-8-alpine': 'maven', 'selenium/standalone-chrome': 'selenium'],
120+
containerName: 'maven',
121+
containerPortMappings: ['selenium/standalone-chrome': [containerPort: 4444, hostPort: 4444]]
122+
containerWorkspaces: ['selenium/standalone-chrome': '']
123+
){
124+
echo "Executing inside a Kubernetes Pod inside 'maven' container to run Selenium tests"
125+
sh "mvn clean install"
126+
}
127+
```

0 commit comments

Comments
 (0)