jsdoctap

Test runner for doctests using JSDoc examples and node-tap.

Based on the hard work of @yamadapc and this project.

• Examples
• Roadmap and known bugs
• Changes

Installation

npm i -D jsdoctap

Usage

jsdoctap some-file.js

I recommend adding it to your npm scripts. Example:

{
  "scripts": {
    "test": "jsdoctap src/*.js"
  }
}

Options

jsdoctap has one option: -i (or --ignore) Example: jsdoctap -i src/*.test.js -i src/*.config.js src/*.js.

Format

Tests must be under an @example in a valid JSDoc comment. The return value to be tested against must come after a line comment with an arrow (Clojure REPL style):

/**
 * Identity
 * @example
 * id(1) // => 1
 */

Line breaks between the call and the comment are fine:

/**
 * Identity
 * @example
 *   id(1)
 *   // => 1
 */

Line breaks in function calls currently do not work:

/**
 * This will break!
 * @example
 * id(
 *   1
 * ) // => 1
 */

Source and examples that need to be Babelified work just fine, as long as you have Babel configured and modules installed.

Roadmap

• Handle expecting errors
• Fix multi-line function calls
• Fix dependencies that need to be Babelified
• Add ability to have custom test case name
• Clean up comment-parser and getModuleName (in tap)
• More tests and examples

License

MIT

• 0.5.7 - 2018-08-03
  • Fix test cases that use double slashes in URLs. Thanks @adw0rd!
• 0.3.0 - 2017-08-19
  • Add Babel support. jsdoctap will now use your local Babel config and modules. I really hope this didn't break something else.

• 0.2.0 - 2017-08-15

  • Fix helpers/other declarations/whatever in examples. Important this partially kinda breaks one possible formatting. No single expression in an @example can span multiple lines (which was broken before, and then fixed for a minute, but is now broken again). So:

    /**
     * THIS WORKS
     * @example
     * const arr = [ 1, 2, 3 ]
     * const plusTen = (a) => a + 10
     * map(plusTen, arr)
     *   // => [ 11, 12, 13 ]
     */
    
    /**
     * BUT THIS DOES NOT
     * @example
     * const arr = [ 1, 2, 3 ]
     * const plusTen = (a) =>
     *   a + 10
     * map(
     *   plusTen,
     *   arr
     * ) // => [ 11, 12, 13 ]
     */

• 0.1.5 - 2017-08-13
  • Now with less noisy output, colors in the help, and a demo gif!
• 0.1.0 - 2017-08-13
  • First real release. It works!