Skip to main content

Project banner

shell-spec

shell-spec is a testing framework for shell scripts, written entirely in shell script. It brings xUnit/Jest-style testing patterns--automatic test discovery, assertions, mocking, stubbing, and code coverage--to Bash without requiring any external runtime. No Python, no Ruby, no Node.js. Just a shell script that tests other shell scripts.

The Problem It Solves​

Shell scripts are everywhere. They glue CI/CD pipelines together, configure servers, automate deployments, manage dotfiles, and handle a thousand other tasks that nobody thinks about until they break. But testing them? Most people don't. The scripts are "too simple" to test, until they aren't, and the tooling friction is high enough that testing feels like more trouble than the scripts themselves.

Test assertions as railroad switches — pass routes forward, fail routes to a dead-end siding.

shell-spec lowers that friction to nearly zero. The patterns are familiar to anyone who's written a unit test in any language. The barrier to entry is a file ending in _test.sh. That's it.

What It Does​

Test discovery finds files automatically (anything ending in _test.sh) and runs all functions prefixed with test_. No registration, no configuration files, no manifest. Each test runs in a separate subshell, so side effects can't leak between tests--state changes in one test don't affect the next.

Coverage heatmap: functions vs. test suites, bright cells mean well-tested code.

The assertion library covers the standard set: equality checks, pattern matching, exit code verification, file existence, string comparison. Mocking and stubbing let you replace external commands during testing. If your script calls curl or docker or aws, you can mock those calls to return predictable results without hitting real services.

Output uses TAP (Test Anything Protocol v13), which means virtually every CI system and test reporting tool can consume the results natively. Code coverage provides line-by-line tracking (Bash 4.0+), and an HTML reporting dashboard gives you something readable alongside the machine output.

Mock scaffolding around a function under test — inputs from above, expected outputs below.

Technology​

  • Language: Shell script (Bash)
  • Compatibility: bash, zsh, sh
  • Platforms: Ubuntu, macOS, Alpine Linux
  • License: MIT

How It Connects​

shell-spec was born from Circus. When your dotfiles framework has 40+ subcommands, 55+ defaults scripts, and 30 security features, you either test it or you find out it's broken at 2 AM on a fresh machine before a deadline. shell-spec provides the testing infrastructure that makes Circus reliable. It's useful for anyone with non-trivial shell scripts, which is most developers whether they admit it or not.

Where to Find It​