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.

Test	Arguments	Expected	Results
	John	Hello, John!	true

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.

Test	Arguments	Expected	Results
JohnTest	John	Hello, John!	true

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.

Type	Operator
String	:string
Integer	:int
Float	:number
Boolean	:bool

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.

Type	Operator
null	:null
NaN	:NaN
undefined	:undefined