*testing.txt* For Vim version 8.2. Last change: 2020 Feb 08 VIM REFERENCE MANUAL by Bram Moolenaar Testing Vim and Vim script *testing-support* Expression evaluation is explained in |eval|. This file goes into details about writing tests in Vim script. This can be used for testing Vim itself and for testing plugins. 1. Testing Vim |testing| 2. Test functions |test-functions-details| 3. Assert functions |assert-functions-details|
1. Testing Vim *testing* Vim can be tested after building it, usually with "make test". The tests are located in the directory "src/testdir". There are several types of tests added over time: test33.in oldest, don't add any of these test_something.in old style tests test_something.vim new style tests *new-style-testing* New tests should be added as new style tests. These use functions such as |assert_equal()| to keep the test commands and the expected result in one place. *old-style-testing* In some cases an old style test needs to be used. E.g. when testing Vim without the |+eval| feature. Find more information in the file src/testdir/README.txt.
2. Test functions *test-functions-details* test_alloc_fail({id},{countdown},{repeat}) *test_alloc_fail()* This is for testing: If the memory allocation with{id}is called, then decrement{countdown}, and when it reaches zero let memory allocation fail{repeat}times. When{repeat}is smaller than one it fails one time. Can also be used as a |method|:GetAllocId()->test_alloc_fail()test_autochdir() *test_autochdir()* Set a flag to enable the effect of 'autochdir' before Vim startup has finished. test_feedinput({string}) *test_feedinput()* Characters in{string}are queued for processing as if they were typed by the user. This uses a low level input buffer. This function works only when with |+unix| or GUI is running. Can also be used as a |method|:GetText()->test_feedinput()test_garbagecollect_now() *test_garbagecollect_now()* Like garbagecollect(), but executed right away. This must only be called directly to avoid any structure to exist internally, and |v:testing| must have been set before calling any function. test_garbagecollect_soon() *test_garbagecollect_soon()* Set the flag to call the garbagecollector as if in the main loop. Only to be used in tests. test_getvalue({name}) *test_getvalue()* Get the value of an internal variable. These values for{name}are supported: need_fileinfo Can also be used as a |method|:GetName()->test_getvalue()test_ignore_error({expr}) *test_ignore_error()* Ignore any error containing{expr}. A normal message is given instead. This is only meant to be used in tests, where catching the error with try/catch cannot be used (because it skips over following code).{expr}is used literally, not as a pattern. When the{expr}is the string "RESET" then the list of ignored errors is made empty. Can also be used as a |method|:GetErrorText()->test_ignore_error()test_null_blob() *test_null_blob()* Return a |Blob| that is null. Only useful for testing. test_null_channel() *test_null_channel()* Return a |Channel| that is null. Only useful for testing.{only available when compiled with the +channel feature}test_null_dict() *test_null_dict()* Return a |Dict| that is null. Only useful for testing. test_null_job() *test_null_job()* Return a |Job| that is null. Only useful for testing.{only available when compiled with the +job feature}test_null_list() *test_null_list()* Return a |List| that is null. Only useful for testing. test_null_partial() *test_null_partial()* Return a |Partial| that is null. Only useful for testing. test_null_string() *test_null_string()* Return a |String| that is null. Only useful for testing. test_unknown() *test_unknown()* Return a value with unknown type. Only useful for testing. test_void() *test_void()* Return a value with void type. Only useful for testing. test_option_not_set({name}) *test_option_not_set()* Reset the flag that indicates option{name}was set. Thus it looks like it still has the default value. Use like this:set ambiwidth=doublecall test_option_not_set('ambiwidth')Now the 'ambiwidth' option behaves like it was never changed, even though the value is "double". Only to be used for testing! Can also be used as a |method|:GetOptionName()->test_option_not_set()test_override({name},{val}) *test_override()* Overrides certain parts of Vim's internal processing to be able to run tests. Only to be used for testing Vim! The override is enabled when{val}is non-zero and removed when{val}is zero. Current supported values for name are:name effect whenredraw disable the redrawing() function redraw_flag ignore the RedrawingDisabled flag char_avail disable the char_avail() function starting reset the "starting" variable, see below nfa_fail makes the NFA regexp engine fail to force a fallback to the old engine no_query_mouse do not query the mouse position for "dec" terminals no_wait_return set the "no_wait_return" flag. Not restored with "ALL". ALL clear all overrides ({val}is non-zero{val}is not used) "starting" is to be used when a test should behave like startup was done. Since the tests are run by sourcing a script the "starting" variable is non-zero. This is usually a good thing (tests run faster), but sometimes changes behavior in a way that the test doesn't work properly. When using:call test_override('starting', 1)< The value of "starting" is saved. It is restored by:call test_override('starting', 0)< Can also be used as a |method|:GetOverrideVal()-> test_override('starting')test_refcount({expr}) *test_refcount()* Return the reference count of{expr}. When{expr}is of a type that does not have a reference count, returns -1. Only to be used for testing. Can also be used as a |method|:GetVarname()->test_refcount()test_scrollbar({which},{value},{dragging}) *test_scrollbar()* Pretend using scrollbar{which}to move it to position{value}.{which}can be: left Left scrollbar of the current window right Right scrollbar of the current window hor Horizontal scrollbar For the vertical scrollbars{value}can be 1 to the line-count of the buffer. For the horizontal scrollbar the{value}can be between 1 and the maximum line length, assuming 'wrap' is not set. When{dragging}is non-zero it's like dragging the scrollbar, otherwise it's like clicking in the scrollbar. Only works when the{which}scrollbar actually exists, obviously only when using the GUI. Can also be used as a |method|:GetValue()->test_scrollbar('right', 0)test_setmouse({row},{col}) *test_setmouse()* Set the mouse position to be used for the next mouse action.{row}and{col}are one based. For example:call test_setmouse(4, 20)call feedkeys("\<LeftMouse>", "xt")test_settime({expr}) *test_settime()* Set the time Vim uses internally. Currently only used for timestamps in the history, as they are used in viminfo, and for undo. Using a value of 1 makes Vim not sleep after a warning or error message.{expr}must evaluate to a number. When the value is zero the normal behavior is restored. Can also be used as a |method|:GetTime()->test_settime()test_srand_seed([seed]) *test_srand_seed()* When [seed] is given this sets the seed value used by `srand()`. When omitted the test seed is removed.
3. Assert functions *assert-functions-details* assert_beeps({cmd}) *assert_beeps()* Run{cmd}and add an error message to |v:errors| if it does NOT produce a beep or visual bell. Also see |assert_fails()| and |assert-return|. Can also be used as a |method|:GetCmd()->assert_beeps()*assert_equal()* assert_equal({expected},{actual}[,{msg}]) When{expected}and{actual}are not equal an error message is added to |v:errors| and 1 is returned. Otherwise zero is returned |assert-return|. There is no automatic conversion, the String "4" is different from the Number 4. And the number 4 is different from the Float 4.0. The value of 'ignorecase' is not used here, case always matters. When{msg}is omitted an error in the form "Expected{expected}but got{actual}" is produced. Example:assert_equal('foo', 'bar')Will result in a string to be added to |v:errors|:test.vim line 12: Expected 'foo' but got 'bar'Can also be used as a |method|:mylist->assert_equal([1, 2, 3])*assert_equalfile()* assert_equalfile({fname-one},{fname-two}) When the files{fname-one}and{fname-two}do not contain exactly the same text an error message is added to |v:errors|. Also see |assert-return|. When{fname-one}or{fname-two}does not exist the error will mention that. Mainly useful with |terminal-diff|. Can also be used as a |method|:GetLog()->assert_equalfile('expected.log')assert_exception({error}[,{msg}]) *assert_exception()* When v:exception does not contain the string{error}an error message is added to |v:errors|. Also see |assert-return|. This can be used to assert that a command throws an exception. Using the error number, followed by a colon, avoids problems with translations:trycommandthatfailscall assert_false(1, 'command should have failed')catchcall assert_exception('E492:')endtryassert_fails({cmd}[,{error}[,{msg}]]) *assert_fails()* Run{cmd}and add an error message to |v:errors| if it does NOT produce an error. Also see |assert-return|. When{error}is given it must match in |v:errmsg|.Notethat beeping is not considered an error, and some failing commands only beep. Use |assert_beeps()| for those. Can also be used as a |method|:GetCmd()->assert_fails('E99:')assert_false({actual}[,{msg}]) *assert_false()* When{actual}is not false an error message is added to |v:errors|, like with |assert_equal()|. Also see |assert-return|. A value is false when it is zero. When{actual}is not a number the assert fails. When{msg}is omitted an error in the form "Expected False but got{actual}" is produced. Can also be used as a |method|:GetResult()->assert_false()assert_inrange({lower},{upper},{actual}[,{msg}]) *assert_inrange()* This asserts number and |Float| values. When{actual}is lower than{lower}or higher than{upper}an error message is added to |v:errors|. Also see |assert-return|. When{msg}is omitted an error in the form "Expected range{lower}-{upper}, but got{actual}" is produced. *assert_match()* assert_match({pattern},{actual}[,{msg}]) When{pattern}does not match{actual}an error message is added to |v:errors|. Also see |assert-return|.{pattern}is used as with |=~|: The matching is always done like 'magic' was set and 'cpoptions' is empty, no matter what the actual value of 'magic' or 'cpoptions' is.{actual}is used as a string, automatic conversion applies. Use "^" and "$" to match with the start and end of the text. Use both to match the whole text. When{msg}is omitted an error in the form "Pattern{pattern}does not match{actual}" is produced. Example:assert_match('^f.*o$', 'foobar')Will result in a string to be added to |v:errors|:test.vim line 12: Pattern '^f.*o$' does not match 'foobar'Can also be used as a |method|:getFile()->assert_match('foo.*')*assert_notequal()* assert_notequal({expected},{actual}[,{msg}]) The opposite of `assert_equal()`: add an error message to |v:errors| when{expected}and{actual}are equal. Also see |assert-return|. Can also be used as a |method|:mylist->assert_notequal([1, 2, 3])*assert_notmatch()* assert_notmatch({pattern},{actual}[,{msg}]) The opposite of `assert_match()`: add an error message to |v:errors| when{pattern}matches{actual}. Also see |assert-return|. Can also be used as a |method|:getFile()->assert_notmatch('bar.*')assert_report({msg}) *assert_report()* Report a test failure directly, using{msg}. Always returns one. Can also be used as a |method|:GetMessage()->assert_report()assert_true({actual}[,{msg}]) *assert_true()* When{actual}is not true an error message is added to |v:errors|, like with |assert_equal()|. Also see |assert-return|. A value is TRUE when it is a non-zero number. When{actual}is not a number the assert fails. When{msg}is omitted an error in the form "Expected True but got{actual}" is produced. Can also be used as a |method|:GetResult()->assert_true()vim:tw=78:ts=8:noet:ft=help:norl:
Generated by vim2html on Wed Feb 26 03:19:42 UTC 2020