README.asciidoc (3493B)
1 Regression test 2 =============== 3 4 :unified-context-diff: https://en.wikipedia.org/wiki/Diff#Unified_format 5 6 Source structure 7 ---------------- 8 9 ---------------------------------------------- 10 . 11 ├── unit 12 │ └── … 13 └── compose 14 └── … 15 ├── [enabled] → applicability 16 ├── [env] → environment setup 17 ├── [rc] → configuration 18 ├── [in] → start file 19 ├── cmd → command 20 ├── [script] → UI automation 21 ├── [out] → expected end file 22 ├── [kak_*] → expected expansion values 23 └── [error] → expected error 24 ---------------------------------------------- 25 26 Usage 27 ----- 28 29 To test, just type +run [test]+ in the +test+ directory. 30 It will print each passing test. If a test fails, a {unified-context-diff}[unified context diff] 31 is printed showing the test’s expected output and the actual output. 32 33 Details 34 ------- 35 36 +enabled+ is optional. 37 If it exists and is executable, 38 it is invoked with no parameters. 39 If it exits with a non-zero exit code, 40 the test is assumed to be not applicable to the current environment 41 (for example, a test for OS-specific integration 42 isn't useful on a different OS) 43 and will be silently skipped. 44 45 +env+ is optional. 46 If it exists, it will be sourced before starting Kakoune. 47 48 +rc+ is optional 49 and should contain a sequence of commands, 50 _e.g._, +set-option+, +define-command+, +declare-option+. 51 +rc+ is sourced and evaluated before the +cmd+ key sequence is executed. 52 53 +in+ is optional 54 and should contain the initial text loaded into the input buffer 55 for editing by the +cmd+ key sequence. 56 This file can contain special markers +%(+ and +)+, 57 to denote which parts of the buffer are initially selected. 58 These markers are stripped by the test runner. 59 60 For instance, when the test runner reads an +in+ file containing: 61 62 ----------------- 63 %(foo) bar %(qux) 64 ----------------- 65 66 +foo+ and +qux+ are selected and the file is transformed to: 67 68 ----------- 69 foo bar qux 70 ----------- 71 72 before further processing of the test case. 73 74 75 +cmd+ is required 76 and should contain a key sequence that will edit the input buffer. 77 +cmd+ is executed after the +rc+ command sequence is sourced. 78 79 +script+ is optional 80 and is a shell-script that will be sourced after +cmd+ is executed. 81 The special +ui_in+ function sends a string 82 (expected to be a JSON UI message, 83 see `doc/json_ui.asciidoc` in the Kakoune source) 84 to the running Kakoune instance, 85 while the special +ui_out+ function 86 checks the next JSON UI messages from Kakoune 87 against its arguments, 88 and fails the test if any of them are different. 89 90 You can also say `ui_out -ignore N` to ignore the next _N_ JSON UI messages, 91 where _N_ is a positive integer. 92 93 +out+ is optional 94 and should contain the expected text generated by the +cmd+ key sequence. 95 96 If the actual +out+ text 97 does not match the expected content in the corresponding file, 98 the unit test will fail. 99 100 If there is no +out+ 101 then the unit test will always succeed. 102 103 Any +kak_*+ files should match the corresponding expansion 104 after +cmd+ is complete. 105 For example, a file named +kak_selection_desc+ 106 should match the +%val{selection_desc}+ expansion. 107 See `:doc expansions` for a list of available expansions. 108 109 If there is an +error+ file, 110 the test is expected to produce an error. 111 If Kakoune exits successfully, 112 or if it fails with the wrong error, 113 the test is marked as a failure.