blob: d3f11b23ee7a6e8b1ca7f427323702c3d0c8f679 [file] [log] [blame]
Bram Moolenaara9537d22014-08-29 10:04:47 +02001This directory contains tests for various Vim features.
Bram Moolenaarec504012019-01-11 17:30:16 +01002For testing an indent script see runtime/indent/testdir/README.txt.
Bram Moolenaara9537d22014-08-29 10:04:47 +02003
Bram Moolenaar6602af72016-01-07 22:01:01 +01004If it makes sense, add a new test method to an already existing file. You may
5want to separate it from other tests with comment lines.
Bram Moolenaara9537d22014-08-29 10:04:47 +02006
Bram Moolenaar6602af72016-01-07 22:01:01 +01007TO ADD A NEW STYLE TEST:
8
91) Create a test_<subject>.vim file.
Bram Moolenaarec504012019-01-11 17:30:16 +0100102) Add test_<subject>.res to NEW_TESTS_RES in Make_all.mak in alphabetical
11 order.
123) Also add an entry "test_<subject>" to NEW_TESTS in Make_all.mak.
134) Use make test_<subject> to run a single test.
Bram Moolenaara9537d22014-08-29 10:04:47 +020014
Bram Moolenaar02c97212018-09-09 15:56:06 +020015At 2), instead of running the test separately, it can be included in
16"test_alot". Do this for quick tests without side effects. The test runs a
17bit faster, because Vim doesn't have to be started, one Vim instance runs many
18tests.
19
Bram Moolenaar85683ec2020-02-20 22:35:02 +010020At 4), to run a test in GUI, add "GUI_FLAG=-g" to the make command.
21
Bram Moolenaar02c97212018-09-09 15:56:06 +020022
Bram Moolenaar6602af72016-01-07 22:01:01 +010023What you can use (see test_assert.vim for an example):
Bram Moolenaar02c97212018-09-09 15:56:06 +020024
Bram Moolenaardac19472016-09-03 22:35:40 +020025- Call assert_equal(), assert_true(), assert_false(), etc.
Bram Moolenaar02c97212018-09-09 15:56:06 +020026
27- Use assert_fails() to check for expected errors.
28
29- Use try/catch to avoid an exception aborts the test.
30
Bram Moolenaarb45125b2019-03-24 20:18:40 +010031- Use test_alloc_fail() to have memory allocation fail. This makes it possible
32 to check memory allocation failures are handled gracefully. You need to
33 change the source code to add an ID to the allocation. Add a new one to
34 alloc_id_T, before aid_last.
Bram Moolenaar02c97212018-09-09 15:56:06 +020035
36- Use test_override() to make Vim behave differently, e.g. if char_avail()
37 must return FALSE for a while. E.g. to trigger the CursorMovedI autocommand
Bram Moolenaarb45125b2019-03-24 20:18:40 +010038 event. See test_cursor_func.vim for an example.
Bram Moolenaar02c97212018-09-09 15:56:06 +020039
Bram Moolenaardac19472016-09-03 22:35:40 +020040- If the bug that is being tested isn't fixed yet, you can throw an exception
Bram Moolenaar02c97212018-09-09 15:56:06 +020041 with "Skipped" so that it's clear this still needs work. E.g.: throw
42 "Skipped: Bug with <c-e> and popupmenu not fixed yet"
43
Bram Moolenaarfd89d7e2016-06-04 20:25:05 +020044- See the start of runtest.vim for more help.
Bram Moolenaar6602af72016-01-07 22:01:01 +010045
46
Bram Moolenaarda650582018-02-20 15:51:40 +010047TO ADD A SCREEN DUMP TEST:
48
Bram Moolenaarc4568ab2018-11-16 16:21:05 +010049Mostly the same as writing a new style test. Additionally, see help on
Bram Moolenaarda650582018-02-20 15:51:40 +010050"terminal-dumptest". Put the reference dump in "dumps/Test_func_name.dump".
51
Bram Moolenaar02c037a2020-08-30 19:26:45 +020052
53OLD STYLE TESTS:
54
55There are a few tests that are used when Vim was built without the +eval
56feature. These cannot use the "assert" functions, therefore they consist of a
57.in file that contains Normal mode commands between STARTTEST and ENDTEST.
58They modify the file and the result gets writtein in the test.out file. This
59is then compared with the .ok file. If they are equal the test passed. If
60they differ the test failed.