runtime(syntax-tests): Support embeddable Vim configuration for syntax tests

Currently, the very same syntax file for which a test can
be written is the only place where global variables can be
defined so that the file parts guarded with such variables
can be read during screen dump generation.  This approach
would lead to littering the syntax file with test-related
queries.

Instead, we could borrow the idea of comment-based mechanism
for test setup from the indent test runner.  With it, the
first 20 lines of each test file would be ALWAYS scanned in
search of the TEST_SETUP markers and, when found, the part
between the end of the marker and the end of the line would
be treated as a Vim Ex command.

Note that with these changes, runtime/defaults.vim is no
longer sourced for screen dump generation; however, some of
its functionality is reintroduced.

Further details can be found in the discussion thread at
https://github.com/vim/vim/discussions/14117.

related: #14215

Signed-off-by: Aliaksei Budavei <0x000c70@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

runtime/syntax/testdir/README.txt

@@ -26,14 +26,30 @@ Creating a syntax plugin test
 -----------------------------
 
 Create a source file in the language you want to test in the "input"
-directory.  Make sure to include some interesting constructs with complicated
-highlighting.
-
-Use the filetype name as the base and a file name extension matching the
-filetype.  Let's use Java as an example.  The file would then be
+directory.  Use the filetype name as the base and a file name extension
+matching the filetype.  Let's use Java as an example. The file would then be
 "input/java.java".
 
+Make sure to include some interesting constructs with plenty of complicated
+highlighting.  Optionally, pre-configure the testing environment by including
+setup commands at the top of the input file. The format for these lines is:
+
+	TEST_SETUP {command}
+
+where {command} is any valid Ex command, which extends to the end of the line.
+The first 20 lines of the input file are ALWAYS scanned for setup commands and
+these will be executed before the syntax highlighting is enabled.  Typically,
+these lines would be included as comments so as not to introduce any syntax
+errors in the input file but this is not required.
+
+Continuing the Java example:
+
+	// TEST_SETUP let g:java_space_errors = 1
+	// TEST_SETUP let g:java_minlines = 5
+	class Test { }
+
 If there is no further setup required, you can now run the tests:
+
 	make test
 
 The first time this will fail with an error for a missing screendump.  The
@@ -69,8 +85,10 @@ are covered by the test.  You can follow these steps:
    pass, but if you fixed syntax highlighting that was already visible in the
    input file, carefully check that the changes in the screendump are
    intentional:
+
 	let fname = '{name}_99.dump'
 	call term_dumpdiff('failed/' .. fname, 'dumps/' .. fname)
+
    Fix the syntax plugin until the result is good.
 2. Edit the input file for your language to add the items you have improved.
    (TODO: how to add another screendump?).
@@ -91,7 +109,6 @@ test.
 
 
 
-TODO: run test for one specific filetype
 
-TODO: testing with various option values
+TODO: run test for one specific filetype
 TODO: test syncing by jumping around

runtime/syntax/testdir/runtest.vim

@@ -114,8 +114,6 @@ func RunTest()
       call delete('done/' .. root)
 
       let lines =<< trim END
-	syntax on
-
 	" extra info for shell variables
 	func ShellInfo()
 	  let msg = ''
@@ -145,6 +143,25 @@ func RunTest()
 	  redraw!
 	endfunc
 
+	func SetUpVim()
+	  call cursor(1, 1)
+	  " Defend against rogue TEST_SETUP commands.
+	  for _ in range(20)
+	    let lnum = search('\<TEST_SETUP\>', 'eW', 20)
+	    if lnum < 1
+	      break
+	    endif
+	    exe substitute(getline(lnum), '.*TEST_SETUP', '', '')
+	  endfor
+	  call cursor(1, 1)
+	  " BEGIN [runtime/defaults.vim]
+	  set display=truncate ruler scrolloff=5
+	  " Provide pre-TEST_SETUP support for input/*.c.
+	  let g:c_comment_strings = 1
+	  syntax on
+	  " END [runtime/defaults.vim]
+	  redraw!
+	endfunc
       END
       call writefile(lines, 'Xtestscript')
 
@@ -157,9 +174,12 @@ func RunTest()
       " for the terminal window.
       redraw
 
-      let buf = RunVimInTerminal('-S Xtestscript', {})
+      " Let "Xtestscript#SetUpVim()" turn the syntax on.
+      let buf = RunVimInTerminal('-Nu NONE -S Xtestscript', {})
       " edit the file only after catching the SwapExists event
       call term_sendkeys(buf, ":edit " .. fname .. "\<CR>")
+      " set up the testing environment
+      call term_sendkeys(buf, ":call SetUpVim()\<CR>")
       " load filetype specific settings
       call term_sendkeys(buf, ":call LoadFiletype('" .. filetype .. "')\<CR>")