BDD based testing framework for POSIX compatible shell scripts.

Table of Contents

• Introduction
  • Specfile syntax
  • Features
  • Supported shells
  • Dependency
• Tutorial
  • Installation
  • Getting started
  • Samples
• Basic structure
  • Nestable groups and scope
  • Temporarily skip block
  • Hooks
  • Mock and Stub
• Example
  • Evaluation
  • Expectation
    • The statement
    • It statement
    • Language chains
  • Subject
  • Modifier
  • Matcher
  • Helper
    • Path alias
  • Skip and Pending
• shellspec command
  • Configure default options
  • Task runner
  • Envronment
  • Special files / directories with in spec directory
    • spec/spec_helper.sh
    • spec/support/
    • spec/banner
• Version history

Describe 'sample' # Example group block
  Describe 'bc command'
    add() { echo "$1 + $2" | bc; }

    Example 'perform addition' # Example block
      When call add 2 3 # Evaluation
      The output should eq 5  # Expectation
    End
  End

  Describe 'implemented by shell function'
    . ./mylib.sh # add() function defined

    Example 'perform addition'
      When call add 2 3
      The output should eq 5
    End
  End
End

• Support POSIX compatible shell (dash, bash, ksh, busybox, etc...)
• BDD style syntax
• The specfile is a valid shell script language syntax
• Pure shell script implementation
• Minimum Dependencies (Use only a few POSIX compliant command)
• Nestable groups with scope like lexical scope
• Before / After hooks
• Skip / Pending
• Mocking and stubbing (temporary function override)
• Built-in simple task runner
• Modern reporting (colorize, failure line number)
• Extensible architecture (custom matcher, custom formatter, etc...)
• shellspec is tested by shellspec

dash, bash, ksh, mksh, pdksh, zsh, posh, yash, busybox (ash)

Tested Platforms:

• Linux (ubuntu, debian, alpine)
• Windows 10 (WSL, cygwin, Git Bash)
• macOS Mojave
• Solaris 11

Confirmed version:

• ash 0.3.8 (debian 3.0)
• dash 0.5.3 (debian 4.0)
• busybox ash 1.1.3 (debian 4.0)
• bash 2.03 (debian 2.2)
• zsh 3.1.9 (debian 2.2)
• pdksh 5.2.14 (debian 2.2)
• mksh 28 (debian 4.0)
• ksh93 93q (debian 3.1)
• ksh88 0.5.11 (solaris 11)
• posh 0.3.14 (debian 3.1)
• yash 2.30 (debian 7)

shellspec is implemented in a pure shell script, so what you need is the target shell and few POSIX compliant command.

Currently used external command:

date, mkdir, rm, mv (recommends: printf, ps, readlink, time)

Just get the shellspec and create a symlink in your PATH!

For example

$ cd /SOME/WHERE/TO/INSTALL
$ wget https://github.com/ko1nksm/shellspec/archive/{VERSION}.tar.gz
$ tar xzvf shellspec-{VERSION}.tar.gz

$ ln -s /SOME/WHERE/TO/INSTALL/shellspec-{VERSION}/shellspec /EXECUTABLE/PATH/
# (e.g. /EXECUTABLE/PATH/ = /usr/local/bin/, $HOME/bin/)

or create shellspec instead of create a symlink (If you does not have readlink)

$ cat<<'HERE'>/EXECUTABLE/PATH/shellspec
#!/bin/sh
exec /SOME/WHERE/TO/INSTALL/shellspec-{VERSION}/shellspec "$@"
HERE
$ chmod +x /EXECUTABLE/PATH/shellspec

Just create your project directory and run shellspec --init to setup to your project

# Create your project directory
$ mkdir <your-project-directory>
$ cd <your-project-directory>

# Initialize
$ shellspec --init
  create .shellspec
  create spec/spec_helper.sh

# Write your first specfile (of course you can use your favorite editor)
$ cat<<'HERE'>spec/hello_spec.sh
Describe 'hello.sh'
  . lib/hello.sh
  Example 'hello'
    When call hello shellspec
    The output should equal 'Hello shellspec!'
  End
End
HERE

# Create lib/hello.sh
$ mkdir lib
$ touch lib/hello.sh

# It goes fail because hello function not implemented.
$ shellspec

# Write hello function (of course you can use your favorite editor)
$ cat<<'HERE'>lib/hello.sh
hello() {
  echo "Hello ${1}!"
}
HERE

# It goes success!
$ shellspec

See sample directory, and run shellspec sample with in shellspec directory.

You can write structured Example by below DSL.

The specfile is a valid as shell script syntax, but performs translation process to implements the scope and line number etc.

Each example group block and example block are translate to sub shell. Therefore, changes inside the block do not affect the outside of the block.

In other words, it can realize local variables and local functions in the specfile. This is very useful for describing a structured Spec.

If you are interested in how to translate, use the --translate option.

You want to temporary skip Describe, Context, Example, Specify block, add prefixing x and modify to xDescribe, xContext, xExample, xSpecify.

You can define hooks called before/after running example.

Currentry, shellspec is not provide special function for mocking/stubbing. But redefine shell function can override existing shell function or external command. It can use as substitute as mocking/stubbing.

Remember to Describe, Context, Example, Specify block running in subshell. When going out of the block will restore overridden function.

An example block is a place to describe the specification. It constitute by maximum of one Evaluation and multiple Expectations.

Defines the action for verification. Maximum of one Evaluation for each Example.

When call             echo hello world
     <- evaluation type ->

Normally you will use call. invoke is similar to call but run in subshell. invoke usefull for override function in evaluation only and trap exit.

Defines the verifications.

This is the most basic Expectation. Evaluate the subject is the expected value.

The output        should equal         4
    <- subject ->        <- matcher -> <- expected value ->

modifier is modify subject before expectation.

The line 2  of     output        should equal 4
    <- modofier -> <- subject ->

modifier is chainable.

The word 1 of line 2  of    output        should equal 4
    <- multiple modifier -> <- subject ->

If modifier's first argument is number, you can use names for ordinal numbers.

The second line of output        should equal 4
    <- modofier -> <- subject ->

It statement is syntax sugar for The statement. Use to avoid top-heavy sentences.

Note: Unlike rspec, It is not alias of Example.

The following two sentences are the same meaning.

The word 1 of line 2 of output should equal 4

It should equal 4 the word 1 of line 2 of output

shellspec supports language chains like chai.js.

Language chains only improve readability. It does not any effect the execution of Expectation.

• a
• an
• as
• the

The following two sentences are the same meaning.

The first word of second line of output should valid number

The first word of the second line of output should valid as a number

exit status (the subject expect exit status)

stat (the subject expect file)

valid

variable (the subject expect variable)

string

other

You can define short path name for long path for readability.

for example

Example 'not use path alias'
  The file "/etc/hosts" should be exist
End

Example 'use path alias'
  File hosts="/etc/hosts"
  The file hosts should be exist
End

You can skip or pending current execution block.

To change default options for shellspec command, create options file. Read files in the order the bellows and overrides options.

1. $XDG_CONFIG_HOME/shellspec/options
2. $HOME/.shellspec
3. ./.shellspec
4. ./.shellspec-local (Do not manage by VCS)

You can run the task with --task option.

The spec_helper.sh loaded by --require spec_helper option.

This file use to preparation for running examples, define custom matchers, and etc.

This directory use to create file for custom matchers, tasks and etc.

If exists spec/banner file, shows banner when shellspec command executed. To disable shows banner with --no-banner option.

0.7.0

• Added lines modifier.

0.6.0

• Added match matcher.

0.5.0

• Initial public release.