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