Nacho Portmanteau Meltdown

    acquit

    1.2.1 • Public • Published

    acquit

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

    Build Status Coverage Status

    Website

    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.

    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.

    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().

    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

    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
    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

    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.

    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.

    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.

    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);

    Install

    npm i acquit

    DownloadsWeekly Downloads

    1,615

    Version

    1.2.1

    License

    Apache 2.0

    Unpacked Size

    38.1 kB

    Total Files

    15

    Last publish

    Collaborators

    • vkarpov15