Helpers and assertions for BATS testing.

• Installation
• Usage
  • Load library
  • Assertions - Command run, String, File, Git
  • Data Provider - Parameterized tests
  • Mocking - Command mocking
  • Step Runner - Sequential test assertions
  • Helpers - Utility functions
• Maintenance

npm install -D bats-helpers@npm:@drevops/bats-helpers

This will also install bats-core.

1. Click Code -> Download ZIP in the GitHub UI.
2. Extract files to a desired location. Usually, next to where bats-core is located.

Create a _loader.bash file next to your BATS tests with content:

# For NPM installation:
export BATS_LIB_PATH="${BATS_TEST_DIRNAME}/../node_modules"

# For source installation:
# export BATS_LIB_PATH="<path/to/extracted/files>"

bats_load_library bats-helpers

Then use load _loader.bash in every BATS test file:

#!/usr/bin/env bats
load _loader.bash

@test "My test" {
 run ls
 assert_success
}

Use these after running a command with run.

Run multiple test cases for a given function (aka "data provider").

Arguments:

1. func_name: The name of the function to be tested.
2. args_per_row: (Optional) The number of arguments in each row of the TEST_CASES array, defaults to 1. Last argument is always the expected value.

Global Variables:

• TEST_CASES: An array containing test cases with their expected values.

Examples:

To run a function add_numbers with TEST_CASES containing three arguments per row, you can call dataprovider_run like so:

# Function to test.
add_numbers() {
  echo "$(($1 + $2))"
}

@test "Test add_numbers" {
  # Numbers: first two are inputs, last is expected output.
  TEST_CASES=(
    1 2 3
    4 5 9
  )
  dataprovider_run "add_numbers" 3
}

This Bats helper library provides command mocking functionality for BATS.

It allows to mock commands and check how they were called.

This is a very powerful feature that allows to test complex scenarios as unit tests.

setup() {
  setup_mock
}

# Example to test the notify.sh script that uses curl to send a notification to external system.
@test "Notify" {
  app_id="9876543210"

  # Mock curl command.
  mock_curl="$(mock_command "curl")"

  # Setup mock responses for curl call with specific arguments in notify.sh.
  mock_set_output "${mock_curl}" "12345678910-1234567890-${app_id}-12345" 1
  mock_set_output "${mock_curl}" "201" 2

  run ./notify.sh
  assert_success

  # Single line mock assertion example.
  assert_equal "-s -X GET https://api.example.com/v2/applications.json" "$(mock_get_call_args "${mock_curl}" 1)"
  # Multi-line mock assertion example.
  assert_equal '-X POST https://api.example.com/v2/applications/9876543210/deployments.json -d {
  "deployment": {
    "description": "example description",
  }
}' "$(mock_get_call_args "${mock_curl}" 2)"
}

When working with mocks, you would have to setup a mock for each command call with the expected argument numbers, return value, possible output and an index of the call. Then, you would run the code to be tested and run assertions for each of the mocked commands. For large scripts maintaining both parts becomes a tedious task.

The Step Runner allows to setup and process a sequence of string and mocked command assertions. It helps to make maintenance of complex tests easier.

Consider this example:

# Declare STEPS as a global variable, as `process_steps` needs to be called
# twice and it does not store the steps internally.
declare -a STEPS=(
  # Mock command with exit status only (status 1 = failure, no output).
  "@drush -y status --field=drupal-version # 1"

  # Mock command with exit status 0 (success) and output "success".
  "@drush -y status --fields=bootstrap # 0 # success"

  # Mock command with exit status 1 (failure) and output "failure".
  "@drush -y status --fields=bootstrap # 1 # failure"

  # Mock command with exit status, output, AND side effect.
  # Side effect creates a file when the mock is called.
  "@drush cache-rebuild # 0 # Cache rebuilt # touch /tmp/cache-cleared"

  # Mock command with wildcard (*) - accepts any arguments.
  "@git * # 0 # Git operation successful"

  # Mock command with escaped hash (\#) in URL - use \# for literal # in arguments.
  "@curl https://example.com/page\#anchor # 0 # Response body"

  # Assert that the output contains the substring "Hello world".
  "Hello world"

  # Assert that the output does NOT contain the substring "Goodbye world".
  # The leading "- " indicates negation.
  "- Goodbye world"
)

# Setup phase: creates mocks and returns references to them.
mocks="$(process_steps "setup")"

# Run the code under test.
run ./my-script.sh

# Assert phase: verifies mocks were called correctly and output assertions pass.
process_steps "assert" "$mocks"

A step can be one of the following types:

• Command - mock a command
• Substring presence - assert output contains string
• Substring absence - assert output does NOT contain string

@<command> [<args>|*] # <mock_status> [ # <mock_output> [ # <mock_side_effect> ]]

Mock a command with the given status, optional output, and optional side effect.

• <command> - the command to mock:
  • Steps for the same command can be mocked multiple times
  • Calls to the same command will use the same mock
• <args> - arguments to match (optional):
  • Match is exact
  • Use * as wildcard to accept any arguments
• <mock_status> - exit status to return (optional):
  • If not specified, 0 exit code will be used
  • Can be omitted if only <mock_output> is needed
• <mock_output> - output to return (optional)
• <mock_side_effect> - Bash code executed when mock is called (optional):
  • Useful for creating files/directories, setting env vars, logging, simulating complex behaviors
  • Executed in the context of the mock, not the test
  • Runs after output is generated but before exit status is returned
  • Chain multiple commands with ; or &&
  • Use ${BATS_TEST_TMPDIR} for temporary files
  • Each invocation of the same command can have different side effects

<substring>

Assert that the output contains the given substring.

- <substring>

Assert that the output does not contain the specified substring. Starts with - (minus followed by a space).

The mocking functionality is based on the bats-mock project. A special thank you to the contributors for their original work.

npm install

npm run lint

npm run test

npm version minor

git push

npm publish

This repository was created using the Scaffold project template