testing.txt ForVim version 9.1. Last change: 2025 Mar 25VIM REFERENCE MANUAL by Bram MoolenaarTesting Vim and Vimscripttesting-supportExpression evaluationis explained ineval.txt. This file goes into detailsaboutwriting tests in Vim script. This can be used fortesting Vim itselfand fortesting plugins.1. Testing Vimtesting2. Testfunctionstest-functions-details3. Assertfunctionsassert-functions-details==============================================================================1. Testing VimtestingVim can be tested after building it, usually with "make test".The tests are located in the directory "src/testdir".There are two types of tests added over time:test20.inoldest, only for tiny buildstest_something.vimnew style testsnew-style-testingNew tests should be addedas new style tests. The test scripts are namedtest_<feature>.vim (replace<feature> with the feature under test). These usefunctions suchasassert_equal() to keep the test commands and the expectedresult in one place.old-style-testingThese tests are used only fortesting Vim without the+eval feature.Find more information in the file src/testdir/README.txt.==============================================================================2. Testfunctionstest-functions-detailstest_alloc_fail({id},{countdown},{repeat})test_alloc_fail()Thisis for testing: If the memory allocation with{id}iscalled, then decrement{countdown}, and whenit reaches zerolet memory allocation fail{repeat} times. When{repeat}issmaller than oneit fails one time.Can also be usedasamethod:GetAllocId()->test_alloc_fail()Return type:Numbertest_autochdir()test_autochdir()Seta flag to enable the effect of'autochdir' before Vimstartup has finished.Return type:Numbertest_feedinput({string})test_feedinput()Characters in{string} are queued for processingas if theywere typed by the user. This usesa low level input buffer.This function works only when with+unix orGUIis running.Can also be usedasamethod:GetText()->test_feedinput()Return type:Numbertest_garbagecollect_now()test_garbagecollect_now()Likegarbagecollect(), but executed right away. Thismustonly be called directly to avoid any structure to existinternally, andv:testingmust have been set before callingany function.E1142This will not work when called froma:def function, becausevariables on the stack will be freed.Return type:Numbertest_garbagecollect_soon()test_garbagecollect_soon()Set the flag to call the garbagecollectoras if in the mainloop. Only to be used in tests.Return type:Numbertest_getvalue({name})test_getvalue()Get the value of an internal variable. These values for{name} are supported:need_fileinfoCan also be usedasamethod:GetName()->test_getvalue()Return type:Numbertest_gui_event()test_gui_event({event},{args})GenerateaGUI{event} with arguments{args} fortesting Vimfunctionality. This function works only when theGUIisrunning.{event}isaString and the supported values are: "dropfiles"drop one or more files ina window. "findrepl" search and replace text. "mouse"mouse button click event. "scrollbar" move or drag the scrollbar. "key"senda low-level keyboard event. "tabline"selectatab page by mouse click. "tabmenu"selecta tabline menu entry.{args}isaDict and contains the arguments for the event."dropfiles": Drop one or more files ina specified window. The supported items in{args} are: files:List of file names row:window row number col:window column number modifiers:key modifiers. The supported values are: 0x4Shift 0x8Alt 0x10Ctrl The files are added to theargument-list and the first file in{files}is edited in the window. Seedrag-n-drop for more information. This event works only when thedrop_file featureis present."findrepl":{only available when the GUI has a find/replace dialog} Performa search and replace of text. The supported items in{args} are: find_text:string to find. repl_text:replacement string. flags:flags controlling the find/replace. Supportedvalues are: 1search nextstring (find dialog) 2search nextstring (replace dialog) 3replacestring once 4replace all matches 8match whole words only 16matchcase forward:set to 1 for forward search."mouse": Inject eithera mouse button click, ora mouse move, event. The supported items in{args} are: button:mouse button. The supported values are:0left mouse button 1middle mouse button 2right mouse button 3mouse button release 4scroll wheel down 5scroll wheel up 6scroll wheel left 7scroll wheel right row:mouse click row number. The first row of theVimwindowis 1 and the last rowis'lines'. col:mouse click column number. The maximum valueof{col}is'columns'. multiclick:set to 1 to injecta multiclick mouse event. modifiers:key modifiers. The supported values are: 4shiftis pressed 8altis pressed 16ctrlis pressed move:Optional; if used andTRUE thena mouse move event can be generated.Only{args} row: and col: are used andrequired; they are interpretedas pixels orscreen cells, depending on "cell".Only results in an event when'mousemoveevent'is set orapopup uses mouse move events. cell:Optional: when present andTRUE then "move"uses screen cells instead of pixel positions"scrollbar": Set or drag the left, right or horizontal scrollbar. Only works when the scrollbar actually exists. The supported items in{args} are: which:Selects the scrollbar. The supported valuesare: left Left scrollbar of the currentwindow right Right scrollbar of the currentwindow hor Horizontal scrollbar value:Amount to scroll. For the vertical scrollbarsthe value can be between0 to the line-countof the buffer minus one. For the horizontalscrollbar the value can be between 1 and themaximum line length, assuming'wrap'is notset. dragging:1 to drag the scrollbar and0 to click in thescrollbar."key": Senda low-level keyboard event (e.g. key-up or down). Currently only supported on MS-Windows. The supported items in{args} are: event:The supportedstring values are: keyup generatea keyup event keydown generatea keydown event keycode: Keycode to use fora keyup ora keydown event.E1291"tabline": Injecta mouse click event on the tabline to selecta tabpage. The supported items in{args} are: tabnr:tab page number"tabmenu": Inject an event to selecta tabline menu entry. The supported items in{args} are: tabnr:tab page number item:tab page menu item number. 1 for the firstmenu item, 2 for the second item and so on.After injecting theGUI events you probably should callfeedkeys() to have them processed, e.g.:call feedkeys("y", 'Lx!')ReturnsTRUE if the eventis successfully added,FALSE ifthereisa failure.Can also be usedasamethod:GetEvent()->test_gui_event({args})Return type:vim9-booleantest_ignore_error({expr})test_ignore_error()Ignore any error containing{expr}.A normal messageis giveninstead.Thisis only meant to be used in tests, where catching theerror with try/catch cannot be used (becauseit skips overfollowing code).{expr}is used literally, notasa pattern.When the{expr}is thestring "RESET" then thelist of ignorederrorsis made empty.Can also be usedasamethod:GetErrorText()->test_ignore_error()Return type:Numbertest_mswin_event({event},{args})test_mswin_event()Generatea low-levelMS-Windows{event} with arguments{args}fortesting Vim functionality. It works forMS-WindowsGUIand for the console.{event}isaString and the supported values are: "mouse"mouse event. "key"keyboard event. "set_keycode_trans_strategy"Change the key translation method."mouse": Inject eithera mouse button click, ora mouse move, event. The supported items in{args} are: button:mouse button. The supported values are:0right mouse button 1middle mouse button 2left mouse button 3mouse button release 4scroll wheel down 5scroll wheel up 6scroll wheel left 7scroll wheel right row:mouse click row number. The first row of theVimwindowis 1 and the last rowis'lines'. col:mouse click column number. The maximum valueof{col}is'columns'.Note: row and col are always interpretedasscreen cells for the console application.But, they may be interpretedas pixelsfor the GUI, depending on "cell". multiclick:set to 1 to injectadouble-click mouse event. modifiers:key modifiers. The supported values are: 4shiftis pressed 8altis pressed 16ctrlis pressed move:Optional; if used andTRUE thena mouse move event can be generated.Only{args} row: and col: are used andrequired.Only results in an event when'mousemoveevent'is set orapopup uses mouse move events. cell:Optional for the GUI: when present andTRUEthen "move" uses screen cells instead of pixelpositions. Not used by the console."key": Senda low-level keyboard event (e.g. keyup or keydown). The supported items in{args} are: event:The supportedstring values are: keyup generatea keyup event keydown generatea keydown event keycode:Keycode to use fora keyup ora keydown event. modifiers:Optional; key modifiers.The supported values are: 2shiftis pressed 4ctrlis pressed 8altis pressedNote: These values are different from themouse modifiers. execute:Optional. Similar tofeedkeys() mode x.When thisis included and set totrue(non-zero) then Vim will process any bufferedunprocessed key events. All other{args}items are optional when thisis set and true."set_keycode_trans_strategy":w32-experimental-keycode-trans-strategy Switch the keycode translation method. The supported methods are: experimental: Themethod used after Patch v8.2.4807 using ToUnicode() Win API call. classic: Themethod used pre Patch v8.2.4807 using the TranslateMessage() Win API call.ReturnsTRUE if the eventis successfully added or executed,FALSE if thereisa failure.Can also be usedasamethod:GetEvent()->test_mswin_event({args})Return type:vim9-booleantest_null_blob()test_null_blob()ReturnaBlob thatis null. Only useful for testing.Return type:Blobtest_null_channel()test_null_channel()ReturnaChannel thatis null. Only useful for testing.{only available when compiled with the +channel feature}Return type:Channeltest_null_dict()test_null_dict()ReturnaDict thatis null. Only useful for testing.Return type: dict<any>test_null_function()test_null_function()ReturnaFuncref thatis null. Only useful for testing.Return type: func(...): unknowntest_null_job()test_null_job()ReturnaJob thatis null. Only useful for testing.{only available when compiled with the +job feature}Return type:jobtest_null_list()test_null_list()ReturnaList thatis null. Only useful for testing.Return type: list<any>test_null_partial()test_null_partial()ReturnaPartial thatis null. Only useful for testing.Return type: func(...): unknowntest_null_string()test_null_string()ReturnaString thatis null. Only useful for testing.Return type:Stringtest_null_tuple()test_null_tuple()ReturnaTuple thatis null. Only useful for testing.Return type:Tupletest_option_not_set({name})test_option_not_set()Reset the flag that indicates option{name} was set. Thusitlooks likeit still has the default value. Use like this:set ambiwidth=doublecall test_option_not_set('ambiwidth')Now the'ambiwidth' option behaves likeit was never changed,even though the valueis "double".Only to be used for testing!Can also be usedasamethod:GetOptionName()->test_option_not_set()Return type:Numbertest_override({name},{val})test_override()Overrides certain parts of Vim's internal processing to be ableto run tests. Only to be used fortesting Vim!The overrideis enabled when{val}is non-zero and removedwhen{val}is zero.Current supported values for{name} are:{name} effect when {val} is non-zeroalloc_lines makea copy of every buffer line into allocated memory, so that memory accesserrors can be found by valgrind.autoload `import autoload` will load thescript right away, not postponed until an itemis used.char_avail disable the char_avail() function.defcompile all the:deffunctions ina sourcedscript are compiled when defined. Thisis similar to using the:defcompile command ina script.nfa_fail makes theNFAregexp engine fail to forcea fallback to the old engine.no_query_mousedo not query the mouse position for "dec"terminals.no_wait_returnset the "no_wait_return" flag. Not restoredwith "ALL".redraw disable the redrawing() function.redraw_flag ignore the RedrawingDisabled flag.starting reset the "starting" variable, see below.term_props reset allterminal properties when the versionstringis detected.ui_delay time in msec to use in ui_delay(); overrulesa wait time of up to 3 seconds for messages.unreachable no error for code after:throw and:return.uptime overrules sysinfo.uptime.vterm_title setting thewindow title byajob running inaterminal window.ALL clear all overrides, except alloc_lines ({val}is not used)."starting"is to be used whena test should behave likestartup was done. Since the tests are run by sourcingascript the "starting" variableis non-zero. Thisis usuallyagood thing (tests run faster), but sometimes this changesbehavior ina way that the test doesn't work properly.When using:call test_override('starting', 1)The value of "starting"is saved. Itis restored by:call test_override('starting', 0)To make sure the flagis reset later using:defer can beuseful:call test_override('unreachable', 1)defer call test_override('unreachable', 0)Can also be usedasamethod:GetOverrideVal()-> test_override('starting')Return type:Numbertest_refcount({expr})test_refcount()Return thereferencecount of{expr}. When{expr}is ofatype that does not haveareference count, returns -1. Onlyto be used for testing.Can also be usedasamethod:GetVarname()->test_refcount()Return type:Numbertest_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")Return type:Numbertest_settime({expr})test_settime()Set the time Vim uses internally. Currently only used fortimestamps in the history,as they are used in viminfo, andfor undo.Usinga value of 1 makes Vim not sleep aftera warning orerror message.{expr}must evaluate toa number. When the valueis zero thenormal behavioris restored.Can also be usedasamethod:GetTime()->test_settime()Return type:Numbertest_srand_seed([{seed}])test_srand_seed()When{seed}is given this sets the seed value used bysrand(). When omitted the test seedis removed.Return type:Numbertest_unknown()test_unknown()Returna value with unknown type. Only useful for testing.Return type: unknowntest_void()test_void()Returna value with void type. Only useful for testing.Return type: void==============================================================================3. Assertfunctionsassert-functions-detailsassert_beeps({cmd})assert_beeps()Run{cmd} and add an error message tov:errors ifit doesNOT produceabeep or visual bell.Also seeassert_fails(),assert_nobeep() andassert-return.Can also be usedasamethod:GetCmd()->assert_beeps()Return type:Numberassert_equal()assert_equal({expected},{actual} [,{msg}])When{expected} and{actual} are not equal an error messageisadded tov:errors and 1is returned. Otherwise zeroisreturned.assert-returnThe erroris in the form "Expected{expected} but got{actual}". When{msg}is presentitis prefixed to that,along with the location of the assert when run froma script.Thereis no automatic conversion, theString "4"is differentfrom theNumber 4. And the number 4is different from theFloat 4.0. The value of'ignorecase'is not used here,casealways matters.Example:call assert_equal('foo', 'bar', 'baz')Will add the following tov:errors:test.vim line 12: baz: Expected 'foo' but got 'bar'Can also be usedasamethod, the baseis passedas thesecond argument:mylist->assert_equal([1, 2, 3])Return type:Numberassert_equalfile()assert_equalfile({fname-one},{fname-two} [,{msg}])When the files{fname-one} and{fname-two}do not containexactly the same text an error messageis added tov:errors.Also seeassert-return.When{fname-one} or{fname-two} does not exist the error willmention that.Mainly useful withterminal-diff.Can also be usedasamethod:GetLog()->assert_equalfile('expected.log')Return type:Numberassert_exception({error} [,{msg}])assert_exception()Whenv:exception does not contain thestring{error} an errormessageis added tov:errors. Also seeassert-return.This can be used to assert thata command throws an exception.Using the error number, followed bya colon, avoids problemswith translations:try commandthatfails call assert_false(1, 'command should have failed')catch call assert_exception('E492:')endtryReturn type:Numberassert_fails()assert_fails({cmd} [,{error} [,{msg} [,{lnum} [,{context}]]]])Run{cmd} and add an error message tov:errors ifit doesNOT produce an error or when{error}is not found in theerror message. Also seeassert-return.E856When{error}isastringitmust be found literally in thefirst reported error. Most often this will be the error code,including the colon, e.g. "E123:".call assert_fails('bad cmd', 'E987:')When{error}isaList with one or two strings, these areusedas patterns. The firstpatternis matched against thefirst reported error:call assert_fails('cmd', ['E987:.*expected bool'])The second pattern, if present,is matched against the lastreported error.If thereis only one error then both patternsmust match. Thiscan be used to check that thereis only one error.To only match the last error use an emptystring for the firsterror:call assert_fails('cmd', ['', 'E987:'])If{msg}is empty thenitis not used. Do this to get thedefault message when passing the{lnum} argument.E1115When{lnum}is present and not negative, and the{error}argumentis present and matches, then thisis compared withthe line numberat which the error was reported. That can bethe line number ina function or ina script.E1116When{context}is presentitis usedasapattern and matchedagainst the context (script name or function name) where{lnum}is located in.Note that beepingis not considered an error, and some failingcommands only beep. Useassert_beeps() for those.Can also be usedasamethod:GetCmd()->assert_fails('E99:')Return type:Numberassert_false({actual} [,{msg}])assert_false()When{actual}is notfalse an error messageis added tov:errors, like withassert_equal().The erroris in the form "Expected False but got{actual}".When{msg}is presentitis prefixed to that, along with thelocation of the assert when run froma script.Also seeassert-return.A valueisfalse whenitis zero. When{actual}is notanumber the assert fails.Can also be usedasamethod:GetResult()->assert_false()Return type:Numberassert_inrange({lower},{upper},{actual} [,{msg}])assert_inrange()This asserts number andFloat values. When{actual}is lowerthan{lower} or higher than{upper} an error messageis addedtov:errors. Also seeassert-return.The erroris in the form "Expected range{lower}-{upper},but got{actual}". When{msg}is presentitis prefixed tothat.Return type:Numberassert_match()assert_match({pattern},{actual} [,{msg}])When{pattern} does not match{actual} an error messageisadded tov:errors. Also seeassert-return.The erroris in the form "Pattern{pattern} does not match{actual}". When{msg}is presentitis prefixed to that,along with the location of the assert when run froma script.{pattern}is usedas with=~: The matchingis always donelike'magic' was set and'cpoptions'is empty, no matter whatthe actual value of'magic' or'cpoptions' is.{actual}is usedasa string, automatic conversion applies.Use "^" and "$" to match with the start andend of the text.Use both to match the whole text.Example:call assert_match('^f.*o$', 'foobar')Will result inastring to be added tov:errors:test.vim line 12: Pattern '^f.*o$' does not match 'foobar'Can also be usedasamethod:getFile()->assert_match('foo.*')Return type:Numberassert_nobeep({cmd})assert_nobeep()Run{cmd} and add an error message tov:errors ifitproducesabeep or visual bell.Also seeassert_beeps().Can also be usedasamethod:GetCmd()->assert_nobeep()Return type:Numberassert_notequal()assert_notequal({expected},{actual} [,{msg}])The opposite ofassert_equal(): add an error message tov:errors when{expected} and{actual} are equal.Also seeassert-return.Can also be usedasamethod:mylist->assert_notequal([1, 2, 3])Return type:Numberassert_notmatch()assert_notmatch({pattern},{actual} [,{msg}])The opposite ofassert_match(): add an error message tov:errors when{pattern} matches{actual}.Also seeassert-return.Can also be usedasamethod:getFile()->assert_notmatch('bar.*')Return type:Numberassert_report({msg})assert_report()Reporta test failure directly, usingString{msg}.Always returns one.Can also be usedasamethod:GetMessage()->assert_report()Return type:Numberassert_true({actual} [,{msg}])assert_true()When{actual}is nottrue an error messageis added tov:errors, like withassert_equal().Also seeassert-return.A valueisTRUE whenitisa non-zero number. When{actual}is nota number the assert fails.When{msg}is givenitis prefixed to the default message,along with the location of the assert when run froma script.Can also be usedasamethod:GetResult()->assert_true()Return type:Number vim:tw=78:ts=8:noet:ft=help:norl: