Mercurial > vim

annotate runtime/syntax/testdir/README.txt @ 32670:695b50472e85

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix line endings issue
author Christian Brabandt <cb@256bit.org>
date Mon, 26 Jun 2023 13:13:12 +0200
parents 448aef880252
children 2bedc8f066ff
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
32670
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1 Tests for syntax highlighting plugins
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
2 =====================================
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
3
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
4 Summary: Files in the "input" directory are edited by Vim with syntax
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
5 highlighting enabled. Screendumps are generated and compared with the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
6 expected screendumps in the "dumps" directory. This will uncover any
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
7 character attributes that differ.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
8
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
9 Without any further setup a screendump is made at the top of the file (using
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
10 _00.dump) and another one at the end of the file (using _99.dump). The dumps
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
11 are normally 20 screen lines tall.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
12
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
13 When the screendumps are OK an empty "done/{name}" file is created. This
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
14 avoids running the test again until "make clean" is used. Thus you can run
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
15 "make test", see one test fail, try to fix the problem, then run "make test"
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
16 again to only repeat the failing test.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
17
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
18 When a screendump differs it is stored in the "failed" directory. This allows
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
19 for comparing it with the expected screendump, using a command like:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
20
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
21 let fname = '{name}_99.dump'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
22 call term_dumpdiff('failed/' .. fname, 'dumps/' .. fname)
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
23
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
24
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
25 Creating a syntax plugin test
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
26 -----------------------------
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
27
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
28 Create a source file in the language you want to test in the "input"
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
29 directory. Make sure to include some interesting constructs with complicated
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
30 highlighting.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
31
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
32 Use the filetype name as the base and a file name extension matching the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
33 filetype. Let's use Java as an example. The file would then be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
34 "input/java.java".
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
35
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
36 If there is no further setup required, you can now run the tests:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
37 make test
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
38
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
39 The first time this will fail with an error for a missing screendump. The
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
40 newly created screendumps will be "failed/java_00.dump",
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
41 "failed/java_01.dump", etc. You can inspect each with:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
42
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
43 call term_dumpload('failed/java_00.dump')
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
44 call term_dumpload('failed/java_01.dump')
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
45 ...
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
46 call term_dumpload('failed/java_99.dump')
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
47
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
48 If they look OK, move them to the "dumps" directory:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
49
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
50 :!mv failed/java_00.dump dumps
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
51 :!mv failed/java_01.dump dumps
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
52 ...
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
53 :!mv failed/java_99.dump dumps
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
54
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
55 If you now run the test again, it will succeed.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
56
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
57
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
58 Adjusting a syntax plugin test
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
59 ------------------------------
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
60
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
61 If you make changes to the syntax plugin, you should add code to the input
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
62 file to see the effect of these changes. So that the effect of the changes
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
63 are covered by the test. You can follow these steps:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
64
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
65 1. Edit the syntax plugin somewhere in your personal setup. Use a file
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
66 somewhere to try out the changes.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
67 2. Go to the directory where you have the Vim code checked out and replace the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
68 syntax plugin. Run the tests: "make test". Usually the tests will still
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
69 pass, but if you fixed syntax highlighting that was already visible in the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
70 input file, carefully check that the changes in the screendump are
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
71 intentional:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
72 let fname = '{name}_99.dump'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
73 call term_dumpdiff('failed/' .. fname, 'dumps/' .. fname)
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
74 Fix the syntax plugin until the result is good.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
75 2. Edit the input file for your language to add the items you have improved.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
76 (TODO: how to add another screendump?).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
77 Run the tests and you should get failures. Like with the previous step,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
78 carefully check that the new screendumps in the "failed" directory are
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
79 good. Update the syntax plugin and the input file until the highlighting
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
80 is good and you can see the effect of the syntax plugin improvements. Then
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
81 move the screendumps from the "failed" to the "dumps" directory. Now "make
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
82 test" should succeed.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
83 3. Prepare a pull request with the modified files:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
84 - syntax plugin: syntax/{name}.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
85 - test input file: syntax/testdir/input/{name}.{ext}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
86 - test dump files: syntax/testdir/dumps/{name}_99.dump
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
87
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
88 As an extra check you can temporarily put back the old syntax plugin and
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
89 verify that the tests fail. Then you know your changes are covered by the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
90 test.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
91
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
92
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
93
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
94 TODO: run test for one specific filetype
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
95
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
96 TODO: testing with various option values
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
97 TODO: test syncing by jumping around