batsExecuteTests - add step for executing bats-core (#254)

details are available in the documentation contained in this PR

documentation/docs/steps/batsExecuteTests.md

@@ -0,0 +1,77 @@
+# batsExecuteTests
+
+## Description
+
+This step executes tests using the [Bash Automated Testing System - bats-core](https://github.com/bats-core/bats-core)
+
+## Prerequsites
+
+You need to have a Bats test file. By default you would put this into directory `src/test` within your source code repository.
+
+## Parameters
+
+| parameter | mandatory | default | possible values |
+|-----------|-----------|---------|-----------------|
+| script | no | empty `globalPipelineEnvironment` |  |
+| dockerImage | no | `node:8-stretch` | |
+| dockerWorkspace | no |`/home/node`| |
+| envVars | no | `[:]` | |
+| failOnError | no | `false` | |
+| gitBranch | no | | |
+| gitSshKeyCredentialsId | no | | |
+| outputFormat | no | `junit` | `tap` |
+| repository | no | `https://github.com/bats-core/bats-core.git` | |
+| stashContent | no | `['tests']` | |
+| testPackage | no | `piper-bats` | |
+| testPath | no | `src/test`| |
+| testRepository | no | | |
+
+
+Details:
+
+* `outputFormat` defines the format of the test result output. `junit` would be the standard for automated build environments but you could use also the option `tap`.
+* For the transformation of the test result to xUnit format the node module **tap-xunit** is used. `dockerImage` and `dockerWorkspace` define the Docker image used for the transformation and `testPackage` defines the name of the test package used in the xUnit result file.
+* `testPath` defines either the directory which contains the test files (`*.bats`) or a single file. You can find further details in the [Bats-core documentation](https://github.com/bats-core/bats-core#usage)
+* With `failOnError` you can define the behavior, in case tests fail. For example, in case of `outputFormat: 'junit'` you should set it to `false`. Otherwise test results cannot be recorded using the `testsPublishhResults` step afterwards.
+* You can pass environment variables to the test execution by defining parameter `envVars`.
+
+    With `envVars` it is possible to pass either fixed values but also templates using [`commonPipelineEnvironment`](commonPipelineEnvironment.md).
+
+    Example:
+    ```
+    batsExecuteTests script: this, envVars = [
+      FIX_VALUE: 'my fixed value',
+      CONTAINER_NAME: '${commonPipelineEnvironment.configuration.steps.executeBatsTests.dockerContainerName}',
+      IMAGE_NAME: '${return commonPipelineEnvironment.getDockerImageNameAndTag()}'
+    ]
+    ```
+
+    This means within the test one could refer to environment variables by calling e.g.
+    `run docker run --rm -i --name $CONTAINER_NAME --entrypoint /bin/bash $IMAGE_NAME echo "Test"`
+
+* Using parameters `testRepository` the tests can be loaded from another reposirory. In case the tests are not located in the master branch the branch can be specified with `gitBranch`. For protected repositories you can also define the access credentials via `gitSshKeyCredentialsId`. **Note: In case of using a protected repository, `testRepository` should include the ssh link to the repository.**
+* The parameter `repository` defines the version of **bats-core** to be used. By default we use the version from the master branch.
+
+## Step configuration
+The following parameters can also be specified as step/stage/general parameters using the [global configuration](../configuration.md):
+
+* dockerImage
+* dockerWorkspace
+* envVars
+* failOnError
+* gitBranch
+* gitSshKeyCredentialsId
+* outputFormat
+* repository
+* stashContent
+* testPackage
+* testPath
+* testRepository
+
+
+## Example
+
+```groovy
+batsExecuteTests script:this
+testsPublishResults junit: [pattern: '**/Test-*.xml', archive: true]
+```