% Yarn manual

Yarn
====

FIXME: This will become a manual for writing test suites in yarn. It
is currently not yet written.

Outline
-------

* Introduction
  - what is yarn?
  - who is yarn for?
  - who are the test suites written in yarn for?
  - what kinds of testing is yarn for?
  - why yarn instead of other tools?
    - why not cmdtest?
  - NOT installation instructions
* Examples
  - a test suite for "hello world"
    - make the files available so people can try things for themselves
  - a few simple scenarios
* The yarn testing language
  - Markdown with blockquotes for the executable code
  - SCENARIO + the step-wise keywords
  - IMPLEMENTS sections
* Running yarn
  - command line syntax
  - examples of various ways to run yarn in different scenarios:
    - how to run just one scenario
    - how to run yarn under cron or jenkins
  - formatting a test suite in yarn with pandoc
* Best practices
  - this chapter will describe best practices for writing test suites
    with yarn
  - how to structure the files: what to put in each *.yarn file, e.g.,
    where should IMPLEMENTS go
  - how to write test suites that make it easy to debug things when a
    test case fails
  - good phrasing guidelines for yarn scenario names and step names
  - what things are good to keep visible to the reader, what are
    better hidden inside impementations of steps, with examples from
    real projects using yarn
  - guidelines for well-defined steps that are easy to understand and
    easy to implement
  - anti-patterns: things that are good to avoid
  - make tests fast
  - make test code be obviously correct; make test code be the best
    code
  - when is it OK to skip scenarios?
* Case studies
  - this chapter will discuss ways to use yarn in things that are not
    just "run this program and examine the output"
  - start a daemon in the background, kill it at the end of a scenario
  - how to use a really heavy-weight thing in test suites (e.g., start
    a database server for all scenarios to share)