uiVeri5ExecuteTests¶
Executes UI5 e2e tests using uiVeri5
Deprecation notice
Details of changes after the step migrated to a golang based step can be found below.
Description¶
In this step the (UIVeri5 tests) are executed.
Usage¶
We recommend to define values of step parameters via .pipeline/config.yml file.
In this case, calling the step is essentially reduced to defining the step name.
Calling the step can be done either in an orchestrator specific way (e.g. via a Jenkins library step) or on the command line.
library('piper-lib-os')
uiVeri5ExecuteTests script: this
piper uiVeri5ExecuteTests
Outputs¶
Output type | Details |
---|---|
Prerequisites¶
Parameters¶
Overview - Step¶
Name | Mandatory | Additional information |
---|---|---|
script | (yes) | reference to Jenkins main pipeline script |
installCommand | no | |
runCommand | no | |
runOptions | no | |
testOptions | no | |
testServerUrl | no | |
verbose | no | activates debug output |
Overview - Execution Environment¶
Orchestrator-specific only
These parameters are relevant for orchestrator usage and not considered when using the command line option.
Name | Mandatory | Additional information |
---|---|---|
containerCommand | no | |
containerName | no | |
containerShell | no | |
dockerEnvVars | no | |
dockerImage | no | |
dockerName | no | |
dockerOptions | no | |
dockerPullImage | no | |
dockerVolumeBind | no | |
dockerWorkspace | no | |
sidecarEnvVars | no | |
sidecarImage | no | |
sidecarName | no | |
sidecarOptions | no | |
sidecarPullImage | no | |
sidecarReadyCommand | no | |
sidecarVolumeBind | no | |
sidecarWorkspace | no | |
stashContent | no |
Details¶
containerCommand¶
Jenkins-specific: Used for proper environment setup.
Kubernetes only: Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (/usr/bin/tail -f /dev/null).
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
containerName¶
Jenkins-specific: Used for proper environment setup.
Optional configuration in combination with containerMap to define the container where the commands should be executed in.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | uiVeri5 |
Secret | no |
Configuration scope |
|
Resource references | none |
containerShell¶
Jenkins-specific: Used for proper environment setup.
Allows to specify the shell to be executed for container with containerName.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerEnvVars¶
Jenkins-specific: Used for proper environment setup.
Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | map[NO_PROXY:localhost,selenium,$NO_PROXY no_proxy:localhost,selenium,$no_proxy] |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerImage¶
Jenkins-specific: Used for proper environment setup.
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | node:lts-buster |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerName¶
Jenkins-specific: Used for proper environment setup.
Kubernetes only: Name of the container launching dockerImage. SideCar only: Name of the container in local network.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | uiVeri5 |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerOptions¶
Jenkins-specific: Used for proper environment setup.
Docker options to be set when starting the container.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerPullImage¶
Jenkins-specific: Used for proper environment setup.
Set this to 'false' to bypass a docker image pull. Useful during development process. Allows testing of images which are available in the local registry only.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerVolumeBind¶
Jenkins-specific: Used for proper environment setup.
Volumes that should be mounted into the docker container.
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerWorkspace¶
Jenkins-specific: Used for proper environment setup.
Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME
.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | /home/node |
Secret | no |
Configuration scope |
|
Resource references | none |
installCommand¶
The command that is executed to install the uiveri5 test tool.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | npm install @ui5/uiveri5 --global --quiet |
Secret | no |
Configuration scope |
|
Resource references | none |
runCommand¶
The command that is executed to start the tests.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | /home/node/.npm-global/bin/uiveri5 |
Secret | no |
Configuration scope |
|
Resource references | none |
runOptions¶
Options to append to the runCommand, last parameter has to be path to conf.js (default if missing: ./conf.js).
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | - --seleniumAddress=http://localhost:4444/wd/hub |
Secret | no |
Configuration scope |
|
Resource references | none |
script¶
Jenkins-specific: Used for proper environment setup.
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.
Scope | Details |
---|---|
Aliases | - |
Type | Jenkins Script |
Mandatory | yes |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
sidecarEnvVars¶
Jenkins-specific: Used for proper environment setup.
A map of environment variables to set in the sidecar container, similar to dockerEnvVars
.
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
sidecarImage¶
Jenkins-specific: Used for proper environment setup.
The name of the docker image of the sidecar container. If empty, no sidecar container is started. Similar to dockerImage
.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
sidecarName¶
Jenkins-specific: Used for proper environment setup.
Name of the sidecar container. Similar to dockerName
.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
sidecarOptions¶
Jenkins-specific: Used for proper environment setup.
Options to be set when starting the sidecar container. Similar to dockerOptions
.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
sidecarPullImage¶
Jenkins-specific: Used for proper environment setup.
Set this to 'false' to bypass a docker image pull. Useful during development process. Allows testing of images which are available in the local registry only.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
sidecarReadyCommand¶
Jenkins-specific: Used for proper environment setup.
Command executed inside the container which returns exit code 0 when the container is ready to be used.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
sidecarVolumeBind¶
Jenkins-specific: Used for proper environment setup.
Volumes that should be mounted into the sidecar container. Similar to dockerVolumeBind
.
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
sidecarWorkspace¶
Jenkins-specific: Used for proper environment setup.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
stashContent¶
Jenkins-specific: Used for proper environment setup.
Specific stashes that should be considered for the step execution.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | - buildDescriptor - tests |
Secret | no |
Configuration scope |
|
Resource references | none |
testOptions¶
Deprecated and will result in an error if set. Please use runOptions instead. Split the testOptions string at the whitespaces when migrating it into a list of runOptions.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_testOptions (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
testServerUrl¶
URL pointing to the deployment.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_testServerUrl (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
verbose¶
verbose output
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
Exceptions¶
The parameter testOptions
is deprecated and is replaced by array type parameter runOptions
. Groovy templating for this parameter is deprecated and no longer supported.
Using the runOptions
parameter the 'seleniumAddress' for UIVeri5 can be set.
The former groovy implementation included a default for seleniumAddress in the runCommand. Since this is not possible with the golang-based implementation, the seleniumAddress has to be added to the runOptions. For jenkins on kubernetes the host is 'localhost', in other environments, e.g. native jenkins installations, the host can be set to 'selenium'.
runOptions: ["--seleniumAddress=http://localhost:4444/wd/hub", ..... ]
The parameter failOnError
is no longer supported on the step due to strategic reasons of pipeline resilience. To achieve the former behaviour with failOnError: false
configured, the step can be wrapped using try/catch in your custom pipeline script.
The installCommand
does not support queueing shell commands using &&
and |
operator any longer.
If you see an error like fatal: Not a git repository (or any parent up to mount point /home/jenkins)
it is likely that your test description cannot be found.
Please make sure to point parameter runOptions
to your conf.js
file like runOptions: [...., './path/to/my/tests/conf.js']
Examples¶
Passing credentials from Jenkins¶
When running acceptance tests in a real environment, authentication will be enabled in most cases. UIVeri5 includes features to automatically perform the login with credentials in the conf.js
. However, having credentials to the acceptance system stored in plain text is not an optimal solution.
Therefore, UIVeri5 allows templating to set parameters at runtime, as shown in the following example conf.js
:
// Read environment variables
const defaultParams = {
url: process.env.TARGET_SERVER_URL,
user: process.env.TEST_USER,
pass: process.env.TEST_PASS
};
// Resolve path to specs relative to the working directory
const path = require('path');
const specs = path.relative(process.cwd(), path.join(__dirname, '*.spec.js'));
// export UIVeri5 config
exports.config = {
profile: 'integration',
baseUrl: '\${params.url}',
specs: specs,
params: defaultParams, // can be overridden via cli `--params.<key>=<value>`
auth: {
// set up authorization for CF XSUAA
'sapcloud-form': {
user: '\${params.user}',
pass: '\${params.pass}',
userFieldSelector: 'input[id="j_username"]',
passFieldSelector: 'input[id="j_password"]',
logonButtonSelector: 'button[type="submit"]',
redirectUrl: /cp.portal\/site/
}
}
};
While default values for baseUrl
, user
and pass
are read from the environment, they can also be overridden when calling the CLI.
In a custom Pipeline, this is very simple: Just wrap the call to uiVeri5ExecuteTests
in withCredentials
:
withCredentials([usernamePassword(
credentialsId: 'MY_ACCEPTANCE_CREDENTIALS',
passwordVariable: 'password',
usernameVariable: 'username'
)]) {
uiVeri5ExecuteTests script: this, runOptions: ["--baseURL=NEW_BASE_URL", "--params.user=${username}", "--params.pass=${password}", "--seleniumAddress=http://localhost:4444/wd/hub", "./uiveri5/conf.js"]
}
Please note: It is not recommended to override any secrets with the runOptions, because they may be seen in the Jenkins pipeline run console output. During the withCredentials
call, the credentials are written to the environment and can be accessed by the test code.
The following example shows the recommended way to handle the username and password for a uiVeri5ExecuteTests call that needs authentication. The passwordVariable
and usernameVariable
need to match the environment variables in the test code.
withCredentials([usernamePassword(
credentialsId: 'MY_ACCEPTANCE_CREDENTIALS',
passwordVariable: 'TEST_PASS',
usernameVariable: 'TEST_USER'
)]) {
uiVeri5ExecuteTests script: this, runOptions: ["--seleniumAddress=http://localhost:4444/wd/hub", "./uiveri5/conf.js"]
}
There is also the option to use vault for test credentials.
In a Pipeline Template, a Stage Exit can be used to fetch the credentials and store them in the environment. As the environment is passed down to uiVeri5ExecuteTests, the variables will be present there. This is an example for the stage exit .pipeline/extensions/Acceptance.groovy
where the credentialsId
is read from the config.yml
:
void call(Map params) {
// read username and password from the credential store
withCredentials([usernamePassword(
credentialsId: params.config.acceptanceCredentialsId,
passwordVariable: 'password',
usernameVariable: 'username'
)]) {
// store the result in the environment variables for executeUIVeri5Test
withEnv(["TEST_USER=\${username}", "TEST_PASS=\${password}"]) {
//execute original stage as defined in the template
params.originalStage()
}
}
}
return this