# jsdoctest

> Run jsdoc examples as doctests

Latest version **1.7.1** (published 2017-08-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install jsdoctest
pnpm add jsdoctest
yarn add jsdoctest
bun add jsdoctest
```

Provides the command `jsdoctest`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.7.1 |
| Published | 2017-08-14 |
| First published | 2014-11-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 97 |
| Author | Pedro Tacla Yamada |
| Maintainers | yamadapc |
| Keywords | test, jsdoc, doctests, testing, workflow |

## Links

- npm: https://www.npmjs.com/package/jsdoctest
- Repository: https://github.com/yamadapc/jsdoctest
- Issues: https://github.com/yamadapc/jsdoctest/issues
- npm.io page: https://npm.io/package/jsdoctest

## Dependencies (6)

- [dox](https://npm.io/package/dox.md) ^0.9.0
- [lodash](https://npm.io/package/lodash.md) ^4.0.1
- [should](https://npm.io/package/should.md) ^11.2.1
- [commander](https://npm.io/package/commander.md) ^2.8.1
- [uglify-js](https://npm.io/package/uglify-js.md) ^3.0.13
- [js-beautify](https://npm.io/package/js-beautify.md) ^1.5.4

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads
- [aws-elasticsearch-connector](https://npm.io/package/aws-elasticsearch-connector.md) — 37.4K weekly downloads

## Recent versions

- 1.7.1 (latest) — 2017-08-14
- 1.7.0 — 2016-07-28
- 1.6.3 — 2016-06-06
- 1.6.2 — 2016-06-06
- 1.6.1 — 2016-06-01
- 1.6.0 — 2015-07-24
- 1.5.0 — 2015-07-03
- 1.4.1 — 2015-03-11
- 1.4.0 — 2015-03-11
- 1.3.3 — 2015-03-11
- 1.3.2 — 2015-03-11
- 1.3.1 — 2014-12-17
- 1.3.0 — 2014-11-26
- 1.2.3 — 2014-11-26
- 1.2.2 — 2014-11-22
- … 6 more at https://npm.io/package/jsdoctest/versions

## README

<p align="center">
  <img alt="jsdoctest" src="/jsdoctest.png" />
</p>

[![Build Status](https://travis-ci.org/yamadapc/jsdoctest.svg)](https://travis-ci.org/yamadapc/jsdoctest)
[![Coverage Status](https://coveralls.io/repos/yamadapc/jsdoctest/badge.png)](https://coveralls.io/r/yamadapc/jsdoctest)
[![Stories in Ready](https://badge.waffle.io/yamadapc/jsdoctest.svg?label=ready&title=Ready)](http://waffle.io/yamadapc/jsdoctest)
[![Dependency Status](https://david-dm.org/yamadapc/jsdoctest.svg)](https://david-dm.org/yamadapc/jsdoctest)
[![devDependency Status](https://david-dm.org/yamadapc/jsdoctest/dev-status.svg)](https://david-dm.org/yamadapc/jsdoctest#info=devDependencies)
[![npm downloads](http://img.shields.io/npm/dm/jsdoctest.svg)](https://www.npmjs.org/package/jsdoctest)
[![npm version](http://img.shields.io/npm/v/jsdoctest.svg)](https://www.npmjs.org/package/jsdoctest)
[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/yamadapc/jsdoctest?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

- - -

**jsdoctest** parses [`jsdoc`](http://usejsdoc.org/) `@example` tags from
annotated functions and runs them as if they were doctests.

Inspired by the [doctest](https://docs.python.org/2/library/doctest.html) python
library, as well as its [doctestjs](http://doctestjs.org) javascript
implementation.

## Demo

![demo](/jsdoctest-demo.gif)

## Set-up
Here's a two line set-up you can use:
```bash
$ npm i -g jsdoctest && jsdoctest --init
Adding `jsdoctest` script to your package.json...
Installing `mocha` and `jsdoctest` with npm:
# ... npm doing some work...
You can now run doctests with `npm run jsdoctest` or `npm test`
```
This will add sensible defaults to your `package.json` which you can then edit.

## Test-case Format
Examples need to be valid javascript, followed by a comment with the string
` => ` prefixing the results:
```javascript
/**
 * @example
 *   returns10()
 *   // => 10
 *   returns20()
 *   // => 20
 */
```

It doesn't matter if the comment is on the same line or the next one, so the
following is also valid:
```javascript
/**
 * @example
 *   returns10() // => 10
 *   returns20()
 *   // => 20
 */
```

**Async test cases** are supported prefixing the expected results with the
` async => ` string and pretending to have the `cb` callback function.
```javascript
/**
 * @example
 *   takesCallbackAndYields10('here', cb)
 *   // async => 10
 *   takesCallbackAndYields20('here', cb)
 *   // async => 30
 */
```

**Promises** are also supported, just add the same `// async =>` prefix and be
sure not to use a variable named `cb` on your text expression.
```javascript
/**
 * @example
 *   returnsPromiseThatYields10('here')
 *   // async => 10
 */
```

## Examples
The [examples](/examples) directory has a couple of examples, which may be
useful. Better documentation will be added if the project raises in complexity.

## Usage
The recommended way of using jsdoctest is to use
[`mocha`](https://github.com/mochajs/mocha). That is made possible with:
```bash
npm i mocha jsdoctest
mocha --require jsdoctest <module-name>
```

There's also a rudimentary command-line interface, which can be ran with:
```bash
npm i jsdoctest
jsdoctest <module-name>
```

## Disabling
To disable running jsdoctests, while still requiring it with `mocha` (I don't
know why, but you may) you can set the `JSDOCTEST_DISABLE` environment variable
to anything (`JSDOCTEST_DISABLE=true mocha --require...`).

## License
This code is licensed under the MIT license for Pedro Tacla Yamada. For more
information, please refer to the [LICENSE](/LICENSE) file.

## Donations
Would you like to buy me a beer? Send bitcoin to 3JjxJydvoJjTrhLL86LGMc8cNB16pTAF3y

---
_Source: https://npm.io/package/jsdoctest · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
