编译与测试


在使用 Highlight.js 之前,针对客户端脚本、Node.js 服务端等不同的执行环境,你需要按照相应的方式对其进行编译。

摘要


通常,要往 Github 推送合并请求的话,仅编译和测试 Node.js 就足够了。如果你在开发期间未进行自测,我们的 CI 流程也会确保编译的脚本能通过全部单元测试。

$ npm run build$ npm run test

客户端库必须单独编译和测试:

$ npm run build-browser$ npm run test-browser

编译


需要先了解,编译工具是使用 node.js 以 Ja​​vaScript 语言编写的。然后,在执行脚本之前,请确保已经安装好 node 并且在源码根目录执行了 npm install (安装依赖包)。

编译工具位于 tools/build.js。下面几个是常用示例:

  • 编译一个仅包含常用语言的客户端库:
    $ node tools/build.js :common
  • 编译一个包含所有语言,针对 node.js 的库:
    $ node tools/build.js -t node
  • 编译指定语言并用于调试的库,这种情况不进行压缩:
    $ node tools/build.js -n python ruby

在某些系统上,node 程序又名为 nodejs,如果是这种情况,只需在上面的示例中将 node 替换为 nodejs 即可。

跟惯例一样,可以通过 --help 选项查看完整选项说明。

编译生成的文件会放到 build/ 目录中。

基本测试


通常,调试及测试一项语言时,可以先运行起来直接看页面情况。首先你需要针对你正调试的语言单独编译一个 highlight.js(不压缩并且浏览器上可以输出错误信息),然后使用开发者工具 tools/developer.html 来查看其针对测试代码的高亮处理情况。

测试代码块应该做到简短,并且能描绘出该语言的整体结构。它不应该包含全部的语法结构,甚至可以不用具有实际意义。

当你调试至效果已经达到你的预期后,你需要确保在将你的新语言添加到完整语言包里时,该语言能在自动检测功能中被识别出来。

我们会使用 Mocha 完成测试,相关文件位于 test/ 目录中。在编译之后,通过在命令行执行 npm test 来运行测试用例。(你也可以用一行命令 npm run build_and_test 同时完成编译和测试。)

注意:对于基于 Debian 的系统,例如 Ubuntu,你可能需要为 nodejs 设置一个别名或创建一个目标为 node 的软链接。因为在测试 highlight.js 时,其所必需的依赖项引用的是“node”。

另外,请将你需要在浏览器中展现的代码段放在 test/detect/<language>/default.txt 中,然后使用 node 编译一个包含所有语言的库包,并运行测试用例。如果你调试的语言无法自动检测出来,那么就需要提高相关性来解决这个问题,虽然这个过程本身有点魔幻。如有疑问,欢迎加入我们的研讨群!

语法结构测试


你还可以为指定的语言扩展测试关键字,而且对各种语法结构都能独立测试。比如你的语言有 19 种不同的字符串常量或复杂的句法将斜杠(/)从正则表达式(/ .. /)中区分出来,那这项测试可以有效帮助到你。

每组测试用例会由两个文件组成:

  • test/markup/<language>/<test_name>.txt:测试代码
  • test/markup/<language>/<test_name>.expect.txt:渲染时引用的模板

要生成渲染后的效果,请使用位于 tools/developer.html 的开发者工具。在测试工具的 Language 下拉框中务必勾选你要测试的语言,因为在这种情况下自动检测不太可能起作用。

Docker 编译与测试


如果你不想在系统上安装各依赖项,你可以使用源码包中的 Dockerfile 搭建一个容器,然后在该容器中添加源代码并且部署一个 web 服务以便预览测试结果。具体步骤,就是在你修改好测试用例后,在资源库根目录执行以下命令搭建容器:

$ docker build -t highlight-js .

然后运行容器,请确认已放开主机上的 80 端口,web 界面需要用到。另外,注意我们是在 docker 的 detached mode(-d)下运行的。译者注:即后台运行

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

当然,如果你想换个端口,你可以改成这样:

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

又或者,如果你打算作为开发环境运行交互式容器,则可以不用进行端口绑定:

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

不管哪种方式,你都能够使用 docker ps 命令查看它的运行情况:

$ docker psCONTAINER 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

下一步,打开 http://127.0.0.1/tools/developer.html 查看开发者页面进行预览。完成后,清空容器。

如果你想以更高效的方式的进行测试,你可以在运行容器时绑定源文件夹:

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

然后在你要修改内容时,可以直接修改本地文件(文件夹已作为数据卷挂载),接下来执行 exec 命令触发容器重建:

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

然后重新刷新下页面,便能查看到更改的内容。完成后,不要忘记移除容器。