Add the ability to take screen dumps of the color schemes

[lifepillar]

This commit adds scripts to take screen dumps of the output of the sample*.vim scripts, and verify that such screen dumps match against some reference.

This enables the automatic comparison of the visual appearance of a color scheme before and after some changes are applied. In particular, this may turn useful to avoid unwanted changes when a template is updated in a way that should not affect the visual appearance of a color scheme, as is the case, for instance, for #280.

Usage:

1. take reference screen dumps (based on the color schemes in $VIMRUNTIME) and screen dumps to compare against (taken from ./colors):

:cd colors/tools
:source take_screendumps.vim

Adjust the variables in take_screendumps.vim to take screenshots for different color schemes under various conditions.

2. Compare the screen dumps:

:source verify_screendumps.vim

I'd recommend to run the above in GUI Vim, so that GUI values and all t_Co values can be tested.

Eye candy:

---

The following is kept for reference, but is superseded by the above:

You may source this script to get an idea of how that is meant to work:

vim9script
import './colors/tools/screendump.vim' as screendump

var old    = $VIMRUNTIME .. '/colors/lunaperche.vim'
var new    = './colors/lunaperche.vim'
var script = './colors/tools/sample_spell.vim'
var background = 'dark'

# Take reference screendumps of built-in color scheme
screendump.TakeSelfies(background, {
  colorschemes: [old],
  scripts:      [script],
  outdir:       'dumps-vim',
})

# Take screendumps of repo's color scheme
screendump.TakeSelfies(background, {
  colorschemes: [new],
  scripts:      [script],
  outdir:       'dumps-colorschemes',
})

# Compare the results
for old_dump in glob('dumps-vim/*.dump', 0, 1)
  var new_dump = fnamemodify(old_dump, ":t")

  v:errors = []
  assert_equalfile(old_dump, $'dumps-colorschemes/{new_dump}')

  if !empty(v:errors)
    echomsg $'{new_dump} NOT ok!'
    echomsg v:errors
    term_dumpdiff(old_dump, $'dumps-colorschemes/{new_dump}', {term_rows: 20, term_cols: 75})
  else
    echomsg $'{new_dump} ok!'
  endif
endfor

Edit: added call to term_dumpdiff().

[romainl]

Ho! A visual regression testing framework in vimscript!

Will test this and colortemplate v3 ASAP. Thank you.

[lifepillar]

This did not play well with screen dumps, because the code that starts Vim in a terminal window needs to checks that the screen has been drawn and for that it relies on the presence of the ruler. That's why I have rewritten this as below.

[lifepillar]

One thing that is not clear to me is to what extent the screen dumps taken in different terminals are comparable. It would be great if reference screen dumps could be committed to the repo (as Vim does for vim/src/testdir/dumps), but Vim's tests always work with t_Co=256. I suspect that for lower values the dumps may depend on the environment in which they are taken.

[lifepillar]

Well, Vim doesn't cease to surprise me. I think this is beautiful:

I've added bold to SpellBad in lunaperche and I've run the script above to confirm that the test would fail. Then, I've used term_dumpdiff() to show exactly how the two screenshots differ. Very powerful testing feature.

[lifepillar]

Related to this PR, today I've noticed this script: https://github.com/vim/vim/blob/master/src/testdir/commondumps.vim.

If you decide to merge this PR, then you may also take a look at that. It might be useful for this repository. too.