lib/process.js

  1. // Copyright 2018 Google Inc. All Rights Reserved.
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. //      http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  15. 'use strict';
  17. var util = require('util')
  18. var helpers = require('./handlebar-helpers')
  19. var merge2 = require('./util').merge2;
  21. /**
  22.  * @namespace processing
  23.  */
  25. module.exports = process
  27. /**
  28.  * ProcessedSpec is the fully traversed spec processed for unit test compilation
  29.  * @typedef {object} ProcessedSpec
  30.  * @memberof processing
  31.  * @property {string} host Hostname to be used in the test requests; derived from the options or spec
  32.  * @property {string} scheme HTTP schema to be used in the test requests; derived from the spec
  33.  * @property {string} basePath Base path as defined by the spec
  34.  * @property {string[]} consumes Global content type 'consumes' collection
  35.  * @property {ProcessedPath[]} tests Collection of paths processed for test compilation
  36.  */
  38. /**
  39.  * Processes the given API spec, creating test data artifacts
  40.  * @function process
  41.  * @memberof processing
  42.  * @instance
  43.  * @param {object} api API spec object to be processed
  44.  * @param {object} options options to be used during processing
  45.  * @return {processing.ProcessedSpec}
  46.  */
  47. function process(api, options) {
  48.   var processedSpec = {
  49.     'host': (options.host !== undefined ? options.host : (api.host !== undefined
  50.         ? api.host : 'localhost:5000')),
  51.     'scheme': (options.scheme !== undefined ? options.scheme : (api.schemes
  52.     !== undefined ? api.schemes[0] : 'http')),
  53.     'basePath': (api.basePath !== undefined ? api.basePath : ''),
  54.     'consumes': (api.consumes !== undefined ? api.consumes : []),
  55.     'produces': (api.produces !== undefined ? api.produces : [])
  56.   }
  58.   var processedPaths = processPaths(api, processedSpec, options)
  59.   if (processedPaths.length == 0) {
  60.     console.log('no paths to process in spec')
  61.     return null
  62.   }
  64.   processedSpec.tests = processedPaths
  66.   return processedSpec
  67. }
  69. /**
  70.  * ProcessedPath is the fully traversed path resource ready for unit test compilation
  71.  * @typedef {object} ProcessedPath
  72.  * @memberof processing
  73.  * @property {string} name name to be used in generation of a file name; based on the path
  74.  * @property {string} pathLevelDescription the brief description to use at the top level 'describe' block
  75.  * @property {processing.ProcessedOp[]} operations Collection of operations processed for test compilation
  76.  */
  78. /**
  79.  * Processes the paths defined by the api spec, or indicated by the options
  80.  * @function processPaths
  81.  * @memberof processing
  82.  * @instance
  83.  * @param {object} api parsed OpenAPI spec object
  84.  * @param {object} topLevel global spec properties
  85.  * @param {object} options options to use during processing
  86.  * @return {processing.ProcessedPath[]}
  87.  */
  88. function processPaths(api, topLevel, options) {
  89.   var data = []
  90.   var targetPaths = [];
  92.   if (options.paths !== undefined) {
  93.     options.paths.forEach(function (path, ndx, arr) {
  94.       targetPaths.push(api.getPath(path))
  95.     })
  96.   } else {
  97.     targetPaths = api.getPaths();
  98.   }
  100.   if (options.statusCodes !== undefined) {
  101.     var tempPaths = [];
  102.     options.statusCodes.forEach(function (code, ndx, arr) {
  103.       for (var ndx = 0; ndx < targetPaths.length; ndx++) {
  104.         var opList = targetPaths[ndx].getOperations();
  105.         for (var opNdx = 0; opNdx < opList.length; opNdx++) {
  106.           if (opList[opNdx].getResponse(code)) {
  107.             tempPaths.push(targetPaths[ndx])
  108.             break;
  109.           }
  110.         }
  111.       }
  112.     });
  114.     targetPaths = tempPaths;
  115.   }
  117.   targetPaths.forEach(function (pathObj, ndx, arr) {
  118.     var ops = processOperations(api, pathObj, topLevel, options)
  119.     if (ops.length !== 0) {
  120.       data.push({
  121.         'name': pathObj.path.replace(/\//g, '-').substring(1),
  122.         'pathLevelDescription': 'tests for ' + pathObj.path,
  123.         'operations': ops
  124.       })
  125.     }
  126.   })
  128.   return data
  129. }
  131. /**
  132.  * ProcessedOp is the fully traversed path operation ready for unit test compilation
  133.  * @typedef {object} ProcessedOp
  134.  * @memberof processing
  135.  * @instance
  136.  * @property {string} operationLevelDescription the brief description to use at the inner 'describe' block
  137.  * @property {processing.ProcessedTransaction[]} transactions Collection of transactions processed for test compilation
  138.  */
  140. /**
  141.  * Processes the operations of the given Path object
  142.  * @function processOperations
  143.  * @memberof processing
  144.  * @instance
  145.  * @param {object} api parsed OpenAPI spec object
  146.  * @param {object} parentPath sway Path object being processed
  147.  * @param {object} topLevel global spec properties
  148.  * @param {object} options options to use during processing
  149.  * @return {processing.ProcessedOp[]}
  150.  */
  151. function processOperations(api, parentPath, topLevel, options) {
  152.   var ops = []
  153.   parentPath.getOperations().forEach(function (op, ndx, arr) {
  154.     var transactions = processTransactions(api, op, parentPath, topLevel,
  155.         options)
  156.     if (transactions.length !== 0) {
  157.       ops.push({
  158.         'operationLevelDescription': 'tests for ' + op.method,
  159.         'transactions': transactions
  160.       })
  161.     }
  162.   })
  164.   return ops
  165. }
  167. /**
  168.  * ProcessedTransaction is an HTTP transaction (request/response pair) processed for test compilation
  169.  * @typedef {object} ProcessedTransaction
  170.  * @memberof processing
  171.  * @property {string} testLevelDescription the brief description to use in the test 'it' block
  172.  * @property {string} scheme copied from the globally defined HTTP schema
  173.  * @property {string} host copied from the globally defined hostname or as specified in the options
  174.  * @property {string} path fully qualified path built with the base path; includes path param substitutions
  175.  * @property {op} op the REST operation to use
  176.  * @property {object} body the request body params
  177.  * @property {object} query the request query params
  178.  * @property {object} formData the request form data params
  179.  * @property {ExpectedResponse} expected the expected response to use for test validation
  180.  * @property {boolean} hasSamples flag indicating if the expected response includes sample values
  181.  * @property {string[]} consumes based on globally defined conumes or operation defined types
  182.  */
  184. /**
  185.  * Processes the transactions for a given Path + Operation
  186.  * @function processTransactions
  187.  * @memberof processing
  188.  * @instance
  189.  * @param {object} api parsed OpenAPI spec object
  190.  * @param {object} parentOp parent sway Operation object being processed
  191.  * @param {object} parentPath parent sway Path object being processed
  192.  * @param {object} topLevel global spec properties
  193.  * @param {object} options options to use during processing
  194.  * @return {processing.ProcessedTransaction[]}
  195.  */
  196. function processTransactions(api, parentOp, parentPath, topLevel, options) {
  197.   var transactions = []
  199.   parentOp.getResponses().forEach(function (res, ndx, arr) {
  200.     if (options.statusCodes && options.statusCodes.indexOf(res.statusCode)
  201.         === -1) {
  202.       // skip unwanted status codes
  203.       return;
  204.     }
  206.     var params = processParams(res.statusCode, parentOp, parentPath, options)
  208.     var expected = processResponse(res, parentOp.method, parentPath.path,
  209.         options)
  210.     var hasValue = options.samples
  211.     if (expected.custom) {
  212.       delete expected.custom
  213.       hasValue = true
  214.     }
  216.     transactions.push({
  217.       'testLevelDescription': util.format('should respond %s for "%s"',
  218.           res.statusCode, replaceNewlines(res.description)),
  219.       'scheme': topLevel.scheme,
  220.       'host': topLevel.host,
  221.       'path': (topLevel.basePath + params.path),
  222.       'op': parentOp.method,
  223.       'body': params.body,
  224.       'query': params.query,
  225.       'formData': params.formData,
  226.       'expected': expected,
  227.       'hasValue': hasValue,
  228.       'headers': merge2(params.headers,
  229.           processHeaders(res.statusCode, parentOp, parentPath, topLevel,
  230.               options))
  231.     })
  232.   })
  234.   return transactions
  235. }
  237. /**
  238.  * ProcessedParams is an object representing the processed request parameters for unit test compilation
  239.  * @typedef {object} ProcessedParams
  240.  * @memberof processing
  241.  * @property {string} path processed path with path parameter sample substitutions
  242.  * @property {object} body the request body params
  243.  * @property {object} query the request query params
  244.  * @property {object} formData the request form data params
  245.  */
  247. /**
  248.  * Processes the parameters of a Path + Operation for use in a test
  249.  * @function processParams
  250.  * @memberof processing
  251.  * @instance
  252.  * @param {number} code response status code being processed
  253.  * @param {object} op sway Operation object that's being processed
  254.  * @param {object} path sway Path object that's being process
  255.  * @param {object} options options to use during processing
  256.  * @return {processing.ProcessedParams}
  257.  */
  258. function processParams(code, op, path, options) {
  259.   var opCustomQuery = lookupCustomQueryValue(code, op.method, path.path, options);
  260.   var params = {
  261.     'body': {},
  262.     'query': opCustomQuery || {},
  263.     'formData': {},
  264.     'path': path.path,
  265.     'headers': {}
  266.   }
  268.   op.getParameters().forEach(function (param, ndx, arr) {
  269.     var customValue = lookupCustomValue(param.name, param.in, code, op.method,
  270.       path.path, options)
  271.     // Skip optional parameter with specifically nulled custom value or in-line example
  272.     if ((customValue === null || param.example === null) && (!param.required)) {
  273.       return
  274.     }
  275.     // If multiple examples are present, use the first one
  276.     if (param.examples) {
  277.       param.example = param.examples[Object.keys(param.examples)[0]].value;
  278.     }
  280.     if (param.in === 'body') {
  281.       params.body = customValue !== undefined ? customValue : param.example !== undefined ? param.example : param.getSample()
  282.     } else if (param.in === 'query' && !opCustomQuery) {
  283.       params.query[param.name] = param.example !== undefined ? param.example : param.getSample();
  284.     } else if (param.in === 'formData') {
  285.       try {
  286.         params.formData[param.name] = customValue !== undefined ? customValue
  287.             : param.example !== undefined ? param.example :  param.getSample()
  288.       } catch (e) { // this will be because of formData property of type 'file'
  289.         params.formData[param.name] = '{fileUpload}'
  290.       }
  291.     } else if (param.in === 'path') {
  292.       params.path = pathify(params.path, param, customValue)
  293.     } else if (param.in === 'header') {
  294.       params.headers[param.name] = customValue !== undefined ? customValue
  295.           : param.example !== undefined ? param.example :  param.getSample()
  296.     }
  297.   })
  299.   path.getParameters().forEach(function (param, ndx, arr) {
  300.     var customValue = lookupCustomValue(param.name, param.in, code, op.method,
  301.         path.path, options)
  302.     // Skip optional parameter with specifically nulled custom value or in-line example
  303.     if ((customValue === null || param.example === null) && (!param.required)) {
  304.       return
  305.     }
  306.     params.path = pathify(params.path, param, customValue)
  307.   })
  309.   return params
  310. }
  312. /**
  313.  * resolves any custom values available for the given parameter
  314.  * @function lookupCustomValue
  315.  * @memberof processing
  316.  * @instance
  317.  * @param {string} name parameter name being looked up
  318.  * @param {string} location where the parameter is in the request/response
  319.  * @param {number} code response status code being evaluated
  320.  * @param {string} op the operation method being processed
  321.  * @param {string} path API path being processed
  322.  * @param {object} options for use in looking up the custom value
  323.  * @return {any}
  324.  */
  325. function lookupCustomValue(name, location, code, op, path, options) {
  326.   var levels = [path, op, code]
  327.   var val = undefined;
  329.   if (options.customValues) {
  330.     var curr = options.customValues
  332.     var ndx = 0
  333.     do {
  334.       if (curr[location]) {
  335.         if (curr[location][name] !== undefined) {
  336.           val = curr[location][name]
  337.         }
  338.       }
  340.       curr = curr[levels[ndx]]
  341.     } while (ndx++ < levels.length && curr)
  342.   }
  344.   return val
  345. }
  347. /**
  348.  * resolves any custom query values available for the given operation and path
  349.  * @function lookupCustomQueryValue
  350.  * @memberof processing
  351.  * @instance
  352.  * @param {number} code response status code being evaluated
  353.  * @param {string} op the operation method being processed
  354.  * @param {string} path API path being processed
  355.  * @param {object} options for use in looking up the custom value
  356.  * @return {any}
  357.  */
  358. function lookupCustomQueryValue(code, op, path, options) {
  359.   var levels = [path, op, code];
  360.   var val = undefined;
  362.   if (options.customValues) {
  363.     var curr = options.customValues;
  365.     var ndx = 0
  366.     do {
  367.       if (curr.query !== undefined) {
  368.         val = curr.query
  369.       }
  370.     
  371.       curr = curr[levels[ndx]];
  372.     } while (ndx++ < levels.length && curr)
  373.   }
  375.   return val
  376. }
  378. /**
  379.  * Determines the request headers for a transaction
  380.  * @function processHeaders
  381.  * @memberof processing
  382.  * @instance
  383.  * @param {string} responseCode response code being processed
  384.  * @param {object} op parent operation object
  385.  * @param {object} path parent path object
  386.  * @param {object} top global properties
  387.  * @param {object} options for use in processing headers
  388.  * @return {object}
  389.  */
  390. function processHeaders(responseCode, op, path, top, options) {
  391.   var headers = {};
  392.   var levels = [path.path, op.method, responseCode]
  394.   // handle consumes
  395.   if (options.consumes) { // a specific content-type was targeted
  396.     if (op.definitionFullyResolved.consumes) {
  397.       // this operation overrides global consumes, and does contain the requested content-type
  398.       if (op.definitionFullyResolved.consumes.indexOf(options.consumes) != -1) {
  399.         headers['Content-Type'] = options.consumes;
  400.       } else { // we will just use the first one because this doesn't match
  401.         headers['Content-Type'] = op.definitionFullyResolved.consumes[0];
  402.       }
  404.     } else if (top.consumes.length > 0 && top.consumes.indexOf(options.consumes)
  405.         != -1) {
  406.       headers['Content-Type'] = options.consumes;
  407.     } else if (top.consumes.length === 1) { // unless there is a singular different global consumes, just use that one
  408.       headers['Content-Type'] = top.consumes[0];
  409.     }
  410.   } else if (op.definitionFullyResolved.consumes) { // we will just use the first one if none are specified
  411.     headers['Content-Type'] = op.definitionFullyResolved.consumes[0];
  412.   } else if (top.consumes.length > 0) {
  413.     headers['Content-Type'] = top.consumes[0];
  414.   }
  416.   // handle produces
  417.   if (options.produces) {
  418.     if (op.definitionFullyResolved.produces) {
  419.       if (op.definitionFullyResolved.produces.indexOf(options.produces) != -1) {
  420.         headers['Accept'] = options.produces;
  421.       } else {
  422.         headers['Accept'] = op.definitionFullyResolved.produces[0];
  423.       }
  425.     } else if (top.produces.length > 0 && top.produces.indexOf(options.produces)
  426.         != -1) {
  427.       headers['Accept'] = options.produces;
  428.     } else if (top.produces.length === 1) {
  429.       headers['Accept'] = top.produces[0];
  430.     }
  431.   } else if (op.definitionFullyResolved.produces) {
  432.     headers['Accept'] = op.definitionFullyResolved.produces[0];
  433.   } else if (top.produces.length > 0) {
  434.     headers['Accept'] = top.produces[0];
  435.   }
  437.   // check custom request values for any desired headers; cascading merge
  438.   if (options.customValues) {
  439.     var curr = options.customValues
  441.     var ndx = 0
  442.     do {
  443.       if (curr['header'] !== undefined) {
  444.         headers = merge2(curr['header'], headers)
  445.       }
  447.       curr = curr[levels[ndx]]
  448.     } while (ndx++ < levels.length && curr !== undefined)
  449.   }
  451.   return headers
  452. }
  454. /**
  455.  * ExpectedResponse is the expected response generated based on the API spec
  456.  * @typedef {object} ExpectedResponse
  457.  * @memberof processing
  458.  * @property {number} statusCode expected response status code
  459.  * @property {boolean} custom indicates if the value was a custom injection
  460.  * @property {object} res expected response body, if applicable; can be a generated sample
  461.  */
  463. /**
  464.  * Processes a sway Response for use in a test
  465.  * @function processResponse
  466.  * @memberof processing
  467.  * @instance
  468.  * @param {object} res sway Response object being processed
  469.  * @param {string} op the operation method being processed
  470.  * @param {string} path API path being processed
  471.  * @param {object} options options to use during processing
  472.  * @return {processing.ExpectedResponse}
  473.  */
  474. function processResponse(res, op, path, options) {
  475.   var expected = {
  476.     'statusCode': res.statusCode,
  477.     'custom': false
  478.   }
  480.   if (options.customValues
  481.       && options.customValues[path]
  482.       && options.customValues[path][op]
  483.       && options.customValues[path][op][res.statusCode]
  484.       && options.customValues[path][op][res.statusCode].response) {
  486.     expected['res'] = options.customValues[path][op][res.statusCode].response
  487.     expected.custom = true;
  489.     return expected
  490.   }
  492.   var res = options.samples ? res.getSample()
  493.       : res.definitionFullyResolved.schema
  494.   if (res !== undefined) {
  495.     expected['res'] = res
  496.   }
  498.   return expected
  499. }
  501. /**
  502.  * replaces the path paremeter in the given URL path with a sample value
  503.  * @function pathify
  504.  * @memberof processing
  505.  * @instance
  506.  * @param {string} path URL path to be pathified
  507.  * @param {object} param sway Parameter object to use in pathify
  508.  * @param {(string|number)} value a custom value to use in the pathify
  509.  * @return {string}
  510.  */
  511. function pathify(path, param, value) {
  512.   var regex = new RegExp('(\/.*){' + param.name + '}(\/.*)*', 'g')
  513.   var sample = value !== undefined ? value : param.example !== undefined ? param.example : param.getSample()
  514.   if (isNumberType(param.definition.type)) {
  515.     // prevent negative sample values for numbers
  516.     while (sample < 0) {
  517.       sample = param.getSample()
  518.     }
  519.   }
  521.   return path.replace(regex, '$1' + sample + '$2').replace(/ /g, '');
  522. }
  524. /**
  525.  * evaluates if the given type is an OpenAPI number type or not
  526.  * @function isNumberType
  527.  * @memberof processing
  528.  * @instance
  529.  * @param {string} type type to be evaluated
  530.  * @return {boolean}
  531.  */
  532. function isNumberType(type) {
  533.   return (type === 'integer' || type === 'float' || type === 'long' || type
  534.       === 'double')
  535. }
  537. /**
  538.  * Determines the proper type for the Query parameter
  539.  * @function determineQueryType
  540.  * @memberof processing
  541.  * @instance
  542.  * @param {object} param sway Parameter object to investigate
  543.  * @return {string}
  544.  */
  545. function determineQueryType(param) {
  546.   var val = param.name; // default to the name if all else fails
  548.   if (param.definitionFullyResolved.type === 'array') {
  549.     val = param.definitionFullyResolved.items.type + '[]'
  550.   } else {
  551.     val = param.definitionFullyResolved.type
  552.   }
  553.   return '{' + val + '}'
  554. }
  556. /**
  557.  * Used to replace newlines with a space in each response.description
  558.  * @function replaceNewlines
  559.  * @memberof processing
  560.  * @instance
  561.  * @param {string} str string to replace newlines with spaces
  562.  * @return {string}
  563.  */
  564. function replaceNewlines(str) {
  565.   return str.replace(/\r?\n|\r/g, " ")
  566. }