Running tests for specific languages

To run the tests only for one language, you can use the language parameter: npm test -- --language=markup.

You can even specify multiple languages: npm test -- --language=markup --language=css.

Language directories

All tests are sorted into directories in the tests/languages directory. Each directory name encodes, which language you are currently testing.

All language names must match the names from the definition in components.js.

Example 1: testing a language in isolation (default use case)

Just put your test file into the directory of the language you want to test.

So, if you want to test CSS, put your test file in /tests/languages/css to test CSS only. If you create a test case in this directory, the test runner will ensure that the css language definition including all required language definitions are correctly loaded.

Example 2: testing language injection

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.

You need to define multiple languages by separating them using a + sign: markup+php.

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).

By default the last language is the main language: php+markup will have markup as main language. This is equal to putting your code in the following code block:

...
<pre><code class="language-markup">
	<!-- your code here -->
</code><pre>
...

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: php!+markup. This will use php 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.)

Note: by loading multiple languages you can do integration tests (ensure that loading two or more languages together won't break anything).

Creating your test case file

At first you need to create a new file in the language directory, you want to test.

Use a proper name for your test case. Please use one case of the following conventions:

• issue{issueid}: reference a github issue id (example: issue588.test).
• {featurename}_feature: group all tests to one feature in one file (example: string_interpolation_feature.test).
• {language}_inclusion: test inclusion of one language into the other (example: markup!+css/css_inclusion.test will test CSS inclusion into markup).

You can use all conventions as a prefix, so string_interpolation_feature_inline.test is possible. 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.

Writing your test

The structure of a test case file is as follows:

... language snippet...
----
... the simplified token stream you expect ...

Your file is built up of two or three sections, separated by ten or more dashes -, starting at the begin of the line:

1. Your language snippet. The code you want to compile using Prism. (required)
2. The simplified token stream you expect. Needs to be valid JSON. (required)
3. A comment explaining the test case. (optional)

The easiest way would be to look at an existing test file:

var a = 5;

----------------------------------------------------

[
	["keyword", "var"],
	" a ",
	["operator", "="],
	["number", "5"],
	["punctuation", ";"]
]

----------------------------------------------------

This is a comment explaining this test case.

Explaining the simplified token stream

While compiling, Prism transforms your source code into a token stream. This is basically a tree of nested tokens (or arrays, or strings).

As these trees are hard to write by hand, the test runner uses a simplified version of it.

It uses the following rules:

• Token objects are transformed into an array: [token.type, token.content] (whereas token.content can be a nested structure).
• All strings that are either empty or only contain whitespace, are removed from the token stream.
• All empty structures are removed.

For further information: reading the tests of the test runner (tests/testrunner-tests.js) will help you understand the transformation.