Use CircleCI version 2.1 at the top of your .circleci/config.yml file.
1
version: 2.1
Add the orbs
stanza below your version, invoking the orb:
1
2
orbs:
bats: circleci/bats@1.1.0
Use bats
elements in your existing workflows and jobs.
The "run" job provided by the BATS orb will automatically checkout your repository and execute BATS tests within the given path. Optionally, specify the 'junit' formatter and enable timing to generate a JUnit XML file for CircleCI test reporting. Junit test reports will be automatically collected. See the GitHub README for more resources on creating BATS tests.
1
2
3
4
5
6
7
8
9
10
version: '2.1'
orbs:
bats: circleci/bats@1.1.0
workflows:
test-my-app:
jobs:
- bats/run:
formatter: junit
path: ./src/tests
timing: true
Automatically execute BATS tests as a job.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
args | Additional arguments to pass to the BATS command. e.x: `--recursive --trace` | No | '' | string |
exec_environment | Set a custom executor for your BATS testing environment. By default the Docker image 'cimg/base:stable' will be used. BATS will be installed at run time. | No | default | executor |
formatter | Formatter to use for output seen in the step UI. You can also supply a custom formatter. | No | tap | string |
output | Write the report results to a file in this given path. | No | /tmp/bats | string |
path | REQUIRED: Path containing BATS test script(s) | Yes | - | string |
report_formatter | Formatter to use for test report output. By default, "junit" will be selected and parsed by CircleCI. If a non-junit compatible formatter is selected, "save_test_results" should be set to false. | No | junit | string |
save_test_results | Save test results to CircleCI. Note, your formatter must be 'junit' to be parsed by CircleCI. If the report format has been changed, or if you do not wish for the test results to be displayed within CircleCI, then set this to 'false' | No | true | boolean |
setup-steps | Add additional steps prior to executing tests. Additional BATS plugins can be loaded here, or other setup scripts. | No | [] | steps |
timing | Add timing information to the tests. Recommended for CircleCI test reporting. | No | true | boolean |
CircleCI's cimg/base docker image. An optimized Ubuntu 20.04 environment for CI.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
version: 2.1
description: |
Install BATS and automatically execute BATS (Bash Automated Testing System) tests in your pipeline.
display:
home_url: https://github.com/bats-core/bats-core
source_url: https://github.com/CircleCI-Public/BATS-orb
commands:
install:
description: |
Install the BATS-Core BASH Automation Testing System.
steps:
- run:
command: "#!/bin/bash\n\ncheckRequirements() {\n if ! command -v git &> /dev/null\n then\n echo \"git is required to install BATS\"\n exit 1\n fi\n # TODO: revisit if SUDO is needed. Keeping for patch compatability\n if [[ $EUID == 0 ]]; then export SUDO=\"\"; else export SUDO=\"sudo\"; fi\n}\n\ninstallBats() {\n checkRequirements\n cd /tmp || exit 1\n git clone https://github.com/bats-core/bats-core.git\n cd /tmp/bats-core || exit 1\n $SUDO ./install.sh /usr/local\n if ! command -v bats &> /dev/null\n then\n echo \"BATS failed to install\"\n echo \"Please open an issue at: https://github.com/CircleCI-Public/BATS-orb/issues\"\n exit 1\n else\n echo \"BATS installed successfully\"\n fi\n}\n\nsetupBats() {\n if ! command -v bats &> /dev/null \n then\n # BATS is not installed\n installBats\n else\n # BATS is installed\n echo \"BATS is already available\"\n fi\n}\n\nsetupBats\n"
name: Install BATS-Core
executors:
default:
description: CircleCI's cimg/base docker image. An optimized Ubuntu 20.04 environment for CI.
docker:
- image: cimg/base:stable
jobs:
run:
description: |
Automatically execute BATS tests as a job.
executor: <<parameters.exec_environment>>
parameters:
args:
default: ""
description: 'Additional arguments to pass to the BATS command. e.x: `--recursive --trace`'
type: string
exec_environment:
default: default
description: Set a custom executor for your BATS testing environment. By default the Docker image 'cimg/base:stable' will be used. BATS will be installed at run time.
type: executor
formatter:
default: tap
description: Formatter to use for output seen in the step UI. You can also supply a custom formatter.
type: string
output:
default: /tmp/bats
description: Write the report results to a file in this given path.
type: string
path:
description: 'REQUIRED: Path containing BATS test script(s)'
type: string
report_formatter:
default: junit
description: Formatter to use for test report output. By default, "junit" will be selected and parsed by CircleCI. If a non-junit compatible formatter is selected, "save_test_results" should be set to false.
type: string
save_test_results:
default: true
description: Save test results to CircleCI. Note, your formatter must be 'junit' to be parsed by CircleCI. If the report format has been changed, or if you do not wish for the test results to be displayed within CircleCI, then set this to 'false'
type: boolean
setup-steps:
default: []
description: Add additional steps prior to executing tests. Additional BATS plugins can be loaded here, or other setup scripts.
type: steps
timing:
default: true
description: Add timing information to the tests. Recommended for CircleCI test reporting.
type: boolean
steps:
- checkout
- install
- steps: <<parameters.setup-steps>>
- run:
command: "#!/bin/bash\n# This script is ran within the 'run' job, which will check \n# for the existence of BATS prior to running this script.\n\n# Attempt to create the output directory\nmkdir -p \"$ORB_VAL_OUTPUT\" || { echo \"Failed to create output directory\"; exit 1; }\n\nif [ \"$ORB_VAL_TIMING\" = \"1\" ]; then\n set -- \"$@\" --timing\nfi\n\n# Ensure this is the last argument\nif [ -n \"$ORB_VAL_ARGS\" ]; then\n set -- \"$@\" \"$ORB_VAL_ARGS\"\nfi\n\nset -x\n#shellcheck disable=SC2086\nbats --formatter \"$ORB_VAL_FORMATTER\" --report-formatter \"$ORB_VAL_REPORT_FORMATTER\" \"$@\" --output \"$ORB_VAL_OUTPUT\" $ORB_VAL_PATH \nset +x\n"
environment:
ORB_VAL_ARGS: <<parameters.args>>
ORB_VAL_FORMATTER: <<parameters.formatter>>
ORB_VAL_OUTPUT: <<parameters.output>>
ORB_VAL_PATH: <<parameters.path>>
ORB_VAL_REPORT_FORMATTER: <<parameters.report_formatter>>
ORB_VAL_SAVE_TEST_RESULTS: <<parameters.save_test_results>>
ORB_VAL_TIMING: <<parameters.timing>>
name: Execute BATS tests
- when:
condition: <<parameters.save_test_results>>
steps:
- store_test_results:
path: <<parameters.output>>
examples:
run-bats-tests:
description: |
The "run" job provided by the BATS orb will automatically checkout your repository and execute BATS tests within the given path. Optionally, specify the 'junit' formatter and enable timing to generate a JUnit XML file for CircleCI test reporting. Junit test reports will be automatically collected.
See the GitHub README for more resources on creating BATS tests.
usage:
version: "2.1"
orbs:
bats: circleci/bats@1.1.0
workflows:
test-my-app:
jobs:
- bats/run:
formatter: junit
path: ./src/tests
timing: true