Skip to content

Commit

Permalink
chore: update docs (#23)
Browse files Browse the repository at this point in the history
  • Loading branch information
@noahdietz
noahdietz authored May 28, 2019
1 parent 548d573 commit 0069a73
Show file tree
Hide file tree
Showing 10 changed files with 512 additions and 420 deletions.
16 changes: 8 additions & 8 deletions docs/compilation.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ <h4 class="name" id="compile"><span class="type-signature"></span>compile<span c

<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line46">line 46</a>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line47">line 47</a>
</li></ul></dd>


Expand Down Expand Up @@ -526,7 +526,7 @@ <h4 class="name" id="compilePathLevel"><span class="type-signature"></span>compi

<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line83">line 83</a>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line84">line 84</a>
</li></ul></dd>


Expand Down Expand Up @@ -723,7 +723,7 @@ <h4 class="name" id="compileTransactionLevel"><span class="type-signature"></spa

<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line173">line 173</a>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line174">line 174</a>
</li></ul></dd>


Expand Down Expand Up @@ -966,7 +966,7 @@ <h4 class="name" id="prepareTemplate"><span class="type-signature"></span>prepar

<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line196">line 196</a>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line198">line 198</a>
</li></ul></dd>


Expand Down Expand Up @@ -1267,7 +1267,7 @@ <h4 class="name" id=".GeneratedPath">GeneratedPath</h4>

<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line76">line 76</a>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line77">line 77</a>
</li></ul></dd>


Expand Down Expand Up @@ -1392,7 +1392,7 @@ <h4 class="name" id=".GeneratedTest">GeneratedTest</h4>

<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line38">line 38</a>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line39">line 39</a>
</li></ul></dd>


Expand Down Expand Up @@ -1540,7 +1540,7 @@ <h4 class="name" id=".GeneratedTransaction">GeneratedTransaction</h4>

<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line167">line 167</a>
<a href="lib_compile.js.html">lib/compile.js</a>, <a href="lib_compile.js.html#line168">line 168</a>
</li></ul></dd>


Expand Down Expand Up @@ -1616,7 +1616,7 @@ <h5>Type:</h5>
<br class="clear">

<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Fri May 18 2018 10:10:23 GMT-0700 (PDT) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.2</a> on Tue May 28 2019 13:54:41 GMT-0700 (Pacific Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
</footer>

<script>prettyPrint();</script>
Expand Down
2 changes: 1 addition & 1 deletion docs/global.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -605,7 +605,7 @@ <h5>Type:</h5>
<br class="clear">

<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Fri May 18 2018 10:10:23 GMT-0700 (PDT) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.2</a> on Tue May 28 2019 13:54:41 GMT-0700 (Pacific Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
</footer>

<script>prettyPrint();</script>
Expand Down
97 changes: 76 additions & 21 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,18 +46,25 @@ <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="compil


<section class="readme">
<article><p><a href="https://travis-ci.org/noahdietz/oatts"><img src="https://travis-ci.org/noahdietz/oatts.svg?branch=master" alt="Build Status"></a></p>
<h1>OpenAPI Test Templates (oatts)</h1><blockquote>
<article><p><a href="https://travis-ci.org/google/oatts"><img src="https://travis-ci.org/google/oatts.svg?branch=master" alt="Build Status"></a></p>
<h1>OpenAPI Test Templates (oatts)</h1>
<blockquote>
<p>Generate basic unit test scaffolding for your <a href="https://www.openapis.org/">OpenAPI specification</a>.</p>
</blockquote>
<h2>Disclaimer</h2><p>This is not an officially supported Google product.</p>
<h2>Disclaimer</h2>
<p>This is not an officially supported Google product.</p>
<p><code>oatts</code> is based off of the <a href="https://github.com/apigee-127/swagger-test-templates">swagger-test-templates</a> module and the lessons learned during its development.</p>
<p><em>This is a work in progress.</em></p>
<h2>Goal</h2><p>The goal of <code>oatts</code> is to provide a standalone module for generating Node.js unit test code scaffolding based on a given OpenAPI specification.</p>
<h2>Goal</h2>
<p>The goal of <code>oatts</code> is to provide a standalone module for generating Node.js unit test code scaffolding based on a given OpenAPI specification.</p>
<p>The hope is that by providing such a tool, API developers will be encouraged to test the contract between their spec and backend early, often and continuously as the project grows.</p>
<h2>Usage</h2><p>There are a couple ways to use <code>oatts</code>.</p>
<h3>Module</h3><p>Install via <code>npm</code></p>
<pre class="prettyprint source"><code>npm install --save oatts</code></pre><p>Then use it in code</p>
<h2>Usage</h2>
<p>There are a couple ways to use <code>oatts</code>.</p>
<h3>Module</h3>
<p>Install via <code>npm</code></p>
<pre><code>npm install --save oatts
</code></pre>
<p>Then use it in code</p>
<pre class="prettyprint source lang-js"><code>var oatts = require('oatts');

var options = {
Expand All @@ -66,8 +73,13 @@ <h3>Module</h3><p>Install via <code>npm</code></p>

var tests = oatts.generate('/path/to/openapi.yaml', options);

console.log(tests)</code></pre><h3>Command line interface</h3><p>Install globally via <code>npm</code></p>
<pre class="prettyprint source"><code>npm install -g oatts</code></pre><p>Then use in your command line</p>
console.log(tests)
</code></pre>
<h3>Command line interface</h3>
<p>Install globally via <code>npm</code></p>
<pre><code>npm install -g oatts
</code></pre>
<p>Then use in your command line</p>
<pre class="prettyprint source lang-sh"><code>> oatts generate --help

Usage: generate [options]
Expand All @@ -93,7 +105,10 @@ <h3>Module</h3><p>Install via <code>npm</code></p>
> oatts generate -s ./path/to/openapi.yaml -w ./output/dir
> ls ./output/dir
pet-test.js pet-{petId}-uploadImage-test.js user-test.js
. . .</code></pre><h3>Using the result</h3><p>The resulting test files are built using the <a href="https://mochajs.org/">mocha</a> testing framework and <a href="http://dareid.github.io/chakram/">chakram</a> API testing framework. Thus, you will need both of these dependencies installed in order to run your newly generated tests.</p>
. . .
</code></pre>
<h3>Using the result</h3>
<p>The resulting test files are built using the <a href="https://mochajs.org/">mocha</a> testing framework and <a href="http://dareid.github.io/chakram/">chakram</a> API testing framework. Thus, you will need both of these dependencies installed in order to run your newly generated tests.</p>
<p>After installing these, you can run the tests with mocha:</p>
<pre class="prettyprint source"><code># start your API server to test against!!
> mocha --recursive &lt;test directory>
Expand All @@ -108,9 +123,13 @@ <h3>Module</h3><p>Install via <code>npm</code></p>
✓ should respond 200 for &quot;Success&quot;


2 passing (82ms)</code></pre><h3>Custom Values</h3><p>Custom values can be supplied through both the command line and a JSON file. The in-line, command line supplied JSON will take precedent.</p>
2 passing (82ms)
</code></pre>
<h3>Custom Values</h3>
<p>Custom values can be supplied through both the command line and a JSON file. The in-line, command line supplied JSON will take precedent.</p>
<p>An example custom values JSON file can be found <a href="./test/process/documents/customValuesTest.json">here</a>.</p>
<h3>Custom Templates</h3><p>Custom templates can be supplied via the <code>templates</code> option. The directory pointed to by the option must contain 4 <a href="http://handlebarsjs.com/">Handlebars</a> templates named the same way as those found in <code>./templates</code>.</p>
<h3>Custom Templates</h3>
<p>Custom templates can be supplied via the <code>templates</code> option. The directory pointed to by the option must contain 4 <a href="http://handlebarsjs.com/">Handlebars</a> templates named the same way as those found in <code>./templates</code>.</p>
<ul>
<li><code>topLevel.handlebars</code>: the top level template for a single test file</li>
<li><code>pathLevel.handlebars</code>: the path level template, usually the beginning of a test suite for a specific path</li>
Expand All @@ -119,7 +138,8 @@ <h3>Custom Templates</h3><p>Custom templates can be supplied via the <code>templ
</ul>
<p>The data available to be used in the templates is specified in the <code>ProcessedSpec</code> type.</p>
<p>There are also a few helpers available to be used in the Handlebars templates, which can be found in the <code>templateHelpers</code> documentation namespace. Use the default templates as examples of how to use them.</p>
<h2>Options</h2><p>The following options can be passed to the generation function, some/all are exposed in the accompanying CLI:</p>
<h2>Options</h2>
<p>The following options can be passed to the generation function, some/all are exposed in the accompanying CLI:</p>
<table>
<thead>
<tr>
Expand Down Expand Up @@ -169,14 +189,14 @@ <h2>Options</h2><p>The following options can be passed to the generation functio
<tr>
<td><code>consumes</code></td>
<td style="text-align:center"><code>--consumes -c</code></td>
<td style="text-align:right"><code>operation.consumes[0]</code> &#124; &#124; <code>spec.conumes[0]</code></td>
<td style="text-align:right"><code>operation.consumes[0]</code> | | <code>spec.conumes[0]</code></td>
<td style="text-align:right"><code>false</code></td>
<td style="text-align:right">Consumes header to use in a request when applicable</td>
</tr>
<tr>
<td><code>produces</code></td>
<td style="text-align:center"><code>--produces -o</code></td>
<td style="text-align:right"><code>operation.produces[0]</code> &#124; &#124; <code>spec.produces[0]</code></td>
<td style="text-align:right"><code>operation.produces[0]</code> | | <code>spec.produces[0]</code></td>
<td style="text-align:right"><code>false</code></td>
<td style="text-align:right">Produces header to use in a request when applicable</td>
</tr>
Expand Down Expand Up @@ -215,14 +235,49 @@ <h2>Options</h2><p>The following options can be passed to the generation functio
<td style="text-align:right"><code>false</code></td>
<td style="text-align:right">comma separated list of status codes to explicity generate tests for</td>
</tr>
<tr>
<td><code>jsonRefs</code></td>
<td style="text-align:center"></td>
<td style="text-align:right">n/a</td>
<td style="text-align:right"><code>false</code></td>
<td style="text-align:right"><em>(See <a href="https://github.com/whitlockjc/json-refs/blob/master/docs/API.md#module_JsonRefs..JsonRefsOptions">JsonRefs~JsonRefsOptions</a>)</em></td>
</tr>
<tr>
<td><code>customFormats</code></td>
<td style="text-align:center"></td>
<td style="text-align:right">n/a</td>
<td style="text-align:right"><code>false</code></td>
<td style="text-align:right">The key/value pair of custom formats <em>(The keys are the format name and the values are async functions. See <a href="https://github.com/zaggino/z-schema#register-a-custom-format">ZSchema Custom Formats</a>)</em></td>
</tr>
<tr>
<td><code>customFormatGenerators</code></td>
<td style="text-align:center"></td>
<td style="text-align:right">n/a</td>
<td style="text-align:right"><code>false</code></td>
<td style="text-align:right">The key/value pair of custom format generators <em>(The keys are the format name and the values are functions. See <a href="https://github.com/json-schema-faker/json-schema-faker#custom-formats">json-schema-mocker Custom Format</a>)</em></td>
</tr>
<tr>
<td><code>customValidators</code></td>
<td style="text-align:center"></td>
<td style="text-align:right">n/a</td>
<td style="text-align:right"><code>false</code></td>
<td style="text-align:right">The custom validators. See <a href="https://github.com/apigee-127/sway/blob/master/docs/API.md#module_sway.DocumentValidationFunction">DocumentValidationFunction</a></td>
</tr>
</tbody>
</table>
<h2>Testing</h2><p>To test this module simply use the <code>npm</code> script</p>
<pre class="prettyprint source"><code>npm test</code></pre><h2>Discussion</h2><p>If you have a question or a topic you'd like to discuss, please feel free to open
<h2>Testing</h2>
<p>To test this module simply use the <code>npm</code> script</p>
<pre><code>npm test
</code></pre>
<h2>Discussion</h2>
<p>If you have a question or a topic you'd like to discuss, please feel free to open
a discussion on our Google Group <a href="https://groups.google.com/forum/#!forum/oatts-users/">oatts-users</a>.</p>
<h2>Contributing</h2><p>Contributors are welcome! Please see <a href="CONTRIBUTING.md">CONTRIBUTING.md</a>.</p>
<h2>Copyright</h2><p>Copyright 2018, Google Inc.</p>
<h2>License</h2><p>See <a href="LICENSE">LICENSE</a> file.</p></article>
<h2>Contributing</h2>
<p>Contributors are welcome! Please see <a href="CONTRIBUTING.md">CONTRIBUTING.md</a>.</p>
<h2>Copyright</h2>
<p>Copyright 2018, Google Inc.</p>
<h2>License</h2>
<p>See <a href="LICENSE">LICENSE</a> file.</p></article>
</section>


Expand All @@ -235,7 +290,7 @@ <h2>License</h2><p>See <a href="LICENSE">LICENSE</a> file.</p></article>
<br class="clear">

<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Fri May 18 2018 10:10:23 GMT-0700 (PDT) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.2</a> on Tue May 28 2019 13:54:41 GMT-0700 (Pacific Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
</footer>

<script>prettyPrint();</script>
Expand Down
73 changes: 41 additions & 32 deletions docs/index.js.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ <h1 class="page-title">index.js</h1>
var merge2 = require('./lib/util').merge2

module.exports = {
generate: generate
generate: generate
}

/**
Expand All @@ -79,40 +79,49 @@ <h1 class="page-title">index.js</h1>
* @return {Promise&lt;GenerationResults>}
*/
function generate(specPath, options) {
return sway.create({'definition': specPath})
.then(function (api) {
if (options.customValues) {
options.customValues = JSON.parse(options.customValues);
}

if (options.customValuesFile) {
var customFromFile = require(join(process.cwd(), options.customValuesFile))
options.customValues = merge2(options.customValues, customFromFile)
}
return sway.create({
'definition': specPath,
'jsonRefs': options &amp;&amp; options.jsonRefs,
'customFormats': options &amp;&amp; options.customFormats,
'customFormatGenerators': options &amp;&amp; options.customFormatGenerators,
'customValidators': options &amp;&amp; options.customValidators
})
.then(function (api) {
if (options.customValues) {
options.customValues = JSON.parse(options.customValues);
}

if (options.customValuesFile) {
var customFromFile = require(
join(process.cwd(), options.customValuesFile))
options.customValues = merge2(options.customValues, customFromFile)
}

var processed = proc(api, options)
var compiled = compile(processed, options)
var processed = proc(api, options)
var compiled = compile(processed, options)

if (options.writeTo !== undefined) {
if (!fs.existsSync(options.writeTo)) {
fs.mkdirSync(options.writeTo)
}

compiled.forEach(function(testObj, ndx, arr) {
fs.writeFile(join(options.writeTo, testObj.filename), testObj.contents, function(err) {
if (err !== null) {
console.error(err)
}
})
})
if (options.writeTo !== undefined) {
if (!fs.existsSync(options.writeTo)) {
fs.mkdirSync(options.writeTo)
}

try {
for (var i = 0; i &lt; compiled.length; i++) {
const testObj = compiled[i];
fs.writeFileSync(join(options.writeTo, testObj.filename), testObj.contents)
}
} catch (err) {
console.log(err);
}
}

return { 'generated': compiled }
}, function (err) {
console.error(err.stack);
return err
});
}</code></pre>
return {'generated': compiled}
}, function (err) {
console.error(err.stack);
return err
});
}
</code></pre>
</article>
</section>

Expand All @@ -124,7 +133,7 @@ <h1 class="page-title">index.js</h1>
<br class="clear">

<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Fri May 18 2018 10:10:23 GMT-0700 (PDT) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.2</a> on Tue May 28 2019 13:54:41 GMT-0700 (Pacific Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
</footer>

<script>prettyPrint();</script>
Expand Down
Loading

0 comments on commit 0069a73

Please sign in to comment.