

batsExecuteTests

Description

This step executes tests using the Bash Automated Testing System - bats-core

Prerequisites

You need to have a Bats test file. By default you would put this into directory src/test within your source code repository.

Parameters

name	mandatory	default	possible values
dockerEnvVars	no
dockerImage	no	node:lts-stretch
dockerOptions	no
dockerWorkspace	no	/home/node
envVars	no	[:]
failOnError	no	false
gitBranch	no
gitSshKeyCredentialsId	no	``
outputFormat	no	junit	junit, tap
repository	no	https://github.com/bats-core/bats-core.git
script	yes
stashContent	no	[tests]
testPackage	no	piper-bats
testPath	no	src/test
testRepository	no

• 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.
• envVars - Defines the environment variables to pass to the test execution.
• failOnError - Defines 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.
• gitBranch - Defines the branch where the tests are located, in case the tests are not located in the master branch.
• gitSshKeyCredentialsId - Defines the access credentials for protected repositories. Note: In case of using a protected repository, testRepository should include the ssh link to the repository.
• 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.
• repository - Defines the version of bats-core to be used. By default we use the version from the master branch.
• 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 - Specific stashes that should be considered for the step execution.
• testPackage - For the transformation of the test result to xUnit format the node module tap-xunit is used. This parameter 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.
• testRepository - Allows to load tests from another repository.

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
dockerEnvVars		X
dockerImage		X
dockerOptions		X
dockerWorkspace		X
envVars		X
failOnError		X
gitBranch		X
gitSshKeyCredentialsId		X
outputFormat		X
repository		X
script
stashContent		X
testPackage		X
testPath		X
testRepository		X

Dependencies

The step depends on the following Jenkins plugins

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

Example

batsExecuteTests script:this
testsPublishResults junit: [pattern: '**/Test-*.xml', archive: true]

With `envVars` it is possible to pass either fixed values but also templates using [`commonPipelineEnvironment`](commonPipelineEnvironment.md).

Example:

```yaml
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"`