From 5a31353fb0e0f0bc3e594b2dd4dfa549d7cc841c Mon Sep 17 00:00:00 2001
From: Clinton Gormley <clint@traveljury.com>
Date: Wed, 18 Sep 2013 15:54:58 +0200
Subject: [PATCH] Updated the test README to allow multiple test sections and
 an initial setup section

---
 rest-api-spec/test/README.asciidoc | 42 ++++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 5 deletions(-)

diff --git a/rest-api-spec/test/README.asciidoc b/rest-api-spec/test/README.asciidoc
index 3d1d8e322c9..439187959c0 100644
--- a/rest-api-spec/test/README.asciidoc
+++ b/rest-api-spec/test/README.asciidoc
@@ -1,9 +1,40 @@
 Test Suite:
 ===========
 
-The tests in each YAML file should be run in order as a single set of dependent tests.
-Before each file, the test cluster should be "reset" (eg deleting indices etc),
-the `response` var and the `stash` should be cleared (see below).
+A YAML test file consists of:
+* an optional `setup` section, followed by
+* one or more test sections
+
+For instance:
+
+    setup:
+      - do: ....
+      - do: ....
+
+    ---
+    "First test":
+      - do: ...
+      - match: ...
+
+    ---
+    "Second test":
+      - do: ...
+      - match: ...
+
+
+A `setup` section contains a list of commands to run before each test
+section in order to setup the same environment for each test section.
+
+A test section represents an independent test, containing multiple `do`
+statements and assertions. The contents of a test section must be run in
+order, but individual test sections may be run in any order, as follows:
+
+1. run `setup` (if any)
+2. reset the `response` var and the `stash` (see below)
+2. run test contents
+3. run teardown
+
+The `teardown` should delete all indices and all templates.
 
 Dot notation:
 -------------
@@ -26,8 +57,9 @@ in the `indices.get_settings` API.
 
 Skipping tests:
 ---------------
-If any tests should be skipped on particular versions of Elasticsearch, there
-should be an entry called `skip` containing the range of versions to be
+If a test section should only be run on certain versions of Elasticsearch,
+then the first entry in the section (after the title) should be called
+`skip`, and should contain the range of versions to be
 skipped, and the reason why the tests are skipped.  For instance:
 
 ....