A ShellSpec extension for capturing mock invocations.
This extension enables bash-based ShellSpec tests to capture mock invocations and to verify expectations about these invocations.
Describe 'capture_invocation in a simple mock'
It 'captures an invocation and its arguments'
Mock git
capture_invocation git "$@"
End
When run git commit "-m" "Initial commit"
The number of mocks should equal 1
The first mock should have received arguments git commit "-m" "Initial commit"
End
End
Tip
Passing the initial command ("git" in the above example) as first argument to capture_invocation
is not strictly required, but it helps for distinguishing between multiple mocked functions/commands.
When mocking functions or commands in ShellSpec, mocks might get invoked multiple times with different arguments.
Describe 'capture_invocation in multiple mocks'
It 'captures multiple invocations and their arguments'
# Function mock:
edit_file() {
capture_invocation edit_file "$@"
}
# Command mock:
Mock git
capture_invocation git "$@"
End
some_complex_task() {
# Do stuff
edit_file "$1"
git add "--" "$1"
git commit "-m" "$2"
git push
# Do more stuff
}
When call some_complex_task "README.md" "Initial commit"
The number of mocks should equal 4
The 1st mock should have received arguments edit_file "README.md"
The 2nd mock should have received arguments git add "--" "README.md"
The 3rd mock should have received arguments git commit "-m" "Initial commit"
The 4th mock should have received arguments git push
End
End
Describe 'capture_invocation expectations have aliases'
It 'captures a simple invocation without additional arguments'
When call capture_invocation foo
# aliases
The invocations count should equal 1
The count of invocations should equal 1
The number of invocations should equal 1
The count of mocks should equal 1
The number of mocks should equal 1
# aliases
The first invocation should have received arguments foo
The mock 1 should have received arguments foo
End
End
This extension consists of:
- The
capture_invocation
function to store the command name and the supplied arguments. - A ShellSpec subject
number of mocks
(aliases arenumber of invocations
,count of mocks
, andcount of invocations
) that counts how many mocks have been invoked. - A ShellSpec subject
mock
(alias:invocation
) to select an invocation for verification matching. - A ShellSpec matcher
have received arguments
to match the selected invocation against expected arguments.
The easiest way to run the unit tests is via the dedicated Docker image mgrafl/shellspec-ext-invocation.
docker run --rm -t -v ".:/src" mgrafl/shellspec-ext-invocation
Prefer the dedicated Docker image over local installation. Local installation instructions are only provided for the sake of completeness.
Assuming the code from this repository is located in /path/to/shellspec-ext-invocation/
, run shellspec
directly as:
shellspec --shell=/bin/bash --load-path=/path/to/shellspec-ext-invocation/lib/extension/invocation --require capture_invocation_helper
or:
PATH_TO_SHELLSPEC_EXT_INVOCATION="/path/to/shellspec-ext-invocation/"
PATH="${PATH_TO_SHELLSPEC_EXT_INVOCATION}:${PATH}"
chmod +x "${PATH_TO_SHELLSPEC_EXT_INVOCATION}shellspec-ext-invocation"
# Append ShellSpec CLI parameters as needed
shellspec-ext-invocation
ShellSpec CLI parameters can be appended to the command.
This extension is implemented in Bash and is not POSIX-compliant.
- ShellSpec
- Docker image: mgrafl/shellspec-ext-invocation
- Project for Unit testing GitLab CI/CD job scripts via ShellSpec that uses this extension
- Blog post on Testing GitLab CI/CD job scripts
Contributions to this project are always welcome. Please read the contributing section and raise a Pull Request.
This project is licensed under the MIT license.