assertivedocs v0.4.0

assertivedocs

JSDocs unit testing plugin

Run npm i assertivedocs to install.

Check out the docs for more information.

Getting Started

1. Install assertive docs by running the below command in your terminal open in your project directory.

npm i assertivedocs

2. Add assertivedocs/assertivedocs to plugins in your JSDoc config file. If you haven't made a config file for JSDoc, make one and make JSDoc use it when running.

3. In your JSDoc config file, set opts.destination to "./docs". This will output your generated documentation to this folder, with the unit test results in a "unit-tests" folder. Note: As of 0.3.0 you can call your destination folder anything you would like.

4. Finally, set template.default.layoutFile to "assertivedocs/layout.tmpl". This will ensure there is a link to your unit test results in your documentation's navigation menu.

Basic Assertion

The most basic form of unit test is an assertion: @assert - <list,of,arguments>=>expected_result.

/**
 * Greets a person by name.
 * @param {String} name - Name of the person to greet
 * @returns {String}
 * 
 * @assert - John=>Hello, John!
 */
function greet(name) {
  return `Hello, ${name}!`
}

module.exports = {
  greet,
}

The above code will output a table similar to the below when JSDoc is run.

Naming tests

Including a single-word name - such as JohnTest - between @assert and the '-' will give the test a name. Changing the above example to @assert JohnTest - John=>Hello, John! will output a table similar to the one below.

Type Operators

By default, assertivedocs assumes all arguments and expected values are a string. The below table shows the different type operators that modify the arguments provided for the test. See the docs for how to handle arrays.

Null, NaN, and Undefined

assertivedocs provides operators for handling these keywords. These can be provided on their own instead of providing an argument or expected value. See the docs for examples.