markunit v1.0.7
Markunit
A simple assertion library for unit testing Markdown.
Wait a second...
Unit testing Markdown? Yeah, it might sound odd. But Markdown is code, and it can have bugs just like anything else. Maybe there are lingering references to an API call you’ve removed. Or you want to avoid double-level lists for stylistic reasons. Or perhaps contributors keep misspelling your library's name. Wouldn’t it be nice to catch those things automatically? Exactly. Markunit provides assert methods for analyzing your Markdown content and the HTML it creates, which can be run inside your favorite test runner and continuous integration system.
Installation
Get the package from npm:
$ npm install markunit -D
Then require the package and load your Markdown document:
var markunit = require("markunit");
var markdown =
"# Test document\nThis is _example_ Markdown content for `markunit.js` documentation.";
var doc = markunit(markdown);
Renditions
There are five different renditions of the original Markdown content that can be analyzed: source
, rendered
, copy
, code
, and markup
. Each of them possesses a .has()
and a .no()
method.
Source
Check for the presence or absence of patterns in the source Markdown:
// Will look for text matches in "# Test document\nThis is _example_ Markdown content for `markunit.js` documentation."
doc.source.has("# Test document"); // pass
doc.source.no("Doesn't exist"); // pass
Rendered
Check for the presence or absence of patterns in the rendered HTML:
// Will look for text matches in "<h1>Test document</h1><p>This is <em>example</em> Markdown content for <code>markunit.js</code>" documentation.</p>
doc.rendered.has("<h1>Test document</h1>"); // pass
doc.rendered.no("<h1>Not the title</h1>"); // pass
Copy
Check for the presence or absence of patterns in contents of the doc, excluding code
elements:
// Will look for text matches in "Test document This is example Markdown content for" and "documentation."
doc.copy.has("This is example Markdown"); // pass
doc.copy.no("markunit.js"); // pass
Code
Check for the presence or absence of patterns in contents of only the code
elements:
// Will look for text matches in "markunit.js"
doc.code.has("markunit.js"); // pass
doc.code.no("mark-unit.js"); // pass
Markup
Check for the presence or absence of jquery
-style selectors:
// Will look for structural matches in "<h1></h1><p><em></em><code></code></p>"
doc.markup.has("p"); // pass
doc.markup.no("li li"); // pass
Patterns
For the source
, rendered
, copy
, and code
renditions, the pattern to match can be a string, a regular expression, or an array of either. For the markup
rendition, the pattern can be a string or an array of strings, where each string represents a jquery
-style selector. A single match from an array is sufficient for the .has()
method to pass or the .no()
method to fail.
doc.source.has("test"); // pass
doc.source.has(/t.?*t/); // pass
doc.source.has(["test", /Not present/]); // pass
Ignoring
A pattern can be excluded from review using .ignore()
, which will completely remove matches from the input Markdown. The pattern to ignore can be a string, a regular expression, or an array of either. Subsequent calls will overwrite the pattern, and passing null
will clear the pattern.
doc.ignore("content");
doc.source.no("content"); // pass
Example Usage
The below demonstrates a simple setup and test suite for the typical repository README, using a framework like Mocha.
// test/test.js
var markunit = require("markunit");
var fs = require("fs");
var input = fs.readFileSync("../README.md", "utf8");
var readme = markunit(input);
readme.ignore("It’s spelled MyLibrary, not my-library.");
describe("README", function() {
it("should have a title", function() {
readme.markup.has("h1");
});
it("should not contain double-indented lists", function() {
readme.markup.no("li li");
});
it("should not have any raw HTML in the source", function() {
readme.source.no(/<.*?>.*?<\/.*?>/);
});
it("should have a link to npm", function() {
readme.rendered.has(/<a.*?href="https:\/\/npmjs\.com/);
});
it("should not spell the library name with a hyphen", function() {
readme.copy.no("my-library");
});
it("should not have any curly quotes in code snippets", function() {
readme.code.no(["“", "”"]);
});
it("should not reference old API calls", function() {
readme.code.no([
"deprecatedCall1(",
"deprecatedCall2(",
"deprecatedCall3("
]);
});
it("should contain installation instructions", function() {
readme.code.has("npm install");
});
});