SHELLTEST(1)

💖 SHELLTEST(1) 💖

okay bestie, listen up — this is the manual page for shelltest, from shelltestrunner, version 1.2.1. yes the whole thing. no skimming. we're doing this together 🫶

---

✨ NAME ✨

shelltestrunner — test command-line programs or arbitrary shell commands

---

🌸 SYNOPSIS 🌸

literally that's it. that's the whole vibe.

---

🦋 DESCRIPTION 🦋

shelltestrunner tests command-line programs (or like, arbitrary shell commands, it does not care). It reads simple declarative tests that specify a command, some input, and the expected output — and then it can run them:

• in parallel 🔥
• selectively 👑
• with a timeout ⏰
• in color 🌈
• and/or with differences highlighted ✨

it's giving "organized chaos but make it cute". periodt.

---

💅 OPTIONS 💅

• -a, --all — show all the failure output, even if it's huge. no hiding, we look at everything 💀
• -c, --color — show colored output, but only if your terminal supports it. if it doesn't, don't blame us 🎀
• -d, --diff — show failures in diff format. side-by-side-ish drama ✨
• -p, --precise — show failure output precisely. this one is good for whitespace, so if you're the kind of person who cares about a single trailing space, this is your moment 👑
• -x STR, --exclude=STR — exclude test files whose path contains STR. bye felicia 🦋
• --execdir — run tests from within the test file's directory. normally test commands run within your current directory; --execdir makes them run within the directory where they are defined, instead. main character energy, but for directories 🏠
• --extension=EXT — filename suffix of test files. default is .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. so indent responsibly, bestie
• --debug — show debug info, for troubleshooting. when everything is on fire and you need answers 🔍
• --debug-parse — show test file parsing info and stop. just the parsing tea, nothing else ☕
• --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. (fr fr, no 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. iykyk 🌸
• EXITCODE is a numeric exit status (http://en.wikipedia.org/wiki/Exit_status), eg 0 for a successful exit. zero means we ate and left no crumbs 💅
• you can put ! before a /REGEXP/ or EXITCODE to negate the match. plot twist 🙈
• 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

look at that. [OK] [OK] and a full house. we love to see it ✨🔥

---

👑 AUTHORS 👑

Simon Michael.

---

and that's the whole page, bestie!! 🎀 this was shelltestrunner, version 1.2.1, dated March 18 2012 — and that's the cute little sign-off, mwah 💖 🦋 ✨