From 56bc1750cc70135fab0c35c83531ed42f7e9fc8b Mon Sep 17 00:00:00 2001
From: Steven Chan <stevenyvr987@users.noreply.github.com>
Date: Thu, 16 Feb 2017 12:32:01 -0800
Subject: [PATCH 1/2] Include more details in test/README.asciidoc

Define the role and content of each test file.
---
 test/README.asciidoc | 50 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/test/README.asciidoc b/test/README.asciidoc
index 4fc87d64..7d15f3bc 100644
--- a/test/README.asciidoc
+++ b/test/README.asciidoc
@@ -12,12 +12,15 @@ Source structure
 │   └── …
 └── compose
     └── …
+        ├── [rc]         → configuration
         ├── cmd          → command
         ├── [in]         → start file
+        ├── [ui-in]      → start UI state in JSON format
         ├── [out]        → end file
+        ├── [ui-out]     → output UI state in JSON format
         ├── [selections] → selection contents
         ├── [state]      → selection states
-        └── [rc]         → configuration
+        └── [error]      → error bypass
 ----------------------------------------------
 
 Usage
@@ -26,3 +29,48 @@ Usage
 To test, just type +run [test]+ in the +test+ directory.
 It will print each passing test.  If a test fails, a {unified-context-diff}[unified context diff]
 is printed showing the test’s expected output and the actual output.
+
+Details
+-------
+
++rc+ is optional
+and should contain a sequence of commands,
+_e.g._, +set-option+, +define-command+, +declare-option+.
++rc+ is sourced and evaluated before the +cmd+ key sequence is executed.
+
++cmd+ is required
+and should contain a key sequence that will edit the input buffer.
++cmd+ is executed after the +rc+ command sequence is sourced.
+
++in+ is optional
+and should contain the initial text loaded into the input buffer
+for editing by the +cmd+ key sequence.
+
++ui-in+ is optional
+and should contain the initial json-rpc commands loaded from the UI
+at startup to set a specific UI state.
+
++out+ is optional
+and should contain the expected text generated by the +cmd+ key sequence.
+
++ui-out+ is optional
+and should contain the expected UI JSON output.
+
++selections+ is optional
+and should contain the expected value of +$kak_selections+
+(_i.e._, content of the selection separated by colons).
+
++state+ is optional
+and should contain the expected value of +$kak_selections_desc+
+(_i.e._, range of the selections separated by colons).
+
+If the actual +output+ text, +selections+, +state+, or +ui-out+
+does not match the expected content in the corresponding file,
+the unit test will fail.
+
+If there is no +output+, +selections+, +state+, or +ui-out+ file,
+then the unit test will always succeed.
+
+If there is an +error+ file, which could be empty,
+then the unit test will always fail.
+

From fe0c357b6633362fa4e55ddaa305ea3d19c76312 Mon Sep 17 00:00:00 2001
From: Steven Chan <stevenyvr987@users.noreply.github.com>
Date: Thu, 16 Feb 2017 12:32:01 -0800
Subject: [PATCH 2/2] Include more details in test/README.asciidoc

Define the role and content of each test file.
Further changes to test/README.asciidoc
---
 test/README.asciidoc | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/test/README.asciidoc b/test/README.asciidoc
index 7d15f3bc..cd42f4ae 100644
--- a/test/README.asciidoc
+++ b/test/README.asciidoc
@@ -47,8 +47,7 @@ and should contain the initial text loaded into the input buffer
 for editing by the +cmd+ key sequence.
 
 +ui-in+ is optional
-and should contain the initial json-rpc commands loaded from the UI
-at startup to set a specific UI state.
+and should contain the json-rpc commands sent by the UI at startup.
 
 +out+ is optional
 and should contain the expected text generated by the +cmd+ key sequence.