Merge remote-tracking branch 'stevenyvr987/update-test/README.asciidoc'

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,47 @@ 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 json-rpc commands sent by the UI at startup.
+
++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.
+