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