-*terminal.txt* For Vim version 8.0. Last change: 2018 Jan 28
+*terminal.txt* For Vim version 8.0. Last change: 2018 Feb 20
VIM REFERENCE MANUAL by Bram Moolenaar
If the result is "1" you have it.
-1. Basic use |terminal-use|
- Typing |terminal-typing|
- Size and color |terminal-size-color|
- Syntax |:terminal|
- Resizing |terminal-resizing|
- Terminal Modes |Terminal-mode|
- Cursor style |terminal-cursor-style|
- Special keys |terminal-special-keys|
- Unix |terminal-unix|
- MS-Windows |terminal-ms-windows|
-2. Remote testing |terminal-testing|
-3. Debugging |terminal-debug|
- Starting |termdebug-starting|
- Example session |termdebug-example|
- Stepping through code |termdebug-stepping|
- Inspecting variables |termdebug-variables|
- Other commands |termdebug-commands|
- Communication |termdebug-communication|
- Customizing |termdebug-customizing|
+1. Basic use |terminal-use|
+ Typing |terminal-typing|
+ Size and color |terminal-size-color|
+ Syntax |:terminal|
+ Resizing |terminal-resizing|
+ Terminal Modes |Terminal-mode|
+ Cursor style |terminal-cursor-style|
+ Special keys |terminal-special-keys|
+ Unix |terminal-unix|
+ MS-Windows |terminal-ms-windows|
+2. Remote testing |terminal-testing|
+3. Diffing screen dumps |terminal-diff|
+ Writing a screen dump test for Vim |terminal-dumptest|
+ Creating a screen dump |terminal-screendump|
+ Comparing screen dumps |terminal-diffscreendump|
+4. Debugging |terminal-debug|
+ Starting |termdebug-starting|
+ Example session |termdebug-example|
+ Stepping through code |termdebug-stepping|
+ Inspecting variables |termdebug-variables|
+ Other commands |termdebug-commands|
+ Communication |termdebug-communication|
+ Customizing |termdebug-customizing|
{Vi does not have any of these commands}
{only available when compiled with the |+terminal| feature}
==============================================================================
-3. Debugging *terminal-debug*
+3. Diffing screen dumps *terminal-diff*
+
+In some cases it can be bothersome to test that Vim displays the right
+characters on the screen. E.g. with syntax highlighting. To make this
+simpler it is possible to take a screen dump of a terminal and compare it to
+an expected screen dump.
+
+Vim uses the window size, text, color and other attributes as displayed. The
+Vim screen size, font and other properties do not matter. Therefore this
+mechanism is portable across systems. A convential screenshot would reflect
+all differences, including font size and family.
+
+
+Writing a screen dump test for Vim ~
+ *terminal-dumptest*
+For an example see the Test_syntax_c() function in
+src/testdir/test_syntax.vim. The main parts are:
+- Write a file you want to test with. This is useful for testing syntax
+ highlighting. You can also start Vim with en empty buffer.
+- Run Vim in a terminal with a specific size. The default is 20 lines of 75
+ characters. This makes sure the dump is always this size. The function
+ RunVimInTerminal() takes care of this. Pass it the arguments for the Vim
+ command.
+- Send any commands to Vim using term_sendkeys(). For example: >
+ call term_sendkeys(buf, ":echo &lines &columns\<CR>")
+- Check that the screen is now in the expected state, using
+ VerifyScreenDump(). This expects the reference screen dump to be in the
+ src/testdir/dumps/ directory. Pass the name without ".dump". It is
+ recommended to use the name of the test function and a sequence number, so
+ that we know what test is using the file.
+- Repeat sending commands and checking the state.
+- Finally stop Vim by calling StopVimInTerminal().
+
+The first time you do this you won't have a screen dump yet. Create an empty
+file for now, e.g.: >
+ touch src/testdir/dumps/Test_function_name_01.dump
+
+The test will then fail, giving you the command to compare the reference dump
+and the failed dump, e.g.: >
+ call term_dumpdiff("Test_func.dump.failed", "dumps/Test_func.dump")
+
+Use this command in Vim, with the current directory set to src/testdir.
+Once you are satisfied with the test, move the failed dump in place of the
+reference: >
+ :!mv Test_func.dump.failed dumps/Test_func.dump
+
+
+Creating a screen dump ~
+ *terminal-screendump*
+
+To create the screen dump, run Vim (or any other program) in a terminal and
+make it show the desired state. Then use the term_dumpwrite() function to
+create a screen dump file. For example: >
+ :call term_dumpwrite(77, "mysyntax.dump")
+
+Here "77" is the buffer number of the terminal. Use `:ls!` to see it.
+
+You can view the screen dump with term_dumpload(): >
+ :call term_dumpload("mysyntax.dump")
+
+To verify that Vim still shows exactly the same screen, run Vim again with
+exactly the same way to show the desired state. Then create a screen dump
+again, using a different file name: >
+ :call term_dumpwrite(88, "test.dump")
+
+To assert that the files are exactly the same use assert_equalfile(): >
+ call assert_equalfile("mysyntax.dump", "test.dump")
+
+If there are differences then v:errors will contain the error message.
+
+
+Comparing screen dumps ~
+ *terminal-diffscreendump*
+
+assert_equalfile() does not make it easy to see what is different.
+To spot the problem use term_dumpdiff(): >
+ call term_dumpdiff("mysyntax.dump", "test.dump")
+
+This will open a window consisting of three parts:
+1. The contents of the first dump
+2. The difference between the first and second dump
+3. The contents of the second dump
+
+You can usually see what differs in the second part. Use the 'ruler' to
+relate it to the postion in the first or second dump.
+
+Alternatively, press "s" to swap the first and second dump. Do this everal
+times so that you can spot the difference in the context of the text.
+
+==============================================================================
+4. Debugging *terminal-debug*
The Terminal debugging plugin can be used to debug a program with gdb and view
the source code in a Vim window. Since this is completely contained inside
:Delete delete a breakpoint at the current line
:Step execute the gdb "step" command
- :Over execute the gdb "next" command (:Next is a Vim command)
+ :Over execute the gdb "next" command (:Next is a Vim command)
:Finish execute the gdb "finish" command
:Continue execute the gdb "continue" command
:Stop interrupt the program
--- /dev/null
+" Functions shared by tests making screen dumps.
+
+" Only load this script once.
+if exists('*RunVimInTerminal')
+ finish
+endif
+
+source shared.vim
+
+" Run Vim with "arguments" in a new terminal window.
+" By default uses a size of 20 lines and 75 columns.
+" Returns the buffer number of the terminal.
+"
+" Options is a dictionary (not used yet).
+func RunVimInTerminal(arguments, options)
+ " Make a horizontal and vertical split, so that we can get exactly the right
+ " size terminal window. Works only when we currently have one window.
+ call assert_equal(1, winnr('$'))
+ split
+ vsplit
+
+ " Always doo this with 256 colors and a light background.
+ set t_Co=256
+ hi Normal ctermfg=0 ctermbg=15
+
+ let cmd = GetVimCommandClean()
+ let cmd .= ' ' . a:arguments
+ let buf = term_start(cmd, {'curwin': 1, 'term_rows': 20, 'term_cols': 75})
+ call assert_equal([20, 75], term_getsize(buf))
+
+ return buf
+endfunc
+
+" Stop a Vim running in terminal buffer "buf".
+func StopVimInTerminal(buf)
+ call assert_equal("running", term_getstatus(a:buf))
+ call term_sendkeys(a:buf, ":qa!\<cr>")
+ call WaitFor('term_getstatus(' . a:buf . ') == "finished"')
+ only!
+endfunc
+
+" Verify that Vim running in terminal buffer "buf" matches the screen dump.
+" The file name used is "dumps/{filename}.dump".
+" Will wait for up to a second for the screen dump to match.
+func VerifyScreenDump(buf, filename)
+ let reference = 'dumps/' . a:filename . '.dump'
+ let testfile = a:filename . '.dump.failed'
+
+ let i = 0
+ while 1
+ call delete(testfile)
+ call term_dumpwrite(a:buf, testfile)
+ if readfile(reference) == readfile(testfile)
+ call delete(testfile)
+ break
+ endif
+ if i == 100
+ " Leave the test file around for inspection.
+ call assert_report('See dump file difference: call term_dumpdiff("' . testfile . '", "' . reference . '")')
+ break
+ endif
+ sleep 10m
+ let i += 1
+ endwhile
+endfunc
" The Makefile writes it as the first line in the "vimcmd" file.
func GetVimProg()
if !filereadable('vimcmd')
- return ''
+ " Assume the script was sourced instead of running "make".
+ return '../vim'
endif
return readfile('vimcmd')[0]
endfunc
" Get the command to run Vim, with -u NONE and --not-a-term arguments.
" If there is an argument use it instead of "NONE".
-" Returns an empty string on error.
func GetVimCommand(...)
if !filereadable('vimcmd')
- return ''
+ echo 'Cannot read the "vimcmd" file, falling back to ../vim.'
+ let lines = ['../vim']
+ else
+ let lines = readfile('vimcmd')
endif
if a:0 == 0
let name = 'NONE'
" "vimcmd" file, including environment options.
" Other Makefiles just write the executable in the first line, so fall back
" to that if there is no second line.
- let lines = readfile('vimcmd')
let cmd = get(lines, 1, lines[0])
let cmd = substitute(cmd, '-u \f\+', '-u ' . name, '')
if cmd !~ '-u '. name
return cmd
endfunc
+" Get the command to run Vim, with --clean.
+func GetVimCommandClean()
+ let cmd = GetVimCommand()
+ let cmd = substitute(cmd, '-u NONE', '--clean', '')
+ let cmd = substitute(cmd, '--not-a-term', '', '')
+ return cmd
+endfunc
+
" Run Vim, using the "vimcmd" file and "-u NORC".
" "before" is a list of Vim commands to be executed before loading plugins.
" "after" is a list of Vim commands to be executed after loading plugins.
projects / vim / commitdiff