TAP-based test runner for the fish shell
Branch: master
Clone or download
Latest commit a2cf715 Feb 18, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
test Add tty tests (#44) Feb 18, 2019
.travis.yml Fishtape 2 (#31) Feb 7, 2019
LICENSE.md Fishtape 2 (#31) Feb 7, 2019
README.md docs: add multiline example Feb 13, 2019
fishtape.fish 2.1.2 Feb 18, 2019



Build Status Releases

Fishtape is a TAP-based test runner for the fish shell.

Your tests run concurrently in their own sub-shells, siloing your test environment. That means you are free to set variables, define functions, and modify the executing environment without hijacking your current session or other tests.

There's no learning curve. If you know how to use the test builtin, you are ready to use Fishtape.


With Fisher (recommended):

fisher add jorgebucaran/fishtape
Not using a package manager?

Copy fishtape.fish to any directory on your function path.

set -q XDG_CONFIG_HOME; or set XDG_CONFIG_HOME ~/.config
curl https://git.io/fishtape.fish --create-dirs -sLo $XDG_CONFIG_HOME/fish/functions/fishtape.fish

To uninstall, remove the file.

System Requirements


A test file is a regular fish file with @test declarations. A test declaration (or test case) consists of a description, followed by one or more operators and their arguments. You can use any operator supported by the test builtin except for the -a and -o conditional operators.

@test "math is real" (math 41 + 1) -eq 42

@test "basename is fish" (
    string split -rm1 / /usr/local/bin/fish
)[-1] = "fish"

@test "test is a builtin" (
    contains -- test (builtin -n)
) $status -eq 0

@test "print a sequence of numbers" (seq 3) = "1 2 3"

Run fishtape with one or more test files to run your tests.

fishtape tests/*.fish
TAP version 13
ok 1 math is real
ok 2 basename is fish
ok 3 test is a builtin
ok 4 print a sequence of numbers

# pass 4
# ok

Test files run in the background in a subshell while individual test cases run sequentially. The output is buffered (delivered in batches) until all jobs are complete. If all the tests pass, fishtape exits with status 0—else, it exits with status 1.

Buffered output means we can't write to stdout or stderr without running into race conditions. To print a TAP message along with a batch of test results, use the @mesg declaration.

@mesg "Brought to you by the friendly interactive shell"

Setup and Teardown

You can define special setup and teardown functions, which run before and after each test case, respectively. Use them to load fixtures, set up your environment, and clean up when you're done.

function setup
    set -g tmp (command mktemp -d /tmp/foo.XXXXX)
    command mkdir -p $tmp

function teardown
    command rm -rf $tmp

@test "directory is empty" -z (
    pushd $tmp
    command ls -1

Special Variables

The following variables are globally available for all test files:

  • $current_dirname the directory where the currently running test file is located
  • $current_filename the name and extension of the currently running test file

Reporting Options

TAP is a text-based protocol for reporting test results. It's easy to parse for machines and still readable for humans. But it isn't the end of it. If you are looking for reporting alternatives see this list of reporters or try tap-mocha-reporter for an all-in-one solution.

Once you've downloaded a TAP-compliant reporter and put it somewhere in your $PATH, pipe fishtape to it.

Redirections and pipes involving blocks are run serially in fish (see fish-shell/#1396). This means we must run fishtape in a subshell to enable streaming support.

fish -c "fishtape test/*.fish" | tap-nyan