From dc4e2864e9d4e2bed8701fa4a9ca3e463a5bb4ac Mon Sep 17 00:00:00 2001 From: Pete Fotheringham Date: Sat, 16 Nov 2013 12:34:47 +0000 Subject: Added missing sections in the Introduction Who is `yarn` for? What kinds of testing is `yarn` for? Why `yarn` instead of other tools? Why not cmdtest? --- yarn-doc/index.mdwn | 85 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 73 insertions(+), 12 deletions(-) diff --git a/yarn-doc/index.mdwn b/yarn-doc/index.mdwn index d63dee0..df2fa63 100644 --- a/yarn-doc/index.mdwn +++ b/yarn-doc/index.mdwn @@ -8,8 +8,8 @@ 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. +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 @@ -30,20 +30,22 @@ Document Status * Outline * Mission * this Document Status section - -### What's New - * Writing Scenarios * Test Language Specification * Introduction * Skeleton * What is `yarn`? +### What's New +* Introduction + * Who is `yarn` for? + * What kinds of testing is `yarn` for? + * Why `yarn` instead of other tools? + * Why not cmdtest? + ### What's Next -* Introduction - * Remaining sections * `yarn`'s command line * How to embed `yarn` in Markdown @@ -70,21 +72,81 @@ a backup program works, at least for one simple case. AND an empty backup repository WHEN a backup is made THEN the data can be restored - -(Note the addition of AND: you can have multiple GIVEN, WHEN, and + (Note the addition of AND: you can have multiple GIVEN, WHEN, and THEN statements. The AND keyword makes the text be more readable.) ### Who is `yarn` for? -### Who are the test suites written in `yarn` for? - +Anyone involved in the testing process, from those closest to the process +(the programmers and the engineers implementing the tests) to those +furthest away (architects, customers or their representatives in the +project). + +* Architects: specify the tests by writing scenarios based on requirements, +and the narrative text that goes with them; +* Customers: gain understanding of what they will be getting, of what the +software will do; +* Programmers: create and run tests to verify and debug their code; +* Test engineers: understand what tests they need to implement and +run; +* Project Managers: + * monitor progress of testing activities (tests implemented / run); + * understand current levels of quality (tests passed / failed). + +(In small developments, these roles are often filled by the same person, or +by a very small group of people. In larger development projects, the roles +may be filled by people in different teams, which may be dispersed both +geographically and administratively.) + ### What kinds of testing is `yarn` for? +`yarn` can be used for testing anything that can be driven using the +command line or shell scripts: in practice that means 'anything at all'. +Anything from small, single-engineer developments (add some examples?) +through to very large, multi-team, enterprise-level developments (add some +examples?). + +Testing GUIs can be challenging, but there are tools for the purpose, and +these tools can often be driven from scripts - both for doing things in the +GUI and for checking the outcomes. In these cases, you wouldn't use `yarn` +for implementing the test, but there's no reason not to use it for driving +the tests and reporting the outcomes. + +Because `yarn` is scriptable, it works well as part of a Continuous +Integration process, using tools such as Jenkins. + ### Why `yarn` instead of other tools? +`yarn`'s main strength is that scenarios are written in human readable +language, allowing them to be read, understood and validated by people who +are far removed from the testing process. You don't need to be able to +write (or understand) `IMPLEMENTS` statements to understand a `yarn`. + ### Why not cmdtest? +A single test in `cmdtest` may involve up to eight separate files (the +inputs, outputs, exit code, setup and teardown scripts specific to the +tests, plus the setup and teardown scripts common to all tests). Also, +unless the test author has included narrative comments, it can difficult to +understand the purpose and struture of the test - exactly what is it +testing, and how. These details must be inferred from the implementation of +the test (which is split between the different files). This in turn makes +the tests less accessible to anyone but their creator, and even they may +have problems interpreting the test when returning to it later in the +project lifecycle. + +With `yarn`, the tests are 'self-documenting' - the purpose and structure +of the tests are + +* made explicit in each scenario's narrative text and its steps; +* documented in natural language; +* separated from the implementation. + +So while `cmdtest` could be described as a testing tool for programmers, +`yarn` is intended as a tool for *all* the stakeholders in the testing +process. + Writing Scenarios ----------------- @@ -232,7 +294,6 @@ Semantics: are not run. - Outline ------- -- cgit v1.2.1