/
test-suite.html
212 lines (151 loc) · 10.8 KB
/
test-suite.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<link rel="icon" href="assets/favicon.png" />
<title>Running the test suite ▲ Prism</title>
<link rel="stylesheet" href="assets/style.css" />
<link rel="stylesheet" href="themes/prism.css" data-noprefix />
<script src="assets/vendor/prefixfree.min.js"></script>
<script>var _gaq = [['_setAccount', 'UA-33746269-1'], ['_trackPageview']];</script>
<script src="https://www.google-analytics.com/ga.js" async></script>
</head>
<body class="language-javascript">
<header>
<div class="intro" data-src="assets/templates/header-main.html" data-type="text/html"></div>
<h2>Running the test suite</h2>
<p>Prism has a test suite, that ensures that the correct tokens are matched.</p>
</header>
<section id="running-the-test-suite">
<h1>Running the test suite</h1>
<p>Running the test suite is simple: just call <code class="language-bash">npm test</code>.</p>
<p>All test files are run in isolation. A new prism instance is created for each test case. This will slow the test runner a bit down, but we can be sure that nothing leaks into the next test case.</p>
<h2 id="running-tests-for-specific-languages">Running tests for specific languages</h2>
<p>To run the tests only for one language, you can use the <code>language</code> parameter:</p>
<pre><code class="language-bash">npm run test:languages -- --language=markup</code></pre>
<p>You can even specify multiple languages:</p>
<pre><code class="language-bash">npm run test:languages -- --language=markup --language=css</code></pre>
</section>
<section id="writing-tests">
<h1>Writing tests</h1>
<p>Thank you for writing tests! Tests are awesome! They ensure, that we can improve the codebase without breaking anything. Also, this way, we can ensure that upgrading Prism is as painless as possible for you.</p>
<p>You can add new tests by creating a new test case file (with the <code>.test</code> file extension) in the tests directory which is located at <code>/tests/languages/${language}</code>.</p>
<h2 id="writing-tests-directories">Language directories</h2>
<p>All tests are sorted into directories in the <code>tests/languages</code> directory. Each directory name encodes, which language you are currently testing.</p>
<p><strong>All language names must match the names from the definition in <code>components.json</code>.</strong></p>
<h3>Example 1: testing a language in isolation (default use case)</h3>
<p>Just put your test file into the directory of the language you want to test.</p>
<p>So, if you want to test CSS, put your test file in <code>/tests/languages/css</code> to test CSS only. If you create a test case in this directory, the test runner will ensure that the <code>css</code> language definition including all required language definitions are correctly loaded.</p>
<h3>Example 2: testing language injection</h3>
<p>If you want to test language injection, you typically need to load two or more languages where one language is the “main” language that is being tested, with all other languages being injected into it.</p>
<p>You need to define multiple languages by separating them using a <code>+</code> sign: <code>markup+php</code>.</p>
<p>The languages are loaded in order, so first markup (+ dependencies) is loaded, then php (+ dependencies). The test loader ensures that no language is loaded more than once (for example if two languages have the same dependencies).</p>
<p>By default the last language is the main language: <code>php+markup</code> will have <code>markup</code> as main language. This is equal to putting your code in the following code block:</p>
<pre><code class="language-markup">...
<pre><code class="language-markup">
<!-- your code here -->
</code><pre>
...</code></pre>
<p>If you need to load the languages in a given order, but you don't want to use the last language as main language, you can mark the main language with an exclamation mark: <code>php!+markup</code>. This will use <code>php</code> as main language. (You can only define one main language. The test runner will fail all tests in directories with more than one main language.)</p>
<p><em>Note: by loading multiple languages you can do integration tests (ensure that loading two or more languages together won't break anything).</em></p>
<h2 id="writing-tests-creating-your-test-case-file">Creating your test case file</h2>
<p>At first you need to create a new file in the language directory, you want to test.</p>
<p><strong>Use a proper name for your test case.</strong> Please use one case of the following conventions:</p>
<ul>
<li><code>issue{issueid}</code>: reference a github issue id (example: <code>issue588.test</code>).</li>
<li><code>{featurename}_feature</code>: group all tests to one feature in one file (example: <code>string_interpolation_feature.test</code>).</li>
<li><code>{language}_inclusion</code>: test inclusion of one language into the other (example: <code>markup!+css/css_inclusion.test</code> will test CSS inclusion into markup).</li>
</ul>
<p>You can use all conventions as a prefix, so <code>string_interpolation_feature_inline.test</code> is possible. <strong>But please take a minute or two to think of a proper name of your test case file. You are writing code not only for the computers, but also for your fellow developers.</strong></p>
<h2 id="writing-tests-writing-your-test">Writing your test</h2>
<p>A test case file is built up of two or three sections separated by ten or more dashes <code>-</code> starting at the begin of the line. The sections are the following:</p>
<ol>
<li>Your language snippet. The code you want to tokenize using Prism. (<strong>required</strong>)</li>
<li>
The simplified token stream you expect. Needs to be valid JSON. (<em>optional</em>) <br>
The test runner will automatically insert this if not present. <strong>Carefully check</strong> that the inserted token stream is what you expected. <br>
If the test case fails because the JSON is present but incorrect, then you can use the <a href="#writing-tests-update"><code>--update</code> flag</a> to overwrite it.
</li>
<li>A brief comment explaining the test case. (<em>optional</em>)</li>
</ol>
<p>Here is an example:</p>
<pre><code>var a = 5;
----------------------------------------------------
[
["keyword", "var"],
" a ",
["operator", "="],
["number", "5"],
["punctuation", ";"]
]
----------------------------------------------------
This is a comment explaining this test case.</code></pre>
<h2 id="writing-tests-the-easy-way">The easy way to write tests</h2>
<p>The easy way to create one or multiple new test case(s) is this:</p>
<ol>
<li>Create a new test case file <code class="language-none">tests/languages/{language}/{test-case}.test</code>.</li>
<li>Insert the code you want to test (and nothing more).</li>
<li>Repeat the first two steps for as many test cases as you want.</li>
<li>Run <code class="language-bash">npm run test:languages</code>.</li>
<li>Done.</li>
</ol>
<p>Updating existing test case files is easy too!</p>
<ol>
<li>Run <code class="language-bash">npm run test:languages -- --update</code>.</li>
<li>Done.</li>
</ol>
<p>This works by making the test runner insert the actual token stream of you test code as the expected token stream. <strong>Carefully check that the inserted token stream is actually what you expect or else the test is meaningless!</strong></p>
<h2 id="writing-tests-update">Updating tests</h2>
<p>When creating and changing languages, their test files have to be updated to properly test the language. The rather tedious task of updating test files can be automated using the following command:</p>
<pre><code class="language-bash">npm run test:languages -- --update</code></pre>
<p>Updates (overwrites) the expected token stream of all failing test files. The language tests are guaranteed to pass after running this command.</p>
<p><em>Keep in mind:</em> This command makes it easy to create/update test files but this doesn't mean that the tests will be correct. <strong>Always carefully check the inserted/updated token streams!</strong></p>
<h2 id="writing-tests-explaining-the-simplified-token-stream">Explaining the simplified token stream</h2>
<p>While highlighting, Prism transforms your source code into a token stream. This is basically a tree of nested tokens (or arrays, or strings).</p>
<p>As these trees are hard to write by hand, the test runner uses a simplified version of it.</p>
<p>It uses the following rules:</p>
<ul>
<li><code>Token</code> objects are transformed into an array: <code>[token.type, token.content]</code> (whereas <code>token.content</code> can be a nested structure).</li>
<li>All strings that are either empty or only contain whitespace, are removed from the token stream.</li>
<li>All empty structures are removed.</li>
</ul>
<p>The simplified token stream does not contain the aliases of a token.</p>
<p>For further information: reading the tests of the test runner (<code>tests/testrunner-tests.js</code>) will help you understand the transformation.</p>
</section>
<section id="writing-specific-tests">
<h1>Writing specific tests</h1>
<p>Sometimes, using the token stream tests is not powerful enough. By creating a test file with the file extension <code>.html.test</code> instead of <code>.test</code>, you can make Prism highlight arbitrary pieces of code and check their HTML results.</p>
<p>The language is determined by the folder containing the test file lies, as explained in the previous section.</p>
<p>The structure of your test file will look like this, for example:</p>
<pre><code class="language-html">&amp;
&#x41;
----------------------------------------------------
<span class="token entity named-entity" title="&amp;">&amp;amp;</span>
<span class="token entity" title="&#x41;">&amp;#x41;</span>
----------------------------------------------------
This is a comment explaining this test case.
</code></pre>
</section>
<section id="test-runner-tests">
<h1>Test runner tests</h1>
<p>The test runner itself is tested in a separate test case. You can find all “test core” related tests in <code>tests/testrunner-tests.js</code>.</p>
<p>You shouldn't need to touch this file ever, except you modify the test runner code.</p>
</section>
<section id="internal-structure">
<h1>Internal structure</h1>
<p>The global test flow is at follows:</p>
<ol>
<li>Run all internal tests (test the test runner).</li>
<li>Find all language tests.</li>
<li>Run all language tests individually.</li>
<li>Report the results.</li>
</ol>
</section>
<footer data-src="assets/templates/footer.html" data-type="text/html"></footer>
<script src="assets/vendor/utopia.js"></script>
<script src="prism.js"></script>
<script src="components/prism-bash.js"></script>
<script src="components.js"></script>
<script src="assets/code.js"></script>
</body>
</html>