npmExecuteTests¶
Executes end-to-end tests using npm
[!WARNING] Please note, that the npmExecuteTests step is in beta state, and there could be breaking changes before we remove the beta notice.
Description¶
This step executes end-to-end tests in a Docker environment using npm.
The step spins up a Docker container based on the specified dockerImage
and executes the installScript
and runScript
from package.json
.
The application URLs and credentials can be specified in appUrls
and credentialsId
respectively. If wdi5
is set to true
, the step uses wdi5_username
and wdi5_password
for authentication.
The tests can be restricted to run only on the productive branch by setting onlyRunInProductiveBranch
to true
.
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')
npmExecuteTests script: this
piper npmExecuteTests
Outputs¶
Output type | Details |
---|---|
Parameters¶
Overview - Step¶
Name | Mandatory | Additional information |
---|---|---|
script | (yes) | |
baseUrl | no | |
envs | no | |
installCommand | no | |
passwordEnvVar | no | |
paths | no | |
runCommand | no | |
urlOptionPrefix | no | |
usernameEnvVar | no | |
vaultPassword | no | |
vaultURLs | no | |
vaultUsername | no | |
verbose | no | activates debug output |
workingDirectory | no |
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 |
Details¶
baseUrl¶
Base URL of the application to be tested.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | http://localhost:8080/index.html |
Secret | no |
Configuration scope |
|
Resource references | none |
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 | node |
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¶
Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | map[BASE_URL:${{params.baseUrl}} CREDENTIALS_ID:${{params.credentialsId}} NO_PROXY:localhost,selenium,$NO_PROXY no_proxy:localhost,selenium,$no_proxy] |
Secret | no |
Configuration scope |
|
Resource references | none |
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | node:lts-bookworm |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerName¶
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 | node |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerOptions¶
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¶
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 |
envs¶
List of environment variables to be set
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | $PIPER_envs (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
installCommand¶
Command to be executed for installation`.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | npm ci |
Secret | no |
Configuration scope |
|
Resource references | none |
passwordEnvVar¶
Env var for password.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | wdi5_password |
Secret | no |
Configuration scope |
|
Resource references | none |
paths¶
List of paths to be added to $PATH
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | $PIPER_paths (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
runCommand¶
Command to be executed for running tests`.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | npm run wdi5 |
Secret | no |
Configuration scope |
|
Resource references | none |
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.
Scope | Details |
---|---|
Aliases | - |
Type | Jenkins Script |
Mandatory | yes |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
sidecarEnvVars¶
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¶
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¶
Name of the sidecar container. Similar to dockerName
.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
sidecarOptions¶
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¶
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¶
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 |
urlOptionPrefix¶
If you want to specify an extra option that the tested url it appended to.
For example if the test URL is http://localhost
and urlOptionPrefix is --base-url=
,
we'll add --base-url=http://localhost
to your runScript.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_urlOptionPrefix (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
usernameEnvVar¶
Env var for username.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | wdi5_username |
Secret | no |
Configuration scope |
|
Resource references | none |
vaultPassword¶
The base URL password.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_vaultPassword (if set) |
Secret | no |
Configuration scope |
|
Resource references | Vault resource: name: appMetadataVaultSecretName default value: appMetadata Vault paths:
|
vaultURLs¶
An array of objects, each representing an application URL with associated credentials.
Each object must have the following properties:
- url
: The URL of the application.
- username
: The username for accessing the application.
- password
: The password for accessing the application.
Scope | Details |
---|---|
Aliases | - |
Type | []map[string]interface{} |
Mandatory | no |
Default | $PIPER_vaultURLs (if set) |
Secret | no |
Configuration scope |
|
Resource references | Vault resource: name: appMetadataVaultSecretName default value: appMetadata Vault paths:
|
vaultUsername¶
The base URL username.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_vaultUsername (if set) |
Secret | no |
Configuration scope |
|
Resource references | Vault resource: name: appMetadataVaultSecretName default value: appMetadata Vault paths:
|
verbose¶
verbose output
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
workingDirectory¶
Directory where your tests are located relative to the root of your project
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | . |
Secret | no |
Configuration scope |
|
Resource references | none |
Examples¶
Simple example using wdi5¶
stages:
- name: Test
steps:
- name: npmExecuteTests
type: npmExecuteTests
params:
baseUrl: "http://example.com/index.html"
This will run your wdi5 tests with the given baseUrl.
Advanced example using custom test script with credentials using Vault¶
stages:
- name: Test
steps:
- name: npmExecuteTests
type: npmExecuteTests
params:
installCommand: "npm install"
runCommand: "npm run custom-e2e-test"
usernameEnvVar: "e2e_username"
passwordEnvVar: "e2e_password"
baseUrl: "http://example.com/index.html"
urlOptionPrefix: "--base-url="
and Vault configuration in PIPELINE-GROUP-
{
"vaultURLs": [
{
"url": "http://one.example.com/index.html",
"username": "some-username1",
"password": "some-password1"
},
{
"url": "http://two.example.com/index.html",
"username": "some-username2",
"password": "some-password2"
}
],
"vaultUsername": "base-url-username",
"vaultPassword": "base-url-password"
}
This will run your custom install and run script for each URL from secrets and use the given URL like so:
npm run custom-e2e-test --base-url=http://one.example.com/index.html
Each test run will have their own environment variables set:
e2e_username=some-username1
e2e_password=some-password1
Environment variables are reset before each test run with their corresponding values from the secrets
Custom environment variables and $PATH¶
stages:
- name: Test
steps:
- name: npmExecuteTests
type: npmExecuteTests
params:
envs:
- "MY_ENV_VAR=value"
paths:
- "/path/to/add"
If you're running uiVeri5 tests, you might need to set additional environment variables or add paths to the $PATH variable. This can be done using the envs
and paths
parameters:
stages:
- name: Test
steps:
- name: npmExecuteTests
type: npmExecuteTests
params:
runCommand: "/home/node/.npm-global/bin/uiveri5"
installCommand: "npm install @ui5/uiveri5 --global --quiet"
runOptions: ["--seleniumAddress=http://localhost:4444/wd/hub"]
usernameEnvVar: "PIPER_SELENIUM_HUB_USER"
passwordEnvVar: "PIPER_SELENIUM_HUB_PASSWORD"
envs:
- "NPM_CONFIG_PREFIX=~/.npm-global"
paths:
- "~/.npm-global/bin"