Skip to content

Latest commit

 

History

History
176 lines (107 loc) · 5.52 KB

building-testing.rst

File metadata and controls

176 lines (107 loc) · 5.52 KB
Raw

Building and Testing

To use Highlight.js it is first necessary to build it for the environment where you plan to execute it: the browser, the Node.js server, etc.

TLDR

Often when contributing a pull-request it's sufficient to build and test only the Node.js build. Our CI process will guarantee the browser build tests are all still green if you don't run them during development.

npm run build
npm run test

The browser library must be built and tested separately:

npm run build-browser
npm run test-browser

Building

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

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

  • Build for a browser using only common languages:

    node tools/build.js :common

  • Build for node.js including all available languages:

    node tools/build.js -t node

  • Build two specific languages for debugging, skipping compression in this case:

    node tools/build.js -n python ruby

On some systems the node binary is named nodejs; simply replace node with 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 it visually. You need to build highlight.js with only the language you're working on (without compression, to have readable code in browser error messages) and then use the Developer tool in tools/developer.html to see how it highlights a test snippet in that language.

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

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

Testing is done using Mocha and the files are found in the test/ directory. You can use the node build to run the tests in the command line with npm test after installing the dependencies with npm install.

Note: for Debian-based machine, like Ubuntu, you might need to create an alias or symbolic link for nodejs to node. The reason for this is the dependencies that are requires to test highlight.js has a reference to "node".

Place the snippet you used inside the browser in test/detect/<language>/default.txt, build the package with all the languages for node and run the test suite. If your language breaks auto-detection, it should be fixed by :ref:`improving relevance <relevance>`, which is a black art in 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 isolated cases of various syntactic construct. If your language has 19 different string literals or complicated heuristics for telling division (/) apart from regexes (/ .. /) -- 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 at tools/developer.html. Make sure to explicitly select your language in the drop-down menu, as automatic detection is unlikely to work in this case.

Building and Testing with Docker

If you don't want to install dependencies on your system, you can use the included Dockerfile to build a container that will add the source code and then deploy a web server for you to preview it. Specifically, after you finish with your changes you can build the container from the root of the repository:

docker build -t highlight-js .

And then run the container. You will need to expose port 80 on the host for the web interface, and note that we are running it in detached (-d) mode.

docker run -d --name highlight-js --rm -p 80:80 highlight-js

If your preference is for another port, you can do that too:

docker run -d --name highlight-js --rm -p 80:8080 highlight-js

Or you can skip binding a port if your intention is to interactively shell into the container to use it as a development environment.

docker run -d --name highlight-js --rm highlight-js

Whatever you choose, you can use docker ps to ensure that it's running.

$ docker ps
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                NAMES
0e15a7c99adf        highlight-js        "docker-entrypoint.s…"   8 seconds ago       Up 7 seconds        0.0.0.0:80->80/tcp   highlight-js

Then, open up to http://127.0.0.1/tools/developer.html to see the developer page for preview. When you are done, clean up your container.

docker stop highlight-js

If you want a more advanced testing setup, you can bind the source folder when you run the container.

docker run -d --name highlight-js --volume $PWD/src:/var/www/html/src --rm -p 80:80 highlight-js

Then if you want to make changes, you can do so locally (the folder is bound as a volume), and execute a command to the container to trigger a rebuild:

docker exec highlight-js node tools/build.js :common

And then reload the page to see changes. When you finish, don't forget to remove the container.