YARN(1)

🎀 NAME 🎀

okay so this is yarn, and it lives in the General Commands Manual, section 1, bestie — and it is, and I quote, scenario testing of Unix command line tools. that's the whole vibe. 💖

---

✨ SYNOPSIS ✨

yarn [--allow-missing-steps] [--no-allow-missing-steps] [--cd-datadir]
[--no-cd-datadir] [--config=FILE] [--dump-config] [--dump-setting-names]
[--generate-manpage=TEMPLATE] [-h] [--help] [--help-all]
[--list-config-files] [--version] [--no-default-configs]
[--dump-memory-profile=METHOD] [--env=NAME=VALUE] [--log=FILE]
[--log-keep=N] [--log-level=LEVEL] [--log-max=SIZE] [--log-mode=MODE]
[--memory-dump-interval=SECONDS] [--output=FILE] [-q] [--quiet]
[--no-quiet] [--require-assumptions] [--no-require-assumptions]
[-rSCENARIO] [--run=SCENARIO] [--shell=SHELL] [--shell-arg=ARG]
[-sSHELL-LIBRARY] [--shell-library=SHELL-LIBRARY] [--snapshot]
[--no-snapshot] [--stop-on-first-fail] [--no-stop-on-first-fail]
[--tempdir=DIR] [--timings] [--no-timings] [-v] [--verbose]
[--no-verbose] [-n] [--no-act] [--dry-run] [--pretend] [--no-no-act]
[--no-dry-run] [--no-pretend] [FILE]...

like, yes, it's a lot of flags. we contain multitudes. 🌈

---

🦋 DESCRIPTION 🦋

so yarn is a scenario testing tool. here's the tea: you write a scenario that describes how a user uses your software and what should happen, and you express that scenario using very lightweight syntax so it can be tested automatically. it's giving ✨narrative-driven testing✨.

the scenario has a simple, but strict structure:

GIVEN some setup for the test
WHEN thing that is to be tested happens
THEN the post-conditions must be true

fr fr. GIVEN / WHEN / THEN. the holy trinity. 👑

let's look at a very short test scenario for verifying that a backup program works, at least for one simple case:

SCENARIO backups can be restored
GIVEN some live data in a directory
AND an empty backup repository
WHEN a backup is made
THEN the data case be restored
FINALLY cleanup

notice the addition of AND? you can have multiple GIVEN, WHEN, and THEN statements. the AND keyword just makes the text be more readable. and SCENARIO is also necessary — it gives the title. 💅

FINALLY is for cleanups. the FINALLY steps will be run regardless of whether the scenario succeeds or not. no cap, it's the responsible one in the group chat. 🫶

scenarios are meant to be written in somewhat human readable language. however — and this is the important part — they are not free form text. in addition to the GIVEN/WHEN/THEN structure, the text for each of the steps needs a computer-executable implementation. this is done by using IMPLEMENTS. the backup scenario from above might be implemented as follows:

IMPLEMENTS GIVEN some live data in a directory
rm -rf "$DATADIR/data"
mkdir "$DATADIR/data"
echo foo > "$DATADIR/data/foo"

IMPLEMENTS GIVEN an empty backup repository
rm -rf "$DATADIR/repo"
mkdir "$DATADIR/repo"

IMPLEMENTS WHEN a backup is made
backup-program -r "$DATADIR/repo" "$DATADIR/data"

IMPLEMENTS THEN the data can be restored
mkdir "$DATADIR/restored"
restore-program -r "$DATADIR/repo" "$DATADIR/restored"
diff -rq "$DATADIR/data" "$DATADIR/restored"

IMPLEMENTS FINALLY cleanup
echo nothing to do, actually

each IMPLEMENTS GIVEN (or WHEN, THEN, FINALLY) is followed by a regular expression on the same line, and then a shell script that gets executed to implement any step that matches the regular expression. and the implementation can extract data from the match as well — for example, the regular expression might allow a file size to be specified. 👀

the above example is a bit silly, of course. why go to the effort to obfuscate the various steps? bestie, the answer is: the various steps, implemented using IMPLEMENTS, can be combined in many ways, to test different aspects of the program being tested. it's modular, it's reusable, it ate. 🍓

moreover, by making the step descriptions be human language text matched by regular expressions, most of the test can hopefully be written, and understood, by non-programmers. someone who understands what a program should do could write tests to verify its behaviour. the implementations of the various steps need to be implemented by a programmer, but given a well-designed set of steps, with enough flexibility in their implementation, quite a good test suite can be written. iconic collaboration moment, honestly. 🤝

one last thing: the shell commands in an IMPLEMENTS section are run in the directory in which the user ran yarn. the environment variable SRCDIR is set to the fully qualified path to that directory. 💜

---

💅 OPTIONS 💅

okay sit down, there's a lot, but they're all lil guys. here we go.

• --allow-missing-steps — let scenarios reference steps that do not exist: you'll get a warning about them, but the scenarios are otherwise just ignored. 🫣
• --no-allow-missing-steps — opposite of --allow-missing-steps.
• --cd-datadir — change to DATADIR when running commands.
• --no-cd-datadir — opposite of --cd-datadir.
• --env=NAME=VALUE — add NAME=VALUE to the environment when tests are run.
• --generate-manpage=TEMPLATE — fill in manual page TEMPLATE. (yes, the page you're reading right now probably got made like this. meta. 🪞)
• -h, --help — show this help message and exit.
• --output=FILE — write output to FILE, instead of standard output.
• -q, --quiet — be quiet: avoid progress reporting, only show errors. 🤫
• --no-quiet — opposite of --quiet.
• --require-assumptions — require ASSUMING to always pass.
• --no-require-assumptions — opposite of --require-assumptions.
• -r, --run=SCENARIO — run only SCENARIO. (this option can be repeated, so go wild. 🔁)
• --shell=SHELL — run IMPLEMENTS using SHELL.
• --shell-arg=ARG — use ARG when running shell.
• -s, --shell-library=SHELL-LIBRARY — include a shell library for the IMPLEMENTS sections to use. 📚
• --snapshot — make snapshots of the test working directory after each scenario step; you probably want to use this with --tempdir.
• --no-snapshot — opposite of --snapshot.
• --stop-on-first-fail — stop if any scenario step fails, don't run more scenarios. 🛑
• --no-stop-on-first-fail — opposite of --stop-on-first-fail.
• --tempdir=DIR — use DIR as the temporary directory for tests; it should be empty or not exist.
• --timings — report wall clock time for each scenario and step. ⏱️
• --no-timings — opposite of --timings.
• -v, --verbose — make progress reporting be more verbose ("wall of text"), instead of a one-line status info; this is turned automatically if there is not terminal.
• --no-verbose — opposite of --verbose.
• --version — show program's version number and exit.
• -n, --no-act, --dry-run, --pretend — do not actually run any tests, merely print what would be run. 👻
• --no-no-act, --no-dry-run, --no-pretend — opposite of --no-act.

🗂️ Configuration files and settings 🗂️

• --config=FILE — add FILE to config files.
• --dump-config — write out the entire current configuration.
• --dump-setting-names — write out all names of settings and quit.
• --help-all — show all options.
• --list-config-files — list all possible config files.
• --no-default-configs — clear list of configuration files to read.

📝 Logging 📝

• --log=FILE — write log entries to FILE (default is to not write log files at all); use "syslog" to log to system log, "stderr" to log to the standard error output, or "none" to disable logging.
• --log-keep=N — keep last N logs (10).
• --log-level=LEVEL — log at LEVEL, one of debug, info, warning, error, critical, fatal (default: debug).
• --log-max=SIZE — rotate logs larger than SIZE, zero for never (default: 0).
• --log-mode=MODE — set permissions of new log files to MODE (octal; default 0600).

🏃‍♀️ Peformance 🏃‍♀️

(yes, it's spelled like that, we don't make the rules, we just report them 💀)

• --dump-memory-profile=METHOD — make memory profiling dumps using METHOD, which is one of: none, or simple (no meliae support anymore) (default: simple).
• --memory-dump-interval=SECONDS — make memory profiling dumps at least SECONDS apart.

---

🌸 ENVIRONMENT 🌸

• DATADIR — Fully qualified pathname to a temporary directory, in which the tests can use files. The temporary directory is removed at the end of the test execution, unless the user specifies otherwise with --snapshot. (so like, if you want your lil files to survive, say so. 🥺)
• SRCDIR — Fully qualitifed pathname to the directory in which the user ran yarn. This is useful when the tests want to change the directory.

---

⭐ EXAMPLE ⭐

to run yarn on all the scenarios in your current directory:

yarn *.scenario

all the files will be treated together as if they had been one file. ✨

to add a shell library to be included when running any IMPLEMENTS section:

yarn --shell-library mylib.sh *.scenario

you can repeat --shell-library as many times as necessary. go off. 🔥

---

🧚 SEE ALSO 🧚

cmdtest(1), cliapp(5).

the README.yarn file has more details on the scenario testing language. 📖

---

ok that's the whole page, no skips, no cuts, every flag accounted for. 💖

and that's a wrap, bestie! this was yarn from the General Commands Manual — the footer just signs itself YARN(1) with no date and no version number, which is honestly such a minimal slay of it. go write some scenarios, you're gonna eat. 🎀🦋💅