

newmanExecute

Description

This script executes Postman tests from a collection via the Newman command line tool.

Prerequisites

• prepared Postman with a test collection

Parameters

name	mandatory	default	possible values
cfAppsWithSecrets	no
cloudFoundry/apiEndpoint	no
cloudFoundry/credentialsId	no
cloudFoundry/org	no
cloudFoundry/space	no
dockerEnvVars	no
dockerImage	no	node:lts-stretch
dockerOptions	no
dockerWorkspace	no
failOnError	no	true	true, false
gitBranch	no
gitSshKeyCredentialsId	no	``	Jenkins credentials id
newmanCollection	no	**/*.postman_collection.json
newmanEnvironment	no	``
newmanGlobals	no	``
newmanInstallCommand	no	npm install newman newman-reporter-html --global --quiet
newmanRunCommand	no	run '${config.newmanCollection}' --environment '${config.newmanEnvironment}' --globals '${config.newmanGlobals}' --reporters junit,html --reporter-junit-export 'target/newman/TEST-${collectionDisplayName}.xml' --reporter-html-export 'target/newman/TEST-${collectionDisplayName}.html'
script	yes
stashContent	no	[tests]
testRepository	no
verbose	no		true, false

• cfAppsWithSecrets - Define name array of cloud foundry apps deployed for which secrets (clientid and clientsecret) will be appended to the newman command that overrides the environment json entries (--env-var =${clientid} & --env-var =${clientsecret})
• cloudFoundry/apiEndpoint - Cloud Foundry API endpoint.
• cloudFoundry/credentialsId - Credentials to be used for deployment.
• cloudFoundry/org - Cloud Foundry target organization.
• cloudFoundry/space - Cloud Foundry target space.
• 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.
• 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 - Defines the behavior, in case tests fail.
• gitBranch - Only if testRepository is provided: Branch of testRepository, defaults to master.
• gitSshKeyCredentialsId - Only if testRepository is provided: Credentials for a protected testRepository
• newmanCollection - The test collection that should be executed. This could also be a file pattern.
• newmanEnvironment - Specify an environment file path or URL. Environments provide a set of variables that one can use within collections. see also Newman docs
• newmanGlobals - Specify the file path or URL for global variables. Global variables are similar to environment variables but have a lower precedence and can be overridden by environment variables having the same name. see also Newman docs
• newmanInstallCommand - The shell command that will be executed inside the docker container to install Newman.
• newmanRunCommand - The newman command that will be executed inside the docker container.
• 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.
• stashContent - If specific stashes should be considered for the tests, you can pass this via this parameter.
• testRepository - Define an additional repository where the test implementation is located. For protected repositories the testRepository needs to contain the ssh git url.
• verbose - Print more detailed information into the log.

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
cfAppsWithSecrets		X
cloudFoundry/apiEndpoint		X
cloudFoundry/credentialsId		X
cloudFoundry/org		X
cloudFoundry/space		X
dockerEnvVars		X
dockerImage		X
dockerOptions		X
dockerWorkspace		X
failOnError		X
gitBranch		X
gitSshKeyCredentialsId		X
newmanCollection		X
newmanEnvironment		X
newmanGlobals		X
newmanInstallCommand		X
newmanRunCommand		X
script
stashContent		X
testRepository		X
verbose		X

Side effects

Step uses dockerExecute inside.

Dependencies

The step depends on the following Jenkins plugins

• credentials-binding
• docker
• git
• http_request
• 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.

Exceptions

none

Example

Pipeline step:

newmanExecute script: this

This step should be used in combination with testsPublishResults:

newmanExecute script: this, failOnError: false
testsPublishResults script: this, junit: [pattern: '**/newman/TEST-*.xml']