kakoune/test/README.asciidoc

Regression test
===============

:unified-context-diff: https://en.wikipedia.org/wiki/Diff#Unified_format

Source structure
----------------

----------------------------------------------
.
├── unit
│   └── …
└── 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
        └── [error]      → error bypass
----------------------------------------------

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 to 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.