lib/compile.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 handlebars = require('handlebars');
  18. var helpers = require('./handlebar-helpers')
  19. var fs = require('fs')
  20. var path = require('path')
  22. var DefaultTemplateDirectory = path.join(__dirname, '..', 'templates');
  23. var TopLevelTemplateName = 'topLevel.handlebars';
  24. var PathTemplateName = 'pathLevel.handlebars';
  25. var OperationTemplateName = 'operationLevel.handlebars';
  26. var TransactionTemplateName = 'transactionLevel.handlebars';
  28. /**
  29.  * @namespace compilation
  30.  */
  32. module.exports = compile
  34. handlebars.registerHelper('notEmptyObject', helpers.notEmptyObject)
  35. handlebars.registerHelper('json', helpers.json)
  36. handlebars.registerHelper('isNotDefaultStatusCode',
  37.     helpers.isNotDefaultStatusCode)
  39. /**
  40.  * GeneratedTest is the set of results from procressing a spec & compiling the test code
  41.  * @typedef {object} GeneratedTest
  42.  * @memberof compilation
  43.  * @property {string} filename A file name based off of the path being tested
  44.  * @property {string} contents Generated test file contents
  45.  */
  47. /**
  48.  * Compiles the templated test files with the given processed API spec data
  49.  * @function compile
  50.  * @memberof compilation
  51.  * @instance
  52.  * @param {processing.ProcessedSpec} processed the API spec data processed for test generation
  53.  * @param {object} options for use in compilation of the tests
  54.  * @return {compilation.GeneratedTest[]}
  55.  */
  56. function compile(processed, options) {
  57.   var tests = []
  59.   processed.tests.forEach(function (processedPath, ndx, arr) {
  60.     var pathTest = compilePathLevel(processedPath, processed, options)
  62.     if (pathTest !== null) {
  63.       tests.push({
  64.         'filename': processedPath.name + '-test.js',
  65.         'contents': pathTest
  66.       })
  67.     }
  68.   });
  70.   if (tests.length === 0) {
  71.     return null
  72.   }
  74.   return tests
  75. }
  77. /**
  78.  * GeneratedPath is the result of procressing a path & compiling the path-level test code
  79.  * @typedef {object} GeneratedPath
  80.  * @memberof compilation
  81.  * @property {string} test the generated test code portion
  82.  */
  84. /**
  85.  * Compiles the path level 'describe' content
  86.  * @function compilePathLevel
  87.  * @memberof compilation
  88.  * @instance
  89.  * @param {processing.ProcessedPath} processedPath the processed path object to be compiled
  90.  * @param {processing.ProcessedSpec} processed the entire processed API spec
  91.  * @param {object} options for use in test compilation
  92.  * @return {compilation.GeneratedPath}
  93.  */
  94. function compilePathLevel(processedPath, processed, options) {
  95.   var tests = []
  96.   var requireLevelCompiler = prepareTemplate(
  97.       path.join(
  98.           options.templates ? options.templates : DefaultTemplateDirectory,
  99.           TopLevelTemplateName
  100.       )
  101.   )
  103.   var pathLevelCompiler = prepareTemplate(
  104.       path.join(
  105.           options.templates ? options.templates : DefaultTemplateDirectory,
  106.           PathTemplateName
  107.       )
  108.   )
  110.   processedPath.operations.forEach(function (processedOp, ndx, arr) {
  111.     var opLevelTest = compileOperationLevel(processedOp, processedPath,
  112.         processed, options)
  114.     if (opLevelTest !== null) {
  115.       tests.push(opLevelTest)
  116.     }
  117.   })
  119.   var pathLevelDescribe = pathLevelCompiler({
  120.     'pathLevelDescription': processedPath.pathLevelDescription,
  121.     'tests': tests
  122.   })
  124.   return requireLevelCompiler({'test': pathLevelDescribe})
  125. }
  127. /**
  128.  * GeneratedOp is the result of procressing an operation & compiling the operation-level test code
  129.  * @typedef {object} GeneratedOp
  130.  * @memberof compilation
  131.  * @property {string} operationLevelDescription the operation level description to use incompilation
  132.  * @property {compilation.GeneratedTransaction[]} operationLevelTests Generated test file contents
  133.  */
  135. /**
  136.  * Compiles the operation level 'describe' content
  137.  * @function compileOperationLevel
  138.  * @memberof compilation
  139.  * @instance
  140.  * @param {processing.ProcessedOp} processedOp the processed operation object to be compiled
  141.  * @param {processing.ProcessedPath} processedPath the parent processed path object
  142.  * @param {processing.ProcessedSpec} processed the entire processed API spec
  143.  * @param {object} options for use in test compilation
  144.  * @return {compilation.GeneratedOp}
  145.  */
  146. function compileOperationLevel(processedOp, processedPath, processed, options) {
  147.   var tests = []
  148.   var operationLevelCompiler = prepareTemplate(
  149.       path.join(
  150.           options.templates ? options.templates : DefaultTemplateDirectory,
  151.           OperationTemplateName
  152.       )
  153.   )
  155.   processedOp.transactions.forEach(function (transaction, ndx, arr) {
  156.     var transactionTest = compileTransactionLevel(transaction, processedOp,
  157.         processedPath, processed, options)
  159.     tests.push(transactionTest)
  160.   })
  162.   return operationLevelCompiler({
  163.     'operationLevelDescription': processedOp.operationLevelDescription,
  164.     'operationLevelTests': tests
  165.   })
  166. }
  168. /**
  169.  * GeneratedTransaction is the compiled unit test code for a specific transaction
  170.  * @typedef {string} GeneratedTransaction
  171.  * @memberof compilation
  172.  */
  174. /**
  175.  * Compiles the operation level 'describe' content
  176.  * @function compileTransactionLevel
  177.  * @memberof compilation
  178.  * @instance
  179.  * @param {processing.ProcessedTransaction} transaction the processed transaction object to be compiled
  180.  * @param {processing.ProcessedOp} processedOp the parent processed operation object
  181.  * @param {processing.ProcessedPath} processedPath the parent processed path object
  182.  * @param {processing.ProcessedSpec} processed the entire processed API spec
  183.  * @param {object} options for use in test compilation
  184.  * @return {compilation.GeneratedTransaction}
  185.  */
  186. function compileTransactionLevel(transaction, processedOp, processedPath,
  187.     processed, options) {
  188.   var transactionCompiler = prepareTemplate(
  189.       path.join(
  190.           options.templates ? options.templates : DefaultTemplateDirectory,
  191.           TransactionTemplateName
  192.       )
  193.   )
  195.   return transactionCompiler(transaction)
  196. }
  198. /**
  199.  * prepares a handlebars template for the template given by the path
  200.  * @function prepareTemplate
  201.  * @memberof compilation
  202.  * @instance
  203.  * @param {string} templatePath path to the template to load
  204.  * @return {function}
  205.  */
  206. function prepareTemplate(templatePath) {
  207.   var source = fs.readFileSync(templatePath, 'utf8');
  208.   return handlebars.compile(source, {noEscape: true})
  209. }