neovim

Neovim text editor
git clone https://git.dasho.dev/neovim.git
Log | Files | Refs | README

README.txt (4036B)

      1 This directory contains tests for various Vim features.
      2 For testing an indent script see runtime/indent/testdir/README.txt.
      3 
      4 If it makes sense, add a new test method to an already existing file.  You may
      5 want to separate it from other tests with comment lines.
      6 
      7 TO ADD A NEW STYLE TEST:
      8 
      9 1) Create a test_<subject>.vim file.
     10 2) Add test_<subject>.res to NEW_TESTS_RES in Make_all.mak in alphabetical
     11   order.
     12 3) Also add an entry "test_<subject>" to NEW_TESTS in Make_all.mak.
     13 4) Use make test_<subject> to run a single test.
     14 
     15 At 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
     17 bit faster, because Vim doesn't have to be started, one Vim instance runs many
     18 tests.
     19 
     20 At 4), to run a test in GUI, add "GUI_FLAG=-g" to the make command.
     21 
     22 
     23 What you can use (see test_assert.vim for an example):
     24 
     25 - Call assert_equal(), assert_true(), assert_false(), etc.
     26 
     27 - Use assert_fails() to check for expected errors.
     28 
     29 - Use try/catch to avoid an exception aborts the test.
     30 
     31 - 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.
     35 
     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
     38  event. See test_cursor_func.vim for an example.
     39 
     40 - If the bug that is being tested isn't fixed yet, you can throw an exception
     41  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 
     44 - The following environment variables are recognized and can be set to
     45  influence the behavior of the test suite (see runtest.vim for details)
     46 
     47  - $TEST_MAY_FAIL=Test_channel_one    - ignore those failing tests
     48  - $TEST_FILTER=Test_channel    - only run test that match this pattern
     49  - $TEST_SKIP_PAT=Test_channel  - skip tests that match this pattern
     50  - $TEST_NO_RETRY=yes           - do not try to re-run failing tests
     51  You can also set them in Vim:
     52    :let $TEST_MAY_FAIL = 'Test_channel_one'
     53    :let $TEST_FILTER = '_set_mode'
     54    :let $TEST_SKIP_PAT = 'Test_loop_forever'
     55    :let $TEST_NO_RETRY = 'yes'
     56  Use an empty string to revert, e.g.:
     57    :let $TEST_FILTER = ''
     58 
     59 - See the start of runtest.vim for more help.
     60 
     61 
     62 TO ADD A SCREEN DUMP TEST:
     63 
     64 Mostly the same as writing a new style test.  Additionally, see help on
     65 "terminal-dumptest".  Put the reference dump in "dumps/Test_func_name.dump".
     66 
     67 
     68 OLD STYLE TESTS:
     69 
     70 There are a few tests that are used when Vim was built without the +eval
     71 feature.  These cannot use the "assert" functions, therefore they consist of a
     72 .in file that contains Normal mode commands between STARTTEST and ENDTEST.
     73 They modify the file and the result gets written in the test.out file.  This
     74 is then compared with the .ok file.  If they are equal the test passed.  If
     75 they differ the test failed.
     76 
     77 
     78 RUNNING THE TESTS:
     79 
     80 To run a single test from the src directory:
     81 
     82    $ make test_<name>
     83 
     84 The below commands should be run from the src/testdir directory.
     85 
     86 To run a single test:
     87 
     88    $ make test_<name>.res
     89 
     90 The file 'messages' contains the messages generated by the test script.  If a
     91 test fails, then the test.log file contains the error messages.  If all the
     92 tests are successful, then this file will be an empty file.
     93 
     94 - To run a single test function from a test script:
     95 
     96    $ ../vim -u NONE -S runtest.vim <test_file>.vim <function_name>
     97 
     98 - To execute only specific test functions, add a second argument:
     99 
    100  $ ../vim -u NONE -S runtest.vim test_channel.vim open_delay
    101 
    102 
    103 - To run all the tests:
    104 
    105    $ make
    106 
    107 - To run the test on MS-Windows using the MSVC nmake:
    108 
    109    > nmake -f Make_dos.mak
    110 
    111 - To run the tests with GUI Vim:
    112 
    113    $ make GUI_FLAG=-g
    114 
    115    or
    116 
    117    $ make VIMPROG=../gvim
    118 
    119 - To cleanup the temporary files after running the tests:
    120 
    121    $ make clean