# acquit

> Parse BDD tests (Mocha, Jasmine) to generate documentation

Latest version **1.4.0** (published 2025-05-06) · Apache-2.0 license · 0 weekly downloads

## Install

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

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

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

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2025-05-06 |
| First published | 2014-11-19 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=12.22.0 |
| Dependencies | 1 |
| Unpacked size | 39.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 102 |
| Author | Valeri Karpov |
| Maintainers | vkarpov15 |
| Keywords | documentation, docs, bdd, tests, mocha |

## Links

- npm: https://www.npmjs.com/package/acquit
- Repository: https://github.com/vkarpov15/acquit
- Homepage: http://acquit.mongoosejs.io
- Issues: https://github.com/vkarpov15/acquit/issues
- npm.io page: https://npm.io/package/acquit

## Dependencies (1)

- [espree](https://npm.io/package/espree.md) ~9.6.1

## 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
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 1.4.0 (latest) — 2025-05-06
- 1.3.0 — 2023-02-20
- 1.2.1 — 2020-09-25
- 1.2.0 — 2020-09-25
- 1.1.0 — 2020-08-18
- 1.0.5 — 2019-06-15
- 1.0.4 — 2019-06-15
- 1.0.3 — 2018-12-21
- 1.0.2 — 2018-12-17
- 1.0.0 — 2018-05-31
- 0.6.3 — 2018-05-04
- 0.6.2 — 2018-03-31
- 0.6.1 — 2018-03-09
- 0.6.0 — 2018-01-16
- 0.5.1 — 2018-01-02
- … 9 more at https://npm.io/package/acquit/versions

## README

# acquit

Parse BDD-style tests (Mocha, Jasmine) to generate documentation

[![Build Status](https://travis-ci.org/vkarpov15/acquit.svg?branch=master)](https://travis-ci.org/vkarpov15/acquit)
[![Coverage Status](https://coveralls.io/repos/vkarpov15/acquit/badge.svg?branch=master&service=github)](https://coveralls.io/github/vkarpov15/acquit?branch=master)

## Website

[`acquit.mongoosejs.io`](http://acquit.mongoosejs.io)

# `acquit.parse()`

## It can parse Mocha tests into `blocks`


Acquit's `parse()` function takes in mocha tests as a string, and outputs
a list of "blocks", which are either `describe` or `it` calls. A `describe`
call contains a list of "blocks", whereas an `it` call contains the actual
`code` in order to provide an effective, well-tested example.

```javascript
var contents = `
  /**
   * A Model is a convenience wrapper around objects stored in a
   * collection
   */
  describe('Model', function() {
    /**
     * Model **should** be able to save
     **/
     it('can save', function() {
       assert.ok(1);
     });

     it('can save with a parameter', function() {
     });
  });
`;

var ret = acquit.parse(contents);

// One top-level block: describe('Model')
assert.equal(1, ret.length);
assert.equal('describe', ret[0].type);
assert.equal(1, ret[0].comments.length);
assert.ok(ret[0].comments[0].indexOf('Model') != -1);

// Top-level block contains the `it('can save')` block, which contains
// the code
assert.equal(2, ret[0].blocks.length);
assert.equal('it', ret[0].blocks[0].type);
assert.equal(1, ret[0].blocks[0].comments.length);
assert.ok(ret[0].blocks[0].code.indexOf('assert.ok(1)') !== -1);
assert.equal('can save', ret[0].blocks[0].contents);

assert.equal('it', ret[0].blocks[1].type);
assert.equal('can save with a parameter', ret[0].blocks[1].contents);
assert.equal(0, ret[0].blocks[1].comments.length);
```

## It can call user function on `code` block and save return value


Acquit can also take a callback as second parameter. This callback gets
executed on every block and can transform the block however you want.


```javascript
var contents = `
  describe('ES6', function() {
    // ES6 has a yield keyword
    it(\'should be able to yield\', function() {
     // some code
   });
  });
`;

var cb = function(block) {
  block.code = 'return value from callback';
};

var ret = acquit.parse(contents, cb);

assert.equal('return value from callback', ret[0].blocks[0].code);
```

## It can define transforms


Want to chain multiple callbacks together and/or develop re-usable
plugins? `acquit.transform()` allows you to add transformations that
are executed each time you call `.parse()`.

Transform functions are executed in order **before** the callback
function passed to `.parse()`.


```javascript
var contents = `
  describe('ES6', function() {
    // ES6 has a yield keyword
    it('should be able to yield', function() {
      // some code
    });
  });
`;

var cb = function(block) {
  block.code = 'my transformed code';
};

acquit.transform(cb);

var ret = acquit.parse(contents);

assert.equal('my transformed code', ret[0].blocks[0].code);
acquit.removeAllTransforms();
```

## It can parse the ES6 `yield` keyword


Acquit can also parse ES6 code


```javascript
var contents = `
  describe('ES6', function() {
    // ES6 has a yield keyword
    it('should be able to yield', function() {
      co(function*() {
        yield 1;
      })();
    });
  });
`;

var ret = acquit.parse(contents);

assert.equal(1, ret.length);
assert.equal('describe', ret[0].type);
assert.equal(0, ret[0].comments.length);
assert.equal(1, ret[0].blocks.length);
assert.equal('it', ret[0].blocks[0].type);
assert.equal(1, ret[0].blocks[0].comments.length);
assert.ok(ret[0].blocks[0].code);
```

## It can parse Mocha's `context()` and `specify()`


Acquit can parse Mocha alias:
- `context` = `describe`
- `specify` = `it`


```javascript
var contents = `
  context('Mocha aliases', function() {
    specify('should be parsed', function() {
      assert.equal(1, 1);
    });
  });
`;

var ret = acquit.parse(contents);

assert.equal(1, ret.length);
assert.equal('describe', ret[0].type);
assert.equal(0, ret[0].comments.length);
assert.equal(1, ret[0].blocks.length);
assert.equal('it', ret[0].blocks[0].type);
assert.equal(0, ret[0].blocks[0].comments.length);
assert.ok(ret[0].blocks[0].code);
```

# `acquit.trimEachLine()`

## It strips out whitespace and asterisks in multiline comments


`trimEachLine()` is a helper function for trimming whitespace and asterisks
from JSdoc-style comments

```javascript
var str = `  * This comment looks like a
  * parsed JSdoc-style comment`;

assert.equal(acquit.trimEachLine(str), 'This comment looks like a\n' +
  'parsed JSdoc-style comment');
```

## It strips out whitespace and asterisks in multiline comments


You don't have to use JSdoc-style comments: `trimEachLine()` also trims
leading and trailing whitespace.

```javascript
var str = `This comment looks like a
    * parsed JSdoc-style comment`;

assert.equal(acquit.trimEachLine(str), 'This comment looks like a\n' +
  'parsed JSdoc-style comment');
```

# Output processors

## It can transform acquit output


You can use the `.output()` function to attach output processors,
which transform the output from `acquit.parse()` before you get it.


```javascript
var contents = `
  describe("My feature", function() {
    it("works", function() {
      // some code
    });
  });
`;

acquit.output(function(res) {
  return `
    # ${res[0].contents}

    ## ${res[0].blocks[0].contents}
  `;
});

var res = acquit.parse(contents);

assert.equal(res.trim(), `
    # My feature

    ## works
`.trim());
acquit.removeAllTransforms();
```

# `acquit()` constructor

## It creates a new instance with its own set of transforms


You can also use acquit as a constructor, in case you need
multiple sets of transforms.


```javascript
acquit.transform(function(block) {});
assert.equal(acquit.getTransforms().length, 1);

var parser = acquit();
assert.equal(parser.getTransforms().length, 1);

parser.transform(function(block) {});
assert.equal(parser.getTransforms().length, 2);

parser.removeAllTransforms();
assert.equal(parser.getTransforms().length, 0);
assert.equal(acquit.getTransforms().length, 1);

assert.equal(parser.parse('describe("test", function() {});').length,
  1);

parser.output(function(res) {
  return 'myFakeOutput';
});

assert.equal(parser.parse('describe("test", function() {});'),
  'myFakeOutput');

parser.removeAllOutputProcessors();

assert.equal(parser.parse('describe("test", function() {});').length,
  1);
```

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