diff options
Diffstat (limited to 'yarn-doc/index.mdwn')
-rw-r--r-- | yarn-doc/index.mdwn | 112 |
1 files changed, 109 insertions, 3 deletions
diff --git a/yarn-doc/index.mdwn b/yarn-doc/index.mdwn index df2fa63..e535633 100644 --- a/yarn-doc/index.mdwn +++ b/yarn-doc/index.mdwn @@ -42,11 +42,12 @@ Document Status * What kinds of testing is `yarn` for? * Why `yarn` instead of other tools? * Why not cmdtest? - +* Running yarn + * Command line syntax and examples + * Using `pandoc` to format a test suite ### What's Next -* `yarn`'s command line * How to embed `yarn` in Markdown Introduction @@ -284,7 +285,7 @@ Semantics: * The name of each scenario (given with SCENARIO) must be unique. * All names of scenarios and steps will be normalised before use - (whitespace collapse, leading and trailing whitespace + (whitespace collapse, leading and trailing whitespace) * Every ASSUMING, GIVEN, WHEN, THEN, FINALLY must be matched by exactly one IMPLEMENTS. The test runner checks this before running any code. @@ -293,6 +294,111 @@ Semantics: * If ASSUMING fails, that scenario is skipped, and any FINALLY steps are not run. +Running yarn +------------ +### Command line syntax + +<pre> +Usage: yarn [options] + +Options: + --version show program's version number and exit + -h, --help show this help message and exit + --output=FILE write output to FILE, instead of standard output + -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 + -q, --quiet be quiet, avoid progress reporting, only show errors + --no-quiet + -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 + -s SHELL-LIBRARY, --shell-library=SHELL-LIBRARY + include a shell library for the IMPLEMENTS sections to + use + -r TEST, --run=TEST run only TEST (this option can be repeated) + --tempdir=DIR use DIR as the temporary directory for tests; it + should be empty or not exist + --env=NAME=VALUE add NAME=VALUE to the environment when tests are run + --snapshot make snapshots of test working directory after each + scenario step; you probably want to use this with + --tempdir + --no-snapshot + --timings report wall clock time for each scenario and step + --no-timings + + Configuration files and settings: + --dump-config write out the entire current configuration + --no-default-configs + clear list of configuration files to read + --config=FILE add FILE to config files + --help-all show all options + + Logging: + --log=FILE write log entries to FILE (default is to not write log + files at all); use "syslog" to log to system log, or + "none" to disable logging + --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-keep=N keep last N logs (10) + --log-mode=MODE set permissions of new log files to MODE (octal; + default 0600) + + Peformance: + --dump-memory-profile=METHOD + make memory profiling dumps using METHOD, which is one + of: none, simple, meliae, or heapy (default: simple) + --memory-dump-interval=SECONDS + make memory profiling dumps at least SECONDS apart +</pre> + +### Examples + +This command will run all the tests in the file `tests.yarn`: + + $ yarn test.yarn + +This command will run only the test named "Simple test" in the file +`tests.yarn`: + + $ yarn test.yarn -r "Simple test" + +This command will run all the tests in all the `.yarn` files in the `tests` +sub-directory, using the `IMPLEMENTS` in the `shell-lib.sh` shell library: + + $ yarn --shell-library shell-lib.sh tests/*.yarn + +To Do: how to run yarn under cron or jenkins + +### Using `pandoc` + +Because `yarn` test suites are written in Markdown, you can use the +[`pandoc`][pandoc] document converter to format them for printing or +reading. + +These commands will create html and pdf documents containing the test +scenarios and narrative text from the all the .yarn files in the `tests` +sub-directory: + + $ pandoc -o test-suite.html tests/*.yarn + $ pandoc -o test-suite.pdf tests/*.yarn + +See also +-------- + +Wikipedia has an article on [Behaviour Driven Development][BDD], +which can provide background and further explanation to what this +tools tries to do. + +[BDD]: https://en.wikipedia.org/wiki/Behavior-driven_development +[Markdown]: http://daringfireball.net/projects/markdown/ +[Pandoc]: http://johnmacfarlane.net/pandoc/ + + Outline ------- |