Building and testing

To actually run highlight.js it is necessary to build it for the environmentwhere you’re going to run it: a browser, the node.js server, etc.

Building

The build tool is written in JavaScript using node.js. Before running thescript, make sure to have node installed and run npm install to get thedependencies.

The tool is located in tools/build.js. A few useful examples:

  • Build for a browser using only common languages:
  1. node tools/build.js :common
  • Build for node.js including all available languages:
  1. node tools/build.js -t node
  • Build two specific languages for debugging, skipping compression in this case:
  1. node tools/build.js -n python ruby

On some systems the node binary is named nodejs; simply replace nodewith nodejs in the examples above if that is the case.

The full option reference is available with the usual —help option.

The build result will be in the build/ directory.

Basic testing

The usual approach to debugging and testing a language is first doing itvisually. You need to build highlight.js with only the language you’re workingon (without compression, to have readable code in browser error messages) andthen use the Developer tool in tools/developer.html to see how it highlightsa test snippet in that language.

A test snippet should be short and give the idea of the overall look of thelanguage. It shouldn’t include every possible syntactic element and shouldn’teven make practical sense.

After you satisfied with the result you need to make sure that languagedetection still works with your language definition included in the whole suite.

Testing is done using Mocha and thefiles are found in the test/ directory. You can use the node build torun the tests in the command line with npm test after installing thedependencies with npm install.

Note: for Debian-based machine, like Ubuntu, you might need to create analias or symbolic link for nodejs to node. The reason for this is thedependencies that are requires to test highlight.js has a reference to“node”.

Place the snippet you used inside the browser intest/detect/<language>/default.txt, build the package with all the languagesfor node and run the test suite. If your language breaks auto-detection, itshould be fixed by improving relevance, which is a black artin and of itself. When in doubt, please refer to the discussion group!

Testing markup

You can also provide additional markup tests for the language to test isolatedcases of various syntactic construct. If your language has 19 different stringliterals or complicated heuristics for telling division (/) apart fromregexes (/ .. /) – this is the place.

A test case consists of two files:

  • test/markup/<language>/<test_name>.txt: test code
  • test/markup/<language>/<test_name>.expect.txt: reference rendering
    To generate reference rendering use the Developer tool located attools/developer.html. Make sure to explicitly select your language in thedrop-down menu, as automatic detection is unlikely to work in this case.