node package manager
Don’t reinvent the wheel. Reuse code within your team. Create a free org »

jsdoctap

jsdoctap

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

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

screenshot


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.

API

I strongly recommend just using this as a command-line test runner. However, it does have a basic Node API. Example:

const t = require('jsdoctap')
const { readdirSync } = require('fs')
const files = readdirSync('./src')
files.forEach((f) => { t('./src' + f) })

Roadmap

  • 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