kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

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.