testing/README.md

   1 To run tests run far2l-smoke-run.sh specifying path to far2l which was built by cmake configured with -DTESTING=Yes
   2 Example: `./far2l-smoke-run.sh ../../far2l.build/install/far2l`
   3 Note: if provided far2l built without testing support this will just stuck.. for now.
   4 Actual tests written in JS and located under test directory. They can use following predefined functions to perform actions:
   5
   6 ---------------------------------------------------------
   7
   8 `StartApp(["arg1", "arg2" ...])`
   9
  10 Starts far2l with given arguments, note that some arguments are implicitly inserted - path to far2l as very first argument and --test=
  11 Returns status of started far2l as structure of following fields:
  12  * Width uint32
  13  * Height uint32
  14  * Title string
  15
  16 ---------------------------------------------------------
  17
  18 `AppStatus()`
  19
  20 Returns actual status of far2l as structure described above.
  21
  22 ---------------------------------------------------------
  23
  24 `ReadCellRaw(x, y)`
  25
  26 Reads screen cell at specified coordinates.
  27 Returns structure which has following fields:
  28  * Text string           - string representing contained character
  29  * Attributes uint64     - value from corresponding CHAR_INFO::Attributes
  30
  31 ---------------------------------------------------------
  32
  33 `ReadCell(x, y)`
  34
  35 Reads screen cell at specified coordinates.
  36 Returns more 'decomposed' (comparing to Raw version) structure wich has following fields:
  37  * Text string           - string representing contained character
  38  * BackTC uint32         - 24 bit foreground color if its used
  39  * ForeTC uint32         - 24 bit background color if its used
  40  * Back uint8            - 4 bit base foreground color
  41  * Fore uint8            - 4 bit base background color
  42  * IsBackTC bool         - true if 24 bit foreground color is used
  43  * IsForeTC bool         - true if 24 bit background color is used
  44  * ForeBlue bool         - true if base foreground color has blue component
  45  * ForeGreen bool        - true if base foreground color has green component
  46  * ForeRed bool          - true if base foreground color has red component
  47  * ForeIntense bool      - true if base foreground color has intensified brightness
  48  * BackBlue bool         - true if base background color has blue component
  49  * BackGreen bool        - true if base background color has green component
  50  * BackRed bool          - true if base background color has red component
  51  * BackIntense bool      - true if base background color has intensified brightness
  52  * ReverseVideo bool     - true if foreground/background colors are swapped at rendering
  53  * Underscore bool       - true if character is underscored (not implemented yet)
  54  * Strikeout bool        - true if character is striked out (not implemented yet)
  55
  56 ---------------------------------------------------------
  57
  58 `BoundedLines(left, top, width, height, " \t")`
  59
  60 Returns array of lines bounded by specified rectangle.
  61 Optionally trims edges of each line from trim_chars characters if its not empty.
  62
  63 ---------------------------------------------------------
  64
  65 `SurroundedLines(x, y, "║═│─", " \t")`
  66
  67 Returns array of lines bounded by any of specified in boundary_chars characters.
  68 x, y represends coordinates of any cell inside of required area
  69 Optionally trims edges of each line from trim_chars characters if its not empty.
  70
  71 ---------------------------------------------------------
  72
  73 `CheckCellChar(x, y, "abcdef...")`
  74 `CheckCellCharOrDie(x, y, "abcdef...")`
  75
  76 Checks if cell under specified coordinates contains any of characters contained in specified string.
  77 Returns matched character. But if no character matched then:
  78  * CheckCellChar returns empty string
  79  * CheckCellCharOrDie aborts execution
  80
  81
  82 ---------------------------------------------------------
  83
  84 `ExpectStrings(["string 1", "string 2" ...], x, y, w, h, timeout_ms)`
  85 `ExpectStringsOrDie(["string 1", "string 2" ...], x, y, w, h, timeout_ms)`
  86
  87 Waits given amount of milliseconds for any of given strings will appear in provided rectangular area.
  88 Returns result as structure of following fields, that defines index of found string and its coordinates:
  89  * I uint32
  90  * X uint32
  91  * Y uint32
  92
  93 In case no string found before timeout reached:
  94  * ExpectStrings returns all fields set to 0xffffffff (-1)
  95  * ExpectStringsOrDie aborts execution
  96
  97 ---------------------------------------------------------
  98
  99 `ExpectString("string", x, y, w, h, timeout_ms)`
 100 `ExpectStringOrDie("string", x, y, w, h, timeout_ms)`
 101
 102 Simplified version of ExpectStrings that waits for one string only.
 103 Returns same as ExpectStrings.
 104
 105 ---------------------------------------------------------
 106
 107 `ExpectAppExit(code, timeout_ms)`
 108 `ExpectAppExitOrDie(code, timeout_ms)`
 109
 110 Expects that far2l will exit with specified exit code withing given milliseconds of timeout.
 111 Returns empty string if everything happen as expected, otherwise:
 112  * ExpectAppExit returns string with problem description
 113  * ExpectAppExitOrDie aborts execution
 114
 115 ---------------------------------------------------------
 116
 117 `LogInfo("string")`
 118
 119 Writes given string to test output.
 120
 121 ---------------------------------------------------------
 122
 123 `LogFatal("string")`
 124
 125 Writes given string to test output and aborts tests.
 126
 127 ---------------------------------------------------------
 128
 129 `WriteTTY("string")`
 130
 131 Writes given string to stdin of pseudoterminal where tested far2l is running.
 132
 133 ---------------------------------------------------------
 134
 135 `CtrlC()`
 136
 137 Generates Ctrl+C for tested far2l.
 138
 139 ---------------------------------------------------------
 140
 141 `RunCmd(["prog", "arg1", "arg2" ...])`
 142 `RunCmdOrDie(["prog", "arg1", "arg2" ...])`
 143
 144 Runs given command, returns empty string if start succeeded and command returned zero code, otherwise returns error description or aborts if its RunCmdOrDie.
 145 Note that command is run NOT in pseudoterminal where tested far2l is running.
 146
 147 ---------------------------------------------------------
 148
 149 `Sleep(msec)`
 150
 151 Pauses execution for specified amount of milliseconds
 152
 153 ---------------------------------------------------------
 154
 155 `ToggleShift(pressed bool)`
 156 `ToggleLCtrl(pressed bool)`
 157 `ToggleRCtrl(pressed bool)`
 158 `ToggleLAlt(pressed bool)`
 159 `ToggleRAlt(pressed bool)`
 160
 161 Simulate changing state of specific named control key. Changed state affects all following keypresses.
 162
 163 ---------------------------------------------------------
 164
 165 `TypeBack`
 166 `TypeEnter`
 167 `TypeEscape`
 168 `TypePageUp`
 169 `TypePageDown`
 170 `TypeEnd`
 171 `TypeHome`
 172 `TypeLeft`
 173 `TypeUp`
 174 `TypeRight`
 175 `TypeDown`
 176 `TypeIns`
 177 `TypeDel`
 178
 179 Simulate typing of specific named key
 180
 181 ---------------------------------------------------------
 182
 183 `TypeAdd`
 184 `TypeSub`
 185 `TypeMul`
 186 `TypeDiv`
 187 `TypeSeparator`
 188 `TypeDecimal`
 189
 190 Simulate typing of specific named NumPad key
 191
 192 ---------------------------------------------------------
 193
 194 `TypeDigit(n)`
 195
 196 Simulates typing of specified NumPad digit, where n=0 means 0, n=1 means 1 and so on
 197
 198 ---------------------------------------------------------
 199
 200 `TypeFKey(n)`
 201
 202 Simulates typing of specified F-key, where n=1 means F1, n=2 means F2 and so on
 203
 204 ---------------------------------------------------------
 205
 206 `TypeText("someText to Type")`
 207
 208 Simulates typing of specified text char-by-char according