Package Exports

@kkitahara/esdoc-examples-test-plugin

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@kkitahara/esdoc-examples-test-plugin) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 A !== 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.

@kkitahara/esdoc-examples-test-plugin