92 lines
2.9 KiB
Plaintext
92 lines
2.9 KiB
Plaintext
Regression test
|
||
===============
|
||
|
||
:unified-context-diff: https://en.wikipedia.org/wiki/Diff#Unified_format
|
||
|
||
Source structure
|
||
----------------
|
||
|
||
----------------------------------------------
|
||
.
|
||
├── unit
|
||
│ └── …
|
||
└── compose
|
||
└── …
|
||
├── [enabled] → applicability
|
||
├── [rc] → configuration
|
||
├── [in] → start file
|
||
├── cmd → command
|
||
├── [script] → UI automation
|
||
├── [out] → expected end file
|
||
├── [kak_*] → expected expansion values
|
||
└── [error] → expected error
|
||
----------------------------------------------
|
||
|
||
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
|
||
-------
|
||
|
||
+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.
|
||
|
||
+in+ is optional
|
||
and should contain the initial text loaded into the input buffer
|
||
for editing by the +cmd+ key sequence.
|
||
|
||
+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.
|
||
|
||
+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.
|
||
|
||
If the actual +out+ text
|
||
does not match the expected content in the corresponding file,
|
||
the unit test will fail.
|
||
|
||
If there is no +out+
|
||
then the unit test will always succeed.
|
||
|
||
Any +kak_*+ files should match the corresponding expansion
|
||
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.
|