🚧 Under Construction

Check back soon for the first release of Expect v2

---

---

🧐 expect.sh

expect { BASH testing } toBe "wonderful"

---

Download the latest release or install via:

curl -o- https://expectations.sh/installer.sh | bash

---

expect.sh is a flexible test expectation library

expect { ls } not toContain "$filename"

writeFile "$filename"
expect $? toEqual 0

expect { ls } toContain "$filename"

Basic Syntax

The provided matchers that come with expect.sh use these conventions:

• The first argument is the "actual result"

  expect "Hello, world" toContain "Hello"

• e.g. to get the output of a command:

  expect "$( ls )" toContain "filename"

• If { ... } block is provided, the code is evaluated (without a subshell)

  expect { ls } toContain "filename"

• If {{ ... }} block is provided, the code is evaluated (in a subshell)

  expect {{ ls }} toContain "filename"

---

Authoring Expectations

Every project is different, you should author your own expectations!

If you have a common set of assertions which you perform in your tests:

checkIfConfigIsValid() {
  local configFile="$1"
  [ -f "$configFile" ] || { echo "Not found" >&2; return 1; }
  lint "$configFile"   || { echo "Invalid"   >&2; return 1  }
}

testOne() {
  local config="$( config --new )"
  checkIfConfigFileIsValid "$config"
}

testTwo() {
  local config="$( config --get different )"
  checkIfConfigFileIsValid "$config"
}

# ...

You might want to consider authoring your own expectation(s) for your tests:

testOne() {
  local config="$( config --new )"
  expect "$config" toBeValidConfig
}

For details, see the 🎓 Authoring Expectations Tutorial

---

Provided Expectations

toEqual

(source code)

source "matchers/toEqual.sh"

# Assert content equals provided text ( uses `cat -vet` to include non-visible characters )
expect 5 toEqual 5
expect 5 not toEqual 5

# Runs provided block an asserts content of STDOUT and STDERR combined (does not run in subshell)
expect { echo "Hello" } toEqual "Hello"
expect { echo "Hello" } not toEqual "Hello"

# Runs provided block an asserts content of STDOUT and STDERR combined (runs in subshell)
expect {{ echo "Hello" }} toEqual "Hello"
expect {{ echo "Hello" }} not toEqual "Hello"

toContain

(source code)

source "matchers/toContain.sh"

# Assert content contains all of the provided texts
expect "Hello, world!" toContain "Hello" "world"
expect "Hello, world!" not toContain "Hello" "world"

# Runs provided block an asserts content of STDOUT and STDERR combined (does not run in subshell)
expect { ls } toContain "myFile.txt" "anotherFile.png"
expect { ls } not toEqual "myFile.txt" "anotherFile.png"

# Runs provided block an asserts content of STDOUT and STDERR combined (runs in subshell)
expect {{ ls }} toContain "myFile.txt" "anotherFile.png"
expect {{ ls }} not toEqual "myFile.txt" "anotherFile.png"

toBeEmpty

(source code)

source "matchers/toBeEmpty.sh"

# Assert content is an empty string, e.g. [ -z "" ]
expect "" toBeEmpty
expect " " not toBeEmpty

# Runs provided block an asserts content of STDOUT and STDERR combined (does not run in subshell)
expect { cat somefile } toBeEmpty
expect { cat somefile } not toBeEmpty

# Runs provided block an asserts content of STDOUT and STDERR combined (runs in subshell)
expect {{ cat somefile }} toBeEmpty
expect {{ cat somefile }} not toBeEmpty

toMatch

(source code)

source "matchers/toMatch.sh"

# Assert content matches a provided BASH regex pattern, e.g. [[ "$x" =~ $pattern ]]
expect "Hello 1.2.3" toMatch '[0-9]\.[0-9]\.[0-9]$'
expect "Hello 1.2.3" not toMatch '[0-9]\.[0-9]\.[0-9]$'

# Runs provided block an asserts content of STDOUT and STDERR combined (does not run in subshell)
expect { cat version.txt } toMatch '[0-9]\.[0-9]\.[0-9]$'
expect { cat version.txt } not toMatch '[0-9]\.[0-9]\.[0-9]$'

# Runs provided block an asserts content of STDOUT and STDERR combined (runs in subshell)
expect {{ cat version.txt }} toMatch '[0-9]\.[0-9]\.[0-9]$'
expect {{ cat version.txt }} not toMatch '[0-9]\.[0-9]\.[0-9]$'

toOutput

(source code)

source "matchers/toOutput.sh"

# Requires { block } syntax

# Assert content is present in STDOUT or STDERR (combined)
expect { ls } toOutput "should contain this" "and also this"
expect { ls } not toOutput "should not contain this" "or this"

# Assert content is present in STDOUT (supports either toSTDOUT or toStdout)
expect { ls } toOutput toSTDOUT "should contain this" "and also this"
expect { ls } not toOutput toSTDOUT "should not contain this" "or this"

# Assert content is present in STDERR (supports either toSTDERR or toStderr)
expect { ls } toOutput toSTDERR "should contain this" "and also this"
expect { ls } not toOutput toSTDERR "should not contain this" "or this"

# Like other matchers, using {{ two braces }} runs the command in a subshell
expect {{ ls }} toOutput "should contain this" "and also this"
expect {{ ls }} not toOutput "should not contain this" "or this"

toFail

(source code)

source "matchers/toFail.sh"

# Requires { block } syntax

# Assert that the provided command fails
expect { grep pattern file.txt } toFail

# Assert that the provided command does not fail
expect { grep pattern file.txt } not toFail

# Assert that the provided command with STDERR containing the provided text
expect { grep pattern file.txt } toFail "with this in STDERR" "and this"

# Assert that the provided command does not fail and the STDERR does not contain the provided text
expect { grep pattern file.txt } not toFail "and STDERR shouldn't contain this" "or this"

# Like other matchers, using {{ two braces }} runs the command in a subshell
expect {{ grep pattern file.txt }} toFail
expect {{ grep pattern file.txt }} not toFail
expect {{ grep pattern file.txt }} toFail "with this in STDERR" "and this"
expect {{ grep pattern file.txt }} not toFail "and STDERR shouldn't contain this" "or this"

---

Related Projects

• ☑️ assert.sh for assert [ 1 -eq 42 ] style assertions
• 🚀 run.sh for run ls && echo "$STDOUT" helper function
• 🔬 spec.sh for a lovely shell specification testing framework

---

Test Framework Compatibility

• Bats
• shUnit2
• roundup