Source: plugin/assertivedocs/assertivedocs.js

  1. /**
  2.  * @file assertivedocs
  3.  * @fileoverview Defines the @assert tag and the supporting logic
  4.  */
  6. const fs = require('fs');
  7. const path = require('path');
  8. const logger = require('jsdoc/util/logger');
  9. const env = require('jsdoc/env');
  11. const cwd = process.cwd();
  13. const destination = env.opts.destination || '';
  15. /**
  16.  * Current working file.
  17.  * @memberof assertivedocs
  18.  */
  19. let file;
  21. /**
  22.  * @namespace typeMappings
  23.  */
  24. const typeMappings = {
  25.   /**
  26.    * Converts the argument to a string. Arguments are a string by default.
  27.    * @param {String} arg - Argument from the unit test specification
  28.    * @returns {String}
  29.    */
  30.   string: function(arg) { return arg },
  31.   /**
  32.    * Converts the argument to an integer.
  33.    * @param {String} arg - Argument from the unit test specification
  34.    * @returns {Number}
  35.    */
  36.   int: function(arg) { return parseInt(arg) },
  37.   /**
  38.    * Converts the argument to a number.
  39.    * @param {String} arg Argument from the unit test specification
  40.    * @returns {Number}
  41.    */
  42.   number: function(arg) { return parseFloat(arg) },
  43.   /**
  44.    * Converts the argument to a boolean value.
  45.    * @param {String} arg - Argument from the unit test specification
  46.    * @returns {Boolean}
  47.    */
  48.   bool: function(arg) { return ['true', 'false', '1', '0'].includes(arg) },
  49.   /**
  50.    * Converts the argument to an array.
  51.    * @param {String} arg - Argument from the unit test specification
  52.    * @returns {Array}
  53.    */
  54.   array: function(arg) { return JSON.parse(arg.replaceAll(';', ',')) },
  55.   /**
  56.    * Returns undefined.
  57.    * @param {String} arg - Argument from the unit test specification
  58.    * @returns {undefined}
  59.    */
  60.   undefined: function(arg) { return undefined },
  61.   /**
  62.    * Returns null.
  63.    * @param {String} arg - Argument from the unit test specification
  64.    * @returns {null}
  65.    */
  66.   null: function(arg) { return null },
  67.   /**
  68.    * Returns NaN.
  69.    * @param {String} arg - Argument from the unit test specification
  70.    * @returns {NaN}
  71.    */
  72.   NaN: function(arg) { return NaN },
  73.   /**
  74.    * Attempts to convert the argument to the given type
  75.    * @param {String} arg - Argument to convert
  76.    * @param {String} type - The type to convert to
  77.    * @returns {String|Number|Boolean|any[]|undefined|null|NaN}
  78.    */
  79.   convert: function(arg, type) {
  80.     try {
  81.       switch (type) {
  82.         case 'string':
  83.           return typeMappings.string(arg); 
  84.         case 'int':
  85.           return typeMappings.int(arg);
  86.         case 'number':
  87.           return typeMappings.number(arg);
  88.         case 'bool':
  89.           return typeMappings.bool(arg);
  90.         case 'array':
  91.           return typeMappings.array(arg);
  92.         case 'undefined':
  93.           return typeMappings.undefined(arg);
  94.         case 'null':
  95.           return typeMappings.null(arg);
  96.         case 'NaN':
  97.           return typeMappings.NaN(arg);
  98.         case 'object':
  99.           return typeMappings.object ? typeMappings.object(arg) : {};
  100.         default:
  101.           return arg;
  102.       };
  103.     } catch (error) {
  104.       logger.error(error);
  105.       return arg;
  106.     }
  107.   },
  108.   /**
  109.    * Checks that a custom object map has been provided and attempts to add it to 
  110.    * typeMappings as a mixin.
  111.    */
  112.   modify: function() {
  113.     if (env.opts.assertivedocs.customObjects) {
  114.       const { typeMappingsMixin } = require(path.join(cwd, env.opts.assertivedocs.customObjects));
  115.       Object.assign(typeMappings, typeMappingsMixin);
  116.     }
  117.   }
  118. }
  120. // Attempt to load mixin
  121. typeMappings.modify();
  124. /**
  125.  * An object for asserting the truth of the 
  126.  * @namespace Assertion
  127.  * @param {Function} func - The function to test
  128.  * @param {any[]} args - List of arguments to pass to the function
  129.  * @param {any} expected - The expected result of the function
  130.  * @example
  131.  * function foo(bar) {
  132.  *  return bar;
  133.  * }
  134.  * 
  135.  * const test = Assertion(foo, ['hello'], 'hello');
  136.  * // Returns 'true'
  137.  * console.log(test.assert());
  138.  * 
  139.  * @assert {Assertion} Test1 - console.log,["hello"]:json=>:undefined
  140.  */
  141. function Assertion(func, args, expected) {
  142.   /**
  143.    * Function to be assessed.
  144.    * @memberof Assertion
  145.    */
  146.   this.func = func ? func : () => {};
  147.   /**
  148.    * The arguments to be passed to the function.
  149.    * @memberof Assertion
  150.    */
  151.   this.args = args;
  152.   /**
  153.    * The expected result when the function is passed the arguments.
  154.    * @memberof Assertion
  155.    */
  156.   this.expected = expected;
  158.   /**
  159.    * Asserts that the stored function produces
  160.    * the expected result when passed the given
  161.    * arguments.
  162.    * @memberof Assertion
  163.    * @returns {String}
  164.    */
  165.   this.assert = function() {
  166.     try {
  167.       const outcome = this.func(...this.args);
  168.       return outcome === this.expected;
  169.     } catch (error) {
  170.       return error;
  171.     }
  172.   }
  173. }
  175. /**
  176.  * The function to call when an assert tag is found.
  177.  * @namespace assertivedocs
  178.  * @param {jsdoc.Doclet} doclet - The doclet that the tag is in
  179.  * @param {jsdoc.Tag} tag - The found tag
  180.  */
  181. function assertOnTagged(doclet, tag) {
  182.   // Split tag value description on =>
  183.   const parts = tag.value.description.split('=>');
  185.   // Get all the arguments to parse
  186.   let args = parts[0].split(',');
  188.   // Get the type converted arguments
  189.   args = args.map((arg) => {
  190.     arg = arg.split(':');
  191.     return typeMappings.convert(arg[0], arg[1]);
  192.   });
  194.   // Get the expected result
  195.   let expected = parts[1].split(':');
  196.   expected = expected.length > 1 ? typeMappings.convert(expected[0], expected[1]) : expected[0];
  198.   // Create new Assertion
  199.   const test = new Assertion(file[doclet.meta.code.name], args, expected);
  201.   // Create formatted unit test result for docs
  202.   const result = {
  203.     name: tag.value.name ? tag.value.name : "",
  204.     arguments: args.map((arg) => typeof arg === 'object' ? JSON.stringify(arg) : arg ).join(', '),
  205.     expected: expected,
  206.     result: test.assert().toString(),
  207.   }
  209.   // Assign the result to the doclet
  210.   if (!doclet.tests) doclet.tests = [];
  211.   doclet.tests.push(result);
  212. }
  214. const defineTags = function(dictionary) {
  215.   // Definition of @assert
  216.   dictionary.defineTag('assert', {
  217.     mustHaveValue: true,
  218.     canHaveType: true,
  219.     canHaveName: true,
  220.     onTagged: assertOnTagged,
  221.   });
  222. }
  224. const handlers = {
  225.   fileBegin: function(e) {
  226.     file = require(e.filename);
  227.   },
  228.   processingComplete: function(e) {
  229.     let out;
  230.     fs.readFile(path.join(__dirname, '/assertivehead.html'), 'utf8', (_, data) => {
  231.       out = data;
  232.       e.doclets.forEach(doclet => {
  233.         if (doclet.tests) {
  234.           out += `
  235.   <h3>${doclet.meta.filename}:${doclet.meta.code.name}</h3>
  236.   <table class="params">
  237.     <tr>
  238.       <thead>
  239.         <th>Test</th>
  240.         <th>Arguments</th>
  241.         <th>Expected</th>
  242.         <th class="last">Results</th>
  243.       </thead>
  244.     </tr>
  245.     <tbody>
  246.           `;
  247.           doclet.tests.forEach((test) => {
  248.             out += `
  249.       <tr>
  250.         <td>${test.name}</td>
  251.         <td>${test.arguments}</td>
  252.         <td>${test.expected}</td>
  253.         <td class="last">${test.result}</td>
  254.       </tr>
  255.             `;
  256.           });
  257.           out += `
  258.     </tbody>
  259.   </table>
  260. </body>
  261. </html>
  262.           `;
  263.         }
  264.       });
  266.       if (!fs.existsSync(path.join(cwd, destination, 'unit-tests/'))) {
  267.         fs.mkdir(path.join(cwd, destination, 'unit-tests/'), (err) => {
  268.           logger.error(err);
  269.           fs.writeFile(path.join(cwd, destination, 'unit-tests/index.html'), out, {
  270.             encoding: 'utf-8',
  271.           }, (error) => {
  272.             if (error) logger.error(error);
  273.           });
  274.         });
  275.       } else {
  276.         fs.writeFile(path.join(cwd, destination, 'unit-tests/index.html'), out, {
  277.           encoding: 'utf-8',
  278.         }, (error) => {
  279.           if (error) logger.error(error);
  280.         });
  281.       }
  282.     });
  283.   }
  284. }
  286. module.exports = {
  287.   // Plugin definition
  288.   defineTags,
  289.   handlers,
  291.   // Plugin documnentation; allows assertions to be run on this file
  292.   Assertion,
  293.   assertOnTagged,
  294. }