1*testing.txt* For Vim version 8.2. Last change: 2020 Jul 11 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Testing Vim and Vim script *testing-support* 8 9Expression evaluation is explained in |eval.txt|. This file goes into details 10about writing tests in Vim script. This can be used for testing Vim itself 11and for testing plugins. 12 131. Testing Vim |testing| 142. Test functions |test-functions-details| 153. Assert functions |assert-functions-details| 16 17============================================================================== 181. Testing Vim *testing* 19 20Vim can be tested after building it, usually with "make test". 21The tests are located in the directory "src/testdir". 22 23There are several types of tests added over time: 24 test33.in oldest, don't add any of these 25 test_something.in old style tests 26 test_something.vim new style tests 27 28 *new-style-testing* 29New tests should be added as new style tests. These use functions such as 30|assert_equal()| to keep the test commands and the expected result in one 31place. 32 *old-style-testing* 33In some cases an old style test needs to be used. E.g. when testing Vim 34without the |+eval| feature. 35 36Find more information in the file src/testdir/README.txt. 37 38============================================================================== 392. Test functions *test-functions-details* 40 41test_alloc_fail({id}, {countdown}, {repeat}) *test_alloc_fail()* 42 This is for testing: If the memory allocation with {id} is 43 called, then decrement {countdown}, and when it reaches zero 44 let memory allocation fail {repeat} times. When {repeat} is 45 smaller than one it fails one time. 46 47 Can also be used as a |method|: > 48 GetAllocId()->test_alloc_fail() 49 50test_autochdir() *test_autochdir()* 51 Set a flag to enable the effect of 'autochdir' before Vim 52 startup has finished. 53 54 55test_feedinput({string}) *test_feedinput()* 56 Characters in {string} are queued for processing as if they 57 were typed by the user. This uses a low level input buffer. 58 This function works only when with |+unix| or GUI is running. 59 60 Can also be used as a |method|: > 61 GetText()->test_feedinput() 62 63test_garbagecollect_now() *test_garbagecollect_now()* 64 Like garbagecollect(), but executed right away. This must 65 only be called directly to avoid any structure to exist 66 internally, and |v:testing| must have been set before calling 67 any function. 68 69 70test_garbagecollect_soon() *test_garbagecollect_soon()* 71 Set the flag to call the garbagecollector as if in the main 72 loop. Only to be used in tests. 73 74 75test_getvalue({name}) *test_getvalue()* 76 Get the value of an internal variable. These values for 77 {name} are supported: 78 need_fileinfo 79 80 Can also be used as a |method|: > 81 GetName()->test_getvalue() 82 83test_ignore_error({expr}) *test_ignore_error()* 84 Ignore any error containing {expr}. A normal message is given 85 instead. 86 This is only meant to be used in tests, where catching the 87 error with try/catch cannot be used (because it skips over 88 following code). 89 {expr} is used literally, not as a pattern. 90 When the {expr} is the string "RESET" then the list of ignored 91 errors is made empty. 92 93 Can also be used as a |method|: > 94 GetErrorText()->test_ignore_error() 95 96test_null_blob() *test_null_blob()* 97 Return a |Blob| that is null. Only useful for testing. 98 99 100test_null_channel() *test_null_channel()* 101 Return a |Channel| that is null. Only useful for testing. 102 {only available when compiled with the +channel feature} 103 104 105test_null_dict() *test_null_dict()* 106 Return a |Dict| that is null. Only useful for testing. 107 108 109test_null_function() *test_null_function()* 110 Return a |Funcref| that is null. Only useful for testing. 111 112 113test_null_job() *test_null_job()* 114 Return a |Job| that is null. Only useful for testing. 115 {only available when compiled with the +job feature} 116 117 118test_null_list() *test_null_list()* 119 Return a |List| that is null. Only useful for testing. 120 121 122test_null_partial() *test_null_partial()* 123 Return a |Partial| that is null. Only useful for testing. 124 125 126test_null_string() *test_null_string()* 127 Return a |String| that is null. Only useful for testing. 128 129 130test_unknown() *test_unknown()* 131 Return a value with unknown type. Only useful for testing. 132 133test_void() *test_void()* 134 Return a value with void type. Only useful for testing. 135 136 137test_option_not_set({name}) *test_option_not_set()* 138 Reset the flag that indicates option {name} was set. Thus it 139 looks like it still has the default value. Use like this: > 140 set ambiwidth=double 141 call test_option_not_set('ambiwidth') 142< Now the 'ambiwidth' option behaves like it was never changed, 143 even though the value is "double". 144 Only to be used for testing! 145 146 Can also be used as a |method|: > 147 GetOptionName()->test_option_not_set() 148 149 150test_override({name}, {val}) *test_override()* 151 Overrides certain parts of Vim's internal processing to be able 152 to run tests. Only to be used for testing Vim! 153 The override is enabled when {val} is non-zero and removed 154 when {val} is zero. 155 Current supported values for name are: 156 157 name effect when {val} is non-zero ~ 158 redraw disable the redrawing() function 159 redraw_flag ignore the RedrawingDisabled flag 160 char_avail disable the char_avail() function 161 starting reset the "starting" variable, see below 162 nfa_fail makes the NFA regexp engine fail to force a 163 fallback to the old engine 164 no_query_mouse do not query the mouse position for "dec" 165 terminals 166 no_wait_return set the "no_wait_return" flag. Not restored 167 with "ALL". 168 ui_delay time in msec to use in ui_delay(); overrules a 169 wait time of up to 3 seconds for messages 170 term_props reset all terminal properties when the version 171 string is detected 172 ALL clear all overrides ({val} is not used) 173 174 "starting" is to be used when a test should behave like 175 startup was done. Since the tests are run by sourcing a 176 script the "starting" variable is non-zero. This is usually a 177 good thing (tests run faster), but sometimes changes behavior 178 in a way that the test doesn't work properly. 179 When using: > 180 call test_override('starting', 1) 181< The value of "starting" is saved. It is restored by: > 182 call test_override('starting', 0) 183 184< Can also be used as a |method|: > 185 GetOverrideVal()-> test_override('starting') 186 187test_refcount({expr}) *test_refcount()* 188 Return the reference count of {expr}. When {expr} is of a 189 type that does not have a reference count, returns -1. Only 190 to be used for testing. 191 192 Can also be used as a |method|: > 193 GetVarname()->test_refcount() 194 195 196test_scrollbar({which}, {value}, {dragging}) *test_scrollbar()* 197 Pretend using scrollbar {which} to move it to position 198 {value}. {which} can be: 199 left Left scrollbar of the current window 200 right Right scrollbar of the current window 201 hor Horizontal scrollbar 202 203 For the vertical scrollbars {value} can be 1 to the 204 line-count of the buffer. For the horizontal scrollbar the 205 {value} can be between 1 and the maximum line length, assuming 206 'wrap' is not set. 207 208 When {dragging} is non-zero it's like dragging the scrollbar, 209 otherwise it's like clicking in the scrollbar. 210 Only works when the {which} scrollbar actually exists, 211 obviously only when using the GUI. 212 213 Can also be used as a |method|: > 214 GetValue()->test_scrollbar('right', 0) 215 216test_setmouse({row}, {col}) *test_setmouse()* 217 Set the mouse position to be used for the next mouse action. 218 {row} and {col} are one based. 219 For example: > 220 call test_setmouse(4, 20) 221 call feedkeys("\<LeftMouse>", "xt") 222 223test_settime({expr}) *test_settime()* 224 Set the time Vim uses internally. Currently only used for 225 timestamps in the history, as they are used in viminfo, and 226 for undo. 227 Using a value of 1 makes Vim not sleep after a warning or 228 error message. 229 {expr} must evaluate to a number. When the value is zero the 230 normal behavior is restored. 231 232 Can also be used as a |method|: > 233 GetTime()->test_settime() 234 235test_srand_seed([seed]) *test_srand_seed()* 236 When [seed] is given this sets the seed value used by 237 `srand()`. When omitted the test seed is removed. 238 239============================================================================== 2403. Assert functions *assert-functions-details* 241 242 243assert_beeps({cmd}) *assert_beeps()* 244 Run {cmd} and add an error message to |v:errors| if it does 245 NOT produce a beep or visual bell. 246 Also see |assert_fails()| and |assert-return|. 247 248 Can also be used as a |method|: > 249 GetCmd()->assert_beeps() 250< 251 *assert_equal()* 252assert_equal({expected}, {actual} [, {msg}]) 253 When {expected} and {actual} are not equal an error message is 254 added to |v:errors| and 1 is returned. Otherwise zero is 255 returned |assert-return|. 256 There is no automatic conversion, the String "4" is different 257 from the Number 4. And the number 4 is different from the 258 Float 4.0. The value of 'ignorecase' is not used here, case 259 always matters. 260 When {msg} is omitted an error in the form "Expected 261 {expected} but got {actual}" is produced. 262 Example: > 263 assert_equal('foo', 'bar') 264< Will result in a string to be added to |v:errors|: 265 test.vim line 12: Expected 'foo' but got 'bar' ~ 266 267 Can also be used as a |method|, the base is passed as the 268 second argument: > 269 mylist->assert_equal([1, 2, 3]) 270 271< *assert_equalfile()* 272assert_equalfile({fname-one}, {fname-two} [, {msg}]) 273 When the files {fname-one} and {fname-two} do not contain 274 exactly the same text an error message is added to |v:errors|. 275 Also see |assert-return|. 276 When {fname-one} or {fname-two} does not exist the error will 277 mention that. 278 Mainly useful with |terminal-diff|. 279 280 Can also be used as a |method|: > 281 GetLog()->assert_equalfile('expected.log') 282 283assert_exception({error} [, {msg}]) *assert_exception()* 284 When v:exception does not contain the string {error} an error 285 message is added to |v:errors|. Also see |assert-return|. 286 This can be used to assert that a command throws an exception. 287 Using the error number, followed by a colon, avoids problems 288 with translations: > 289 try 290 commandthatfails 291 call assert_false(1, 'command should have failed') 292 catch 293 call assert_exception('E492:') 294 endtry 295 296assert_fails({cmd} [, {error} [, {msg}]]) *assert_fails()* 297 Run {cmd} and add an error message to |v:errors| if it does 298 NOT produce an error or when {error} is not found in the 299 error message. Also see |assert-return|. 300 301 When {error} is a string it must be found literally in the 302 first reported error. Most often this will be the error code, 303 including the colon, e.g. "E123:". > 304 assert_fails('bad cmd', 'E987:') 305< 306 When {error} is a |List| with one or two strings, these are 307 used as patterns. The first pattern is matched against the 308 first reported error: > 309 assert_fails('cmd', ['E987:.*expected bool']) 310< The second pattern, if present, is matched against the last 311 reported error. To only match the last error use an empty 312 string for the first error: > 313 assert_fails('cmd', ['', 'E987:']) 314< 315 Note that beeping is not considered an error, and some failing 316 commands only beep. Use |assert_beeps()| for those. 317 318 Can also be used as a |method|: > 319 GetCmd()->assert_fails('E99:') 320 321assert_false({actual} [, {msg}]) *assert_false()* 322 When {actual} is not false an error message is added to 323 |v:errors|, like with |assert_equal()|. 324 Also see |assert-return|. 325 A value is false when it is zero. When {actual} is not a 326 number the assert fails. 327 When {msg} is omitted an error in the form 328 "Expected False but got {actual}" is produced. 329 330 Can also be used as a |method|: > 331 GetResult()->assert_false() 332 333assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()* 334 This asserts number and |Float| values. When {actual} is lower 335 than {lower} or higher than {upper} an error message is added 336 to |v:errors|. Also see |assert-return|. 337 When {msg} is omitted an error in the form 338 "Expected range {lower} - {upper}, but got {actual}" is 339 produced. 340 341 *assert_match()* 342assert_match({pattern}, {actual} [, {msg}]) 343 When {pattern} does not match {actual} an error message is 344 added to |v:errors|. Also see |assert-return|. 345 346 {pattern} is used as with |=~|: The matching is always done 347 like 'magic' was set and 'cpoptions' is empty, no matter what 348 the actual value of 'magic' or 'cpoptions' is. 349 350 {actual} is used as a string, automatic conversion applies. 351 Use "^" and "$" to match with the start and end of the text. 352 Use both to match the whole text. 353 354 When {msg} is omitted an error in the form 355 "Pattern {pattern} does not match {actual}" is produced. 356 Example: > 357 assert_match('^f.*o$', 'foobar') 358< Will result in a string to be added to |v:errors|: 359 test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~ 360 361 Can also be used as a |method|: > 362 getFile()->assert_match('foo.*') 363< 364 *assert_notequal()* 365assert_notequal({expected}, {actual} [, {msg}]) 366 The opposite of `assert_equal()`: add an error message to 367 |v:errors| when {expected} and {actual} are equal. 368 Also see |assert-return|. 369 370 Can also be used as a |method|: > 371 mylist->assert_notequal([1, 2, 3]) 372 373< *assert_notmatch()* 374assert_notmatch({pattern}, {actual} [, {msg}]) 375 The opposite of `assert_match()`: add an error message to 376 |v:errors| when {pattern} matches {actual}. 377 Also see |assert-return|. 378 379 Can also be used as a |method|: > 380 getFile()->assert_notmatch('bar.*') 381 382 383assert_report({msg}) *assert_report()* 384 Report a test failure directly, using {msg}. 385 Always returns one. 386 387 Can also be used as a |method|: > 388 GetMessage()->assert_report() 389 390 391assert_true({actual} [, {msg}]) *assert_true()* 392 When {actual} is not true an error message is added to 393 |v:errors|, like with |assert_equal()|. 394 Also see |assert-return|. 395 A value is TRUE when it is a non-zero number. When {actual} 396 is not a number the assert fails. 397 When {msg} is omitted an error in the form "Expected True but 398 got {actual}" is produced. 399 400 Can also be used as a |method|: > 401 GetResult()->assert_true() 402< 403 404 vim:tw=78:ts=8:noet:ft=help:norl: 405