https://github.com/pmsipilot/esdoc-test-plugin
Documentation test plugin for ESDoc
https://github.com/pmsipilot/esdoc-test-plugin
esdoc jsdoc
Last synced: 3 months ago
JSON representation
Documentation test plugin for ESDoc
- Host: GitHub
- URL: https://github.com/pmsipilot/esdoc-test-plugin
- Owner: pmsipilot
- Created: 2017-04-10T11:56:28.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2017-04-11T08:36:48.000Z (about 8 years ago)
- Last Synced: 2025-01-14T02:12:45.173Z (5 months ago)
- Topics: esdoc, jsdoc
- Language: JavaScript
- Size: 9.77 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# ESDoc Documentation Test Plugin
This plugin will convert any Javascript snippet inside descriptions into executable test.
Writing a good documentation often requires to write good examples. Keeping these examples in sync with the actual code
is hard when you don't check them. With this plugin, ESDoc will turn any snippet into executable tests and run them each
time you build the doc.
## Installation
```
npm install --save esdoc esdoc-test-plugin
```
## Configuration
To enable the plugin, update tour `.esdoc.json` configuration file:
```json
{
"source": "./src",
"destination": "./public",
"plugin": [
{
"name": "./esdoc-test-plugin",
"option": {
"path": "./src"
}
}
]
}
```
Here is the complete list of configuration options:
| Name | Type | Default | Annotation | Description |
|-------------------|-----------|---------|------------|-----------------------------------------------------------------------------------------------------------------|
| `path` | `String` | | ✓ | The base path to the source directory. Might be the same as the `source` directive of ESDoc. |
| `exitOnFailure` | `Boolean` | `false` | | Should ESDoc exit immediately if a test failed. |
| `exitWithFailure` | `Boolean` | `true` | | Should ESDoc exit with an error status if a test failed. |
| `assert` | `String` | `node` | ✓ | Which assertion framework to use (one of: `chai`, `chai-expect`, `chai-assert`, `expect`, `expect.js`, `node`). |
## Usage
Given you have the following Javascript code and its documentation:
~~~js
/**
* @param {Number} x
* @param {Number} y
*
* @return {Number}
*/
const add = (x, y) => x + y;
~~~
You can add some test in the description:
~~~js
/**
* This function adds two numbers:
*
* ```js
* const add = require('./add');
*
* assert.equal(add(1, 2), 3);
* ```
*
* @param {Number} x
* @param {Number} y
*
* @return {Number}
*/
const add = (x, y) => x + y;
~~~
This will generate a single test for the `add` function.
_Note that the `require` is relative to the `plugin.option.path` configuration directive (the actual file is located
at `./src/add.js`)._
You can add more test by writing more snippets:
~~~js
/**
* This function adds two numbers:
*
* ```js
* const add = require('./add');
*
* assert.equal(add(1, 2), 3);
* ```
*
* ```js
* const add = require('./add');
*
* assert.equal(add(-1, -2), -3);
* ```
*
* @param {Number} x
* @param {Number} y
*
* @return {Number}
*/
const add = (x, y) => x + y;
~~~
You can also use annotation to configure some tests:
~~~js
/**
* This function adds two numbers:
*
* ```js#assert=chai
* const add = require('./add');
*
* add(1, 2).should.equal(3);
* ```
*
* @param {Number} x
* @param {Number} y
*
* @return {Number}
*/
const add = (x, y) => x + y;
~~~
Annotation are written next to the language with the following format: `js[[#name[=value]]...]`. If the annotation has no
value, its default value will be `true`.
The `path` and `assert` configuration directives can be overridden at the test level using annotations. You can also use
the `skip` annotation to mark a test as skipped.