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


acquit.parse()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 actualcode 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);
`
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);
`
Want to chain multiple callbacks together and/or develop re-usable
plugins? acquit.transform() allows you to add transformations that.parse()
are executed each time you call .
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();
`
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);
`
and specify()
Acquit can parse Mocha alias:
- context = describespecify
- = 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);
`
trimEachLine() is a helper function for trimming whitespace and asterisks
from JSdoc-style comments
`javascript * This comment looks like a
var str =
* parsed JSdoc-style comment;
assert.equal(acquit.trimEachLine(str), 'This comment looks like a\n' +
'parsed JSdoc-style comment');
`
You don't have to use JSdoc-style comments: trimEachLine() also trims
leading and trailing whitespace.
`javascriptThis comment looks like a
var str =
* parsed JSdoc-style comment;
assert.equal(acquit.trimEachLine(str), 'This comment looks like a\n' +
'parsed JSdoc-style comment');
`
You can use the .output() function to attach output processors,acquit.parse()
which transform the output from 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();
constructor
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);
``