testing/README.md

   1 ## How to run tests
   2 To run tests execute ./far2l-smoke-run.sh with argument - path to far2l which was built by cmake configured with -DTESTING=Yes
   3 Example: `./far2l-smoke-run.sh ../../far2l.build/install/far2l`
   4 Note: if provided far2l is built without testing support this will stuck for a while and fail then.
   5
   6 ## How to write tests
   7 Actual tests written in JS and located under tests directory. They can use predefined functions described below to perform some actions.
   8 Add your test as .js file with numbered name prefix, that number defines execution order as tests executed in alphabetical order.
   9 In general test must:
  10  * optionally do some preparations, like create some files needed for tests if any etc
  11  * start far2l using `StartApp()` function. Its recommended to start far2l with unique profile derived from WorkDir() using -u parameter
  12  * wait for far2l startup by expecting output of left panel title and help page (as on clean profile far2l always shows help on 1st start)
  13  * perform some interactive actions with far2l by sending key presses and checking presence of some expected strings
  14  * validate results if need
  15  * send close command to far2l, e.g. by pressing F10 using TypeFKey(10) and then wait for its shutdown by `ExpectAppExit()`
  16  * test may also start far2l again to do some other actions withing same test-case, buts this needed rarely
  17
  18 Note that by default many functions that perform validations, like `ExpectString()`, `ExpectAppExit()` etc - abort execution in case of unexpected results. This can be changed by BeCalm() function (see below) if need. But typically its behavior you exactly want.
  19
  20 ## Functions list goes below
  21
  22 ---------------------------------------------------------
  23
  24 `BePanic()`
  25 In case of logical problem in subsequent functions - abort tests execution.
  26 This is default mode.
  27
  28 `BeCalm()`
  29 In case of logical problem in subsequent functions - continue execution.
  30 Note that low-level problems, like communication issues or failure to start far2l - still will abort execution.
  31
  32 `Inspect() string`
  33 This function useful in calm mode.
  34 If no problem happened so far - it returns empty string.
  35 Otherwise - it returns error description and empties it for next invokations of `Inspect()`.
  36
  37 ---------------------------------------------------------
  38
  39 `StartApp(["arg1", "arg2" ...])`
  40 Starts far2l with given arguments, note that path to far2l implicitly inserted as very first argument
  41 Returns status of started far2l as structure of following fields:
  42  * Title string      - application title
  43  * Width uint32      - application TUI columns
  44  * Height uint32     - application TUI lines
  45  * CurX uint32       - X cursor position (column index)
  46  * CurY uint32       - Y cursor position (line index)
  47  * CurH uint8        - cursor height from 0 to 100
  48  * CurV bool         - true if cursor is visible
  49
  50 ---------------------------------------------------------
  51
  52 `AppStatus()`
  53 Returns actual status of far2l as structure described above.
  54
  55 ---------------------------------------------------------
  56
  57 `ReadCellRaw(x, y)`
  58 Reads screen cell at specified coordinates.
  59 Returns structure which has following fields:
  60  * Text string           - string representing contained character
  61  * Attributes uint64     - value from corresponding CHAR_INFO::Attributes
  62
  63 ---------------------------------------------------------
  64
  65 `ReadCell(x, y)`
  66 Reads screen cell at specified coordinates.
  67 Returns more 'decomposed' (comparing to Raw version) structure wich has following fields:
  68  * Text string           - string representing contained character
  69  * BackTC uint32         - 24 bit foreground color if its used
  70  * ForeTC uint32         - 24 bit background color if its used
  71  * Back uint8            - 4 bit base foreground color
  72  * Fore uint8            - 4 bit base background color
  73  * IsBackTC bool         - true if 24 bit foreground color is used
  74  * IsForeTC bool         - true if 24 bit background color is used
  75  * ForeBlue bool         - true if base foreground color has blue component
  76  * ForeGreen bool        - true if base foreground color has green component
  77  * ForeRed bool          - true if base foreground color has red component
  78  * ForeIntense bool      - true if base foreground color has intensified brightness
  79  * BackBlue bool         - true if base background color has blue component
  80  * BackGreen bool        - true if base background color has green component
  81  * BackRed bool          - true if base background color has red component
  82  * BackIntense bool      - true if base background color has intensified brightness
  83  * ReverseVideo bool     - true if foreground/background colors are swapped at rendering
  84  * Underscore bool       - true if character is underscored (not implemented yet)
  85  * Strikeout bool        - true if character is striked out (not implemented yet)
  86
  87 ---------------------------------------------------------
  88
  89 `BoundedLines(left, top, width, height, " \t")`
  90 Returns array of lines bounded by specified rectangle.
  91 Optionally trims edges of each line from trim_chars characters if its not empty.
  92
  93 ---------------------------------------------------------
  94
  95 `BoundedLine(left, top, width, " \t")`
  96 Returns single line bounded by specified rectangle on unity height.
  97 Optionally trims edges of line from trim_chars characters if its not empty.
  98
  99 ---------------------------------------------------------
 100
 101 `CheckBoundedLine("expected string", left, top, width, " \t") string`
 102 Check that single line at specified rectangle matches to specified value.
 103 Optionally trims edges of line from trim_chars characters if its not empty.
 104 If string doesnt match - aborts execution unless in calm mode.
 105 Returns actual line.
 106
 107 ---------------------------------------------------------
 108
 109 `SurroundedLines(x, y, "║═│─", " \t")`
 110 Returns array of lines bounded by any of specified in boundary_chars characters.
 111 x, y represends coordinates of any cell inside of required area
 112 Optionally trims edges of each line from trim_chars characters if its not empty.
 113
 114 ---------------------------------------------------------
 115
 116 `CellCharMatches(x, y, "abcdef...") bool`
 117 `CheckCellChar(x, y, "abcdef...") string`
 118 Checks if cell under specified coordinates contains any of characters contained in specified string.
 119 CellCharMatches returns true if cell character matched otherwise it returns false.
 120 CheckCellChar returns cell character. But if no character matched then aborts execution unless in calm mode.
 121
 122 ---------------------------------------------------------
 123
 124 `ExpectString("string", x, y, w, h, timeout_ms)`
 125 `ExpectStrings(["string 1", "string 2" ...], x, y, w, h, timeout_ms)`
 126 Waits given amount of milliseconds for given string/any of given strings will appear in provided rectangular area.
 127 Aborts execution in case no string found before timeout reached unless in calm mode, otherwise:
 128 Returns result as structure of following fields, that defines index of found string and its coordinates or -1 if no string found:
 129  * I uint32
 130  * X uint32
 131  * Y uint32
 132
 133 ---------------------------------------------------------
 134
 135 `ExpectNoString("string", x, y, w, h, timeout_ms)`
 136 `ExpectNoStrings(["string 1", "string 2" ...], x, y, w, h, timeout_ms)`
 137 'Inverted' versions of ExpectString/ExpectStrings that wait until string(s) will NO NOT appear in provided rectangular area
 138
 139 ---------------------------------------------------------
 140
 141 `ExpectAppExit(code, timeout_ms) string`
 142 Expects that far2l will exit with specified exit code within given milliseconds of timeout.
 143 Aborts execution if app not exited during timeout or exited with wrong code (unless in calm mode).
 144
 145 ---------------------------------------------------------
 146
 147 `Log("string")`
 148 Writes given string to test output.
 149
 150 ---------------------------------------------------------
 151
 152 `Panic("string")`
 153 Writes given string to test output and aborts tests.
 154
 155 ---------------------------------------------------------
 156
 157 `TTYWrite("string")`
 158 Writes given string to stdin of pseudoterminal where tested far2l is running.
 159
 160 ---------------------------------------------------------
 161
 162 `TTYCtrlC()`
 163 Generates Ctrl+C for pseudoterminal where tested far2l is running.
 164
 165 ---------------------------------------------------------
 166
 167 `RunCmd(["prog", "arg1", "arg2" ...])`
 168 Runs given command, returns empty string if start succeeded and command returned zero code, otherwise aborts unless in calm mode.
 169 Note that command is run NOT in pseudoterminal where tested far2l is running.
 170
 171 ---------------------------------------------------------
 172
 173 `Sleep(msec)`
 174 Pauses execution for specified amount of milliseconds
 175
 176 ---------------------------------------------------------
 177
 178 `ToggleShift(pressed bool)`
 179 `ToggleLCtrl(pressed bool)`
 180 `ToggleRCtrl(pressed bool)`
 181 `ToggleLAlt(pressed bool)`
 182 `ToggleRAlt(pressed bool)`
 183 Simulate changing state of specific named control key. Changed state affects all following keypresses.
 184
 185 ---------------------------------------------------------
 186
 187 `TypeBack()`
 188 `TypeEnter()`
 189 `TypeEscape()`
 190 `TypePageUp()`
 191 `TypePageDown()`
 192 `TypeEnd()`
 193 `TypeHome()`
 194 `TypeLeft()`
 195 `TypeUp()`
 196 `TypeRight()`
 197 `TypeDown()`
 198 `TypeIns()`
 199 `TypeDel()`
 200 Simulate typing of specific named key
 201
 202 ---------------------------------------------------------
 203
 204 `TypeAdd()`
 205 `TypeSub()`
 206 `TypeMul()`
 207 `TypeDiv()`
 208 `TypeSeparator()`
 209 `TypeDecimal()`
 210 Simulate typing of specific named NumPad key
 211
 212 ---------------------------------------------------------
 213
 214 `TypeDigit(n)`
 215 Simulates typing of specified NumPad digit, where n=0 means 0, n=1 means 1 and so on
 216
 217 ---------------------------------------------------------
 218
 219 `TypeFKey(n)`
 220 Simulates typing of specified F-key, where n=1 means F1, n=2 means F2 and so on
 221
 222 ---------------------------------------------------------
 223
 224 `TypeText("someText to Type")`
 225 Simulates char-by-char typing of specified text.
 226
 227 ---------------------------------------------------------
 228
 229 `WorkDir()`
 230 Returns path to tests working directory - where temporary files and logs are resided
 231
 232 ---------------------------------------------------------
 233
 234 `Exists(path string) bool`
 235 Return true if something exists under specified path
 236
 237 ---------------------------------------------------------
 238
 239 `CountExisting(pathes []string) int`
 240 Return count of existing files from specified pathes list
 241
 242 ---------------------------------------------------------
 243
 244
 245 `Chmod(name string, mode os.FileMode) bool`
 246 `Chown(name string, uid, gid int) bool`
 247 `Chtimes(name string, atime time.Time, mtime time.Time) bool`
 248 `Mkdir(name string, perm os.FileMode) bool`
 249 `MkdirTemp(dir, pattern string) string`
 250 `MkdirAll(path string, perm os.FileMode) bool`
 251 `MkdirsAll(pathes []string, perm os.FileMode)` - custom wrapper around MkdirAll
 252 `Remove(name string) bool`
 253 `RemoveAll(name string) bool`
 254 `Rename(oldpath, newpath string) bool`
 255 `ReadFile(name string) []byte`
 256 `WriteFile(name string, data []byte, perm os.FileMode) bool`
 257 `Truncate(name string, size int64) bool`
 258 `ReadDir(name string) []os.DirEntry`
 259 `Symlink(oldname, newname string) bool`
 260 `Readlink(name string) string`
 261 This functions are almost matched to ones provided by os package so you can find their description right there: https://pkg.go.dev/os
 262 Main difference that in case of failure they will abort execution when in panic mode, or will return false or empty result in case of calm mode.
 263
 264 ---------------------------------------------------------
 265
 266 `Mkfile(path string, mode os.FileMode, min_size uint64, max_size uint64) bool`
 267 `Mkfiles(pathes []string, mode os.FileMode, min_size uint64, max_size uint64) bool`
 268 Creates single file/set of files with given mode of random size within given range filled with random data.
 269 Aborts execution in case of failure unless in calm mode.
 270
 271 ---------------------------------------------------------
 272
 273 `HashPath(path string, hash_data bool, hash_name bool, hash_link bool, hash_mode bool, hash_times bool) string`
 274 `HashPathes(pathes []string, hash_data bool, hash_name bool, hash_link bool, hash_mode bool, hash_times bool) string`
 275
 276 Hashes FS objects at given pathes or single path, returning hash that unique identifies contained objects. If there're directories - they're recursively traversed.
 277 Hash optionally affected by files data, names, mode and times.
 278 Thus this function allows to easily check if there're changes in file(s)
 279 In case of any IO error - error text included into hashing result.