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
|
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:
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 <http://mochajs.org/>`_ and the
files are found in the ``test/`` directory. You can use the node build to
run the tests from the command line with ``npm test`` after building_. (Using
``npm run build_and_test`` you can build and then test with one command.)
**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.
|
