diff --git a/documentation/docs/steps/newmanExecute.md b/documentation/docs/steps/newmanExecute.md new file mode 100644 index 0000000000..7a2bffe2a9 --- /dev/null +++ b/documentation/docs/steps/newmanExecute.md @@ -0,0 +1,70 @@ +# newmanExecute + +## Description + +This script executes your [Postman](https://www.getpostman.com) tests from a collection via the [Newman](https://www.getpostman.com/docs/v6/postman/collection_runs/command_line_integration_with_newman) command line collection. + +## Prequisites + +- prepared Postman with a test collection + +## Example + +Pipeline step: + +```groovy +newmanExecute script: this +``` + +This step should be used in combination with `publishTestResults`: + +```groovy +newmanExecute script: this, failOnError: false +publishTestResults script: this, junit: [pattern: '**/newman/TEST-newman.xml'] +``` + +## Parameters + +| name | mandatory | default | possible values | +|------|-----------|---------|-----------------| +| `dockerImage` | no | | | +| `failOnError` | no | | `true`, `false` | +| `gitBranch` | no | | | +| `gitSshKeyCredentialsId` | no | | | +| `newmanCollection` | no | | | +| `newmanEnvironment` | no | | | +| `newmanGlobals` | no | | | +| `newmanRunCommand` | no | | | +| `script` | yes | | | +| `stashContent` | no | | | +| `testRepository` | no | | | + +- `dockerImage` - Docker image for code execution. +- `failOnError` - Defines the behavior, in case tests fail. +- `gitBranch` - see `testRepository` +- `gitSshKeyCredentialsId` - see `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](https://github.com/postmanlabs/newman#newman-run-collection-file-source-options) +- `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](https://github.com/postmanlabs/newman#newman-run-collection-file-source-options) +- `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, for example, configuration parameters. +- `stashContent` - If specific stashes should be considered for the tests, you can pass this via this parameter. +- `testRepository` - In case the test implementation is stored in a different repository than the code itself, you can define the repository containing the tests using parameter `testRepository` and if required `gitBranch` (for a different branch than master) and `gitSshKeyCredentialsId` (for protected repositories). 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](../configuration.md). + +In following sections the configuration is possible:| parameter | general | step | stage | +|-----------|---------|------|-------| +| `dockerImage` |  | X | X | +| `failOnError` |  | X | X | +| `gitBranch` |  | X | X | +| `gitSshKeyCredentialsId` |  | X | X | +| `newmanCollection` |  | X | X | +| `newmanEnvironment` |  | X | X | +| `newmanGlobals` |  | X | X | +| `newmanRunCommand` |  | X | X | +| `script` | X | X | X | +| `stashContent` |  | X | X | +| `testRepository` |  | X | X | diff --git a/vars/newmanExecute.groovy b/vars/newmanExecute.groovy index cd2e2019b6..d45364ecab 100644 --- a/vars/newmanExecute.groovy +++ b/vars/newmanExecute.groovy @@ -11,16 +11,53 @@ import groovy.transform.Field @Field Set GENERAL_CONFIG_KEYS = STEP_CONFIG_KEYS @Field Set STEP_CONFIG_KEYS = [ + /** + * Docker image for code execution. + */ 'dockerImage', + /** + * Defines the behavior, in case tests fail. + * @possibleValues `true`, `false` + */ 'failOnError', + /** + * see `testRepository` + */ 'gitBranch', + /** + * see `testRepository` + */ 'gitSshKeyCredentialsId', + /** + * The test collection that should be executed. This could also be a file pattern. + */ 'newmanCollection', + /** + * Specify an environment file path or URL. Environments provide a set of variables that one can use within collections. + * see also [Newman docs](https://github.com/postmanlabs/newman#newman-run-collection-file-source-options) + */ 'newmanEnvironment', + /** + * 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](https://github.com/postmanlabs/newman#newman-run-collection-file-source-options) + */ 'newmanGlobals', + /** + * The shell command that will be executed inside the docker container to install Newman. + */ 'newmanInstallCommand', + /** + * The newman command that will be executed inside the docker container. + */ 'newmanRunCommand', + /** + * If specific stashes should be considered for the tests, you can pass this via this parameter. + */ 'stashContent', + /** + * In case the test implementation is stored in a different repository than the code itself, you can define the repository containing the tests using parameter `testRepository` and if required `gitBranch` (for a different branch than master) and `gitSshKeyCredentialsId` (for protected repositories). + * For protected repositories the `testRepository` needs to contain the ssh git url. + */ 'testRepository' ]