mltap
mltap
is a unit testing framework for MarkLogic. It includes a test harness for running tests in Server-Side JavaScript in MarkLogic, an assertion library, and a Node.js-based command-line wrapper.
mltap
(partially) implements the tape API, a popular Node.js test framework. This allows you to run the same tests in Node.js, modern browsers, and MarkLogic with no modifications to the test code.
mltap
produces standard TAP output so you can use it in other tools that can consume TAP, for example, for continuous integration, IDE integration, or reporting.
Getting Started
First, install the libraries and the command-line interface,
git clone https://github.com/jmakeig/mltap.git && cd mltapnpm installnpm run setupnpm testnpm install --global . # optional
This installs the the command-line interface on your $PATH
and configures MarkLogic with the necessary library modules and security settings. You’ll only need to do this once.
Then from within the project you’d like to test,
mltap test/*.test.sjs
Behind the scenes, mltap
will run each of local the *.test.sjs
modules against the target MarkLogic JavaScript environemnt. mltap
collates the results and produces a summary of the passed and failed tests in TAP format to stdout. You can use any TAP consumer to further process the output. For example, tap-diff pretty prints TAP on the command-line.
npm install -g tap-diffmltap test/*.test.sjs | tap-diff
Example Test and TAP Output
'use strict'; const test = ? : ; ; ; ; {try return xdmp && cts; catche return false;}
TAP version 13
# Throws an error after some assertions pass
ok 1 true is true
not ok 2 Error: Test error
---
operator: error
actual: undefined
at: Test.impl (/test/test.test.sjs:9:9)
stack: |-
Error: Test error
at Test.impl (/test/test.test.sjs:9:9)
at Test.run (/mltap/test.js:76:12)
at Object.run (/mltap/test.js:49:28)
...
# This test has a fulfilled plan
ok 3 asdf is length 4
ok 4 asdfs is length 5
# This test has an unfulfilled plan
ok 5 asdf is length 4
ok 6 asdfs is length 5
not ok 7 Planned for 25 assertions, got 2
---
operator: ok
expected: 25
actual: 2
at: Test.run (/mltap/test.js:81:10)
...
1..7
Development Set-Up
git clone https://github.com/jmakeig/mltap.git && cd mltapnpm install# Copies the MarkLogic library modules to $ML_HOME/Modules/mltap # You’ll need to run this anytime the MarkLogic modules change # This should theoretically work with a modules database in the future npm config # Requires MarkLogic running (defaults to admin:admin@localhost:8000) npm test
For VSCode
Install Node.js TypeScript types to enable code completion,
npm install -g typingstypings install dt~node --global
Set up a task to run tests via npm. The most important part is that the command return the TAP output unaldulterated, i.e. not reformatted or rewritten, as most console pretty printers will do. Anything that you pipe the TAP output into, such as tap-notify, must be a transparent pass-through. The problemMatcher
below relies on the specific error reporting format of mltap
, which isn’s wholly standardized in TAP.
// See https://go.microsoft.com/fwlink/?LinkId=733558 // for the documentation about the tasks.json format "version": "0.1.0" "command": "npm" "isShellCommand": true "showOutput": "silent" "suppressTaskName": true "tasks": "taskName": "test" "args": "run" "test" "problemMatcher": "owner": "javascript" "fileLocation": "relative" "${workspaceRoot}" "pattern": "regexp": "^\\s+at: (.+) \\((.+):(\\d+):(\\d+)\\)" "file": 2 "line": 3 "column": 4 "message": 1