diff options
| author | Lars Wirzenius <liw@liw.fi> | 2013-10-24 20:42:26 +0100 |
|---|---|---|
| committer | Lars Wirzenius <liw@liw.fi> | 2013-10-24 20:42:26 +0100 |
| commit | 0aad99d630ed073c7d071906f81c8aeba8196dc2 (patch) | |
| tree | 4ebf529eaaa5900e2f5bbcf11ff40e3cf2ce39c4 | |
| parent | e16eba47205f91271b77dc71f960427da5c76f72 (diff) | |
| download | cmdtest-0aad99d630ed073c7d071906f81c8aeba8196dc2.tar.gz | |
Start a yarn manual file
| -rw-r--r-- | yarn-doc/index.mdwn | 57 |
1 files changed, 57 insertions, 0 deletions
diff --git a/yarn-doc/index.mdwn b/yarn-doc/index.mdwn new file mode 100644 index 0000000..7deaffb --- /dev/null +++ b/yarn-doc/index.mdwn @@ -0,0 +1,57 @@ +% 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) |