% Yarn manual

Yarn
====

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

Mission
-------
This manual will provide all the information needed by Yarn users to enable
them to use Yarn effectively in their development projects.

The information will be

* easy to find
* easy to navigate
* easy to use

The information will include details of

* how to perform certain tasks
* why things are done in particular ways

Document Status
---------------

What's Done
===========

* Outline

What's New
==========

* Mission
* this Document Status section

What's Next
===========

* Test language specification (from README.yarn)
* `yarn`'s command line
*  How to embed `yarn` in Markdown


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)