---
name: "shelltest"
section: "1"
platform: "linux"
package: "shelltestrunner"
version: "1.10-1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/shelltest"
---

# shelltest(1)

test command-line programs or arbitrary shell commands

## NAME

shelltestrunner - test command-line programs or arbitrary shell commands

## SYNOPSIS

shelltest \[*options*\] {*testfiles*\|*testdirs*}

## DESCRIPTION

shelltestrunner tests command-line programs (or arbitrary shell commands). It reads simple declarative tests specifying a command, some input, and the expected output, and can run them run in parallel, selectively, with a timeout, in color, and/or with differences highlighted.

## OPTIONS

- **-a, --all**

  Show all failure output, even if large

- **-c, --color**

  Show colored output if your terminal supports it

- **-d, --diff**

  Show failures in diff format

- **-p, --precise**

  Show failure output precisely (good for whitespace)

- **-x *STR*, --exclude=*STR***

  Exclude test files whose path contains *STR*

- **--execdir**

  Run tests from within the test file's directory. Test commands normally run within your current directory; `--execdir` makes them run within the directory where they are defined, instead.

- **--extension=*EXT***

  Filename suffix of test files (default: *.test*)

- **-w, --with=*EXECUTABLE***

  Replace the first word of (unindented) test commands. This option replaces the first word of all test commands with something else, which can be useful for testing alternate versions of a program. Commands which have been indented by one or more spaces will not be affected by this option.

- **--debug**

  Show debug info, for troubleshooting

- **--debug-parse**

  Show test file parsing info and stop

- **--help-format**

  Display test format help

- **-?, --help**

  Display help message

- **-V, --version**

  Print version information

- **-- *TFOPTIONS***

  Set extra test-framework options like `-j`/`--threads`, `-t`/`--select-tests`, `-o`/`--timeout`, `--hide-successes`. Use `-- --help` for a list. Avoid spaces.

## DEFINING TESTS

Test files, typically named `tests/*.test`, contain one or more tests consisting of:

- •

  a one-line command

- •

  optional standard input (`<<<`), standard output (`>>>`) and/or standard error output (`>>>2`) specifications

- •

  an exit status (`>>>=`) specification

**Test format:**

-

  ```
  # optional comment
  the command to test
  <<<
  zero or more lines of standard input
  >>>
  zero or more lines of expected standard output
  (or /REGEXP/ added to the previous line)
  >>>2
  zero or more lines of expected standard error output
  (or /REGEXP/ added to the previous line)
  >>>= EXITCODE (or /REGEXP/)
  ```

- •

  A `/REGEXP/` pattern may be used instead of explicit data. In this case a match anywhere in the output allows the test to pass. The regular expression syntax is regex-tdfa (http://hackage.haskell.org/package/regex-tdfa)'s.

- •

  `EXITCODE` is a numeric exit status (http://en.wikipedia.org/wiki/Exit\_status), eg `0` for a successful exit.

- •

  You can put `!` before a `/REGEXP/` or `EXITCODE` to negate the match.

- •

  Comment lines beginning with `#` may be used between tests.

## EXAMPLES

Here's `example.test`, a file containing two simple tests:

-

  ```
  # 1. let's test that echo runs. Numbering your tests can be helpful.
  echo
  >>>= 0
  # 2. and now the cat command. On windows, this one should fail.
  cat
  <<<
  foo
  >>>
  foo
  >>>= 0
  ```

Run it with `shelltest`:

-

  ```
  $ shelltest example.test
  :t.test:1: [OK]
  :t.test:2: [OK]
           Test Cases  Total
   Passed  2           2
   Failed  0           0
   Total   2           2
  ```

## AUTHORS

Simon Michael.