@kkitahara/esdoc-examples-test-plugin

ESDoc Examples-Test Plugin

This plugin converts the contents of @exmaple blocks into test codes.

Currently, the plugin can generate only the codes that use ES6 modules.

Instllation

npm install esdoc @kkitahara/esdoc-examples-test-plugin

Configuration

The minimum configuration may like:

{
  "source": "./src",
  "destination": "./doc",
  "includes": ["\\.js$|\\.mjs$"],
  "plugins": [
    {
      "name": "@kkitahara/esdoc-examples-test",
      "option": {
        "path": "./examples-test"
      }
    }
  ]
}

Complete list of options:

Name	Default	Description
path	—	Output directory path. (required)
suffix	"-example"	Added to the name of each test code.
mainOutput	"run-test.mjs"	Name of the main test code.
testDriverPath	"@kkitahara/esdoc-examples-test-plugin/src/simple-test-driver.mjs"	Test driver path.
quietPass	false	If true, no log output for passed tests.
testDriverVarName	"testDriver"	Change it if the default conflicts with your example codes.
replace	[]	e.g. [['a', 'b']] will replace all 'a' in the examples with 'b'.

Example

Here, we consider that path is set at ./examples-test, and other options are set at the default values. Let's consider an @example block like:

/**
 * @example
 * let a = 2
 * let b = 3
 *
 * // pass
 * a + b // 5
 *
 * // fail
 * a - b // 5
 *
 * // pass
 * a() // Error
 *
 * // fail
 * a + b // Error
 */

it will be converted into a test code like:

import testDriver from '@kkitahara/esdoc-examples-test-plugin/src/simple-test-driver.mjs'

let a = 2
let b = 3

// pass
testDriver.test(() => { return a + b }, 5, 'my-awesome-example0_0', false)

// fail
testDriver.test(() => { return a - b }, 5, 'my-awesome-example0_1', false)

// pass
testDriver.test(() => { return a() }, Error, 'my-awesome-example0_2', false)

// fail
testDriver.test(() => { return a + b }, Error, 'my-awesome-example0_3', false)

What this plugin does is to detect the lines that match the pattern A // B. If A is not empty, then, the line is converted to a code like testDriver.test(() => { return A }, B, 'my-awesome-example0_0'). Inside the testDriver.test() call, the default test driver will assert the input values by using the default assert module like assert.strictEqual(A, B) if B !== Error and assert.throws(() => { return A }) otherwise.

A test code will be produced per @example block. To run all the tests, do

node --experimental-modules ./examples-test/run-test.mjs

Coverage

The following may be used to get test-coverage report.

npx nyc --extension .mjs -i esm node ./examples-test/run-test.mjs

For this, you need nyc and esm.

LICENSE

© 2019 Koichi Kitahara
Apache 2.0