Merge remote-tracking branch 'Screwtapello/test-doc-updates'

test/README.asciidoc

@@ -12,15 +12,14 @@ Source structure
 │   └── …
 └── compose
     └── …
+        ├── [enabled]    → applicability
         ├── [rc]         → configuration
-        ├── cmd          → command
         ├── [in]         → start file
-        ├── [ui-in]      → start UI state in JSON format
+        ├── cmd          → command
-        ├── [out]        → end file
+        ├── [script]     → UI automation
-        ├── [ui-out]     → output UI state in JSON format
+        ├── [out]        → expected end file
-        ├── [selections] → selection contents
+        ├── [kak_*]      → expected expansion values
-        ├── [state]      → selection states
+        └── [error]      → expected error
-        └── [error]      → error bypass
 ----------------------------------------------
 
 Usage
@@ -33,43 +32,60 @@ is printed showing the test’s expected output and the actual output.
 Details
 -------
 
++enabled+ is optional.
+If it exists and is executable,
+it is invoked with no parameters.
+If it exits with a non-zero exit code,
+the test is assumed to be not applicable to the current environment
+(for example, a test for OS-specific integration
+isn't useful on a different OS)
+and will be silently skipped.
+
 +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
++cmd+ is required
-and should contain the json-rpc commands sent to the UI at startup.
+and should contain a key sequence that will edit the input buffer.
++cmd+ is executed after the +rc+ command sequence is sourced.
+
++script+ is optional
+and is a shell-script that will be sourced after +cmd+ is executed.
+The special +ui_in+ function sends a string
+(expected to be a JSON UI message,
+see `doc/json_ui.asciidoc` in the Kakoune source)
+to the running Kakoune instance,
+while the special +ui_out+ function
+checks the next JSON UI messages from Kakoune
+against its arguments,
+and fails the test if any of them are different.
+
+You can also say `ui_out -ignore N` to ignore the next _N_ JSON UI messages,
+where _N_ is a positive integer. 
 
 +out+ is optional
 and should contain the expected text generated by the +cmd+ key sequence.
 
-+ui-out+ is optional
+If the actual +out+ text
-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,
+If there is no +out+
 then the unit test will always succeed.
 
-If there is an +error+ file, which could be empty,
+Any +kak_*+ files should match the corresponding expansion
-then the unit test will always fail.
+after +cmd+ is complete.
+For example, a file named +kak_selection_desc+
+should match the +%val{selection_desc}+ expansion.
+See `:doc expansions` for a list of available expansions.
 
+If there is an +error+ file,
+the test is expected to produce an error.
+If Kakoune exits successfully,
+or if it fails with the wrong error,
+the test is marked as a failure.