> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/bats

Install BATS and automatically execute BATS (Bash Automated Testing System) tests in your pipeline.


## Commands

### install

Install the BATS-Core BASH Automation Testing System.


## Jobs

### run

Automatically execute BATS tests as a job.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `args` | string |  | Additional arguments to pass to the BATS command. e.x: `--recursive --trace` |
| `exec_environment` | executor | default | 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. |
| `formatter` | string | tap | Formatter to use for output seen in the step UI. You can also supply a custom formatter. |
| `output` | string | /tmp/bats | Write the report results to a file in this given path. |
| `path` | string |  | REQUIRED: Path containing BATS test script(s) |
| `report_formatter` | string | junit | 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. |
| `save_test_results` | boolean | true | 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' |
| `setup-steps` | steps |  | Add additional steps prior to executing tests. Additional BATS plugins can be loaded here, or other setup scripts. |
| `timing` | boolean | true | Add timing information to the tests. Recommended for CircleCI test reporting. |

## Executors

### default

CircleCI's cimg/base docker image. An optimized Ubuntu 20.04 environment for CI.

## Examples

### run-bats-tests

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.


```yaml
version: '2.1'
orbs:
  bats: circleci/bats@1.1.0
workflows:
  test-my-app:
    jobs:
      - bats/run:
          formatter: junit
          path: ./src/tests
          timing: true
```