VIM: testing

## TESTING

    *testing.txt*	For Vim version 8.2.  Last change: 2020 Feb 22

    		  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=double
    			call 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 when {val} is non-zero
    		redraw       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 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:
    			try
    			  commandthatfails
    			  call assert_false(1, 'command should have failed')
    			catch
    			  call assert_exception('E492:')
    			endtry

    assert_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|.
    		Note that 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 Mon, Mar 30, 2020 10:53:32 PM