1*testing.txt* For Vim version 8.2. Last change: 2020 Apr 10 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 ALL clear all overrides ({val} is not used) 169 170 "starting" is to be used when a test should behave like 171 startup was done. Since the tests are run by sourcing a 172 script the "starting" variable is non-zero. This is usually a 173 good thing (tests run faster), but sometimes changes behavior 174 in a way that the test doesn't work properly. 175 When using: > 176 call test_override('starting', 1) 177< The value of "starting" is saved. It is restored by: > 178 call test_override('starting', 0) 179 180< Can also be used as a |method|: > 181 GetOverrideVal()-> test_override('starting') 182 183test_refcount({expr}) *test_refcount()* 184 Return the reference count of {expr}. When {expr} is of a 185 type that does not have a reference count, returns -1. Only 186 to be used for testing. 187 188 Can also be used as a |method|: > 189 GetVarname()->test_refcount() 190 191 192test_scrollbar({which}, {value}, {dragging}) *test_scrollbar()* 193 Pretend using scrollbar {which} to move it to position 194 {value}. {which} can be: 195 left Left scrollbar of the current window 196 right Right scrollbar of the current window 197 hor Horizontal scrollbar 198 199 For the vertical scrollbars {value} can be 1 to the 200 line-count of the buffer. For the horizontal scrollbar the 201 {value} can be between 1 and the maximum line length, assuming 202 'wrap' is not set. 203 204 When {dragging} is non-zero it's like dragging the scrollbar, 205 otherwise it's like clicking in the scrollbar. 206 Only works when the {which} scrollbar actually exists, 207 obviously only when using the GUI. 208 209 Can also be used as a |method|: > 210 GetValue()->test_scrollbar('right', 0) 211 212test_setmouse({row}, {col}) *test_setmouse()* 213 Set the mouse position to be used for the next mouse action. 214 {row} and {col} are one based. 215 For example: > 216 call test_setmouse(4, 20) 217 call feedkeys("\<LeftMouse>", "xt") 218 219test_settime({expr}) *test_settime()* 220 Set the time Vim uses internally. Currently only used for 221 timestamps in the history, as they are used in viminfo, and 222 for undo. 223 Using a value of 1 makes Vim not sleep after a warning or 224 error message. 225 {expr} must evaluate to a number. When the value is zero the 226 normal behavior is restored. 227 228 Can also be used as a |method|: > 229 GetTime()->test_settime() 230 231test_srand_seed([seed]) *test_srand_seed()* 232 When [seed] is given this sets the seed value used by 233 `srand()`. When omitted the test seed is removed. 234 235============================================================================== 2363. Assert functions *assert-functions-details* 237 238 239assert_beeps({cmd}) *assert_beeps()* 240 Run {cmd} and add an error message to |v:errors| if it does 241 NOT produce a beep or visual bell. 242 Also see |assert_fails()| and |assert-return|. 243 244 Can also be used as a |method|: > 245 GetCmd()->assert_beeps() 246< 247 *assert_equal()* 248assert_equal({expected}, {actual} [, {msg}]) 249 When {expected} and {actual} are not equal an error message is 250 added to |v:errors| and 1 is returned. Otherwise zero is 251 returned |assert-return|. 252 There is no automatic conversion, the String "4" is different 253 from the Number 4. And the number 4 is different from the 254 Float 4.0. The value of 'ignorecase' is not used here, case 255 always matters. 256 When {msg} is omitted an error in the form "Expected 257 {expected} but got {actual}" is produced. 258 Example: > 259 assert_equal('foo', 'bar') 260< Will result in a string to be added to |v:errors|: 261 test.vim line 12: Expected 'foo' but got 'bar' ~ 262 263 Can also be used as a |method|: > 264 mylist->assert_equal([1, 2, 3]) 265 266 267< *assert_equalfile()* 268assert_equalfile({fname-one}, {fname-two}) 269 When the files {fname-one} and {fname-two} do not contain 270 exactly the same text an error message is added to |v:errors|. 271 Also see |assert-return|. 272 When {fname-one} or {fname-two} does not exist the error will 273 mention that. 274 Mainly useful with |terminal-diff|. 275 276 Can also be used as a |method|: > 277 GetLog()->assert_equalfile('expected.log') 278 279 280assert_exception({error} [, {msg}]) *assert_exception()* 281 When v:exception does not contain the string {error} an error 282 message is added to |v:errors|. Also see |assert-return|. 283 This can be used to assert that a command throws an exception. 284 Using the error number, followed by a colon, avoids problems 285 with translations: > 286 try 287 commandthatfails 288 call assert_false(1, 'command should have failed') 289 catch 290 call assert_exception('E492:') 291 endtry 292 293assert_fails({cmd} [, {error} [, {msg}]]) *assert_fails()* 294 Run {cmd} and add an error message to |v:errors| if it does 295 NOT produce an error. Also see |assert-return|. 296 When {error} is given it must match in |v:errmsg|. 297 Note that beeping is not considered an error, and some failing 298 commands only beep. Use |assert_beeps()| for those. 299 300 Can also be used as a |method|: > 301 GetCmd()->assert_fails('E99:') 302 303assert_false({actual} [, {msg}]) *assert_false()* 304 When {actual} is not false an error message is added to 305 |v:errors|, like with |assert_equal()|. 306 Also see |assert-return|. 307 A value is false when it is zero. When {actual} is not a 308 number the assert fails. 309 When {msg} is omitted an error in the form 310 "Expected False but got {actual}" is produced. 311 312 Can also be used as a |method|: > 313 GetResult()->assert_false() 314 315assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()* 316 This asserts number and |Float| values. When {actual} is lower 317 than {lower} or higher than {upper} an error message is added 318 to |v:errors|. Also see |assert-return|. 319 When {msg} is omitted an error in the form 320 "Expected range {lower} - {upper}, but got {actual}" is 321 produced. 322 323 *assert_match()* 324assert_match({pattern}, {actual} [, {msg}]) 325 When {pattern} does not match {actual} an error message is 326 added to |v:errors|. Also see |assert-return|. 327 328 {pattern} is used as with |=~|: The matching is always done 329 like 'magic' was set and 'cpoptions' is empty, no matter what 330 the actual value of 'magic' or 'cpoptions' is. 331 332 {actual} is used as a string, automatic conversion applies. 333 Use "^" and "$" to match with the start and end of the text. 334 Use both to match the whole text. 335 336 When {msg} is omitted an error in the form 337 "Pattern {pattern} does not match {actual}" is produced. 338 Example: > 339 assert_match('^f.*o$', 'foobar') 340< Will result in a string to be added to |v:errors|: 341 test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~ 342 343 Can also be used as a |method|: > 344 getFile()->assert_match('foo.*') 345< 346 *assert_notequal()* 347assert_notequal({expected}, {actual} [, {msg}]) 348 The opposite of `assert_equal()`: add an error message to 349 |v:errors| when {expected} and {actual} are equal. 350 Also see |assert-return|. 351 352 Can also be used as a |method|: > 353 mylist->assert_notequal([1, 2, 3]) 354 355< *assert_notmatch()* 356assert_notmatch({pattern}, {actual} [, {msg}]) 357 The opposite of `assert_match()`: add an error message to 358 |v:errors| when {pattern} matches {actual}. 359 Also see |assert-return|. 360 361 Can also be used as a |method|: > 362 getFile()->assert_notmatch('bar.*') 363 364 365assert_report({msg}) *assert_report()* 366 Report a test failure directly, using {msg}. 367 Always returns one. 368 369 Can also be used as a |method|: > 370 GetMessage()->assert_report() 371 372 373assert_true({actual} [, {msg}]) *assert_true()* 374 When {actual} is not true an error message is added to 375 |v:errors|, like with |assert_equal()|. 376 Also see |assert-return|. 377 A value is TRUE when it is a non-zero number. When {actual} 378 is not a number the assert fails. 379 When {msg} is omitted an error in the form "Expected True but 380 got {actual}" is produced. 381 382 Can also be used as a |method|: > 383 GetResult()->assert_true() 384< 385 386 vim:tw=78:ts=8:noet:ft=help:norl: 387