@azu/docco

<!DOCTYPE html> <html> <head> <title>tests.coffee</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0, maximum-scale=1.0, user-scalable=0"> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div id="container"> <div id="background"></div> <ul class="sections"> <li id="title"> <div class="annotation"> <h1>tests.coffee</h1> </div> </li> <li id="section-1"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-1">¶</a> </div> </div> <div class="content"><div class='highlight'><pre> path = <span class="hljs-built_in">require</span> <span class="hljs-string">'path'</span> fs = <span class="hljs-built_in">require</span> <span class="hljs-string">'fs'</span> xfs = <span class="hljs-built_in">require</span> <span class="hljs-string">'fs-extra'</span> rimraf = <span class="hljs-built_in">require</span> <span class="hljs-string">'rimraf'</span> Docco = <span class="hljs-built_in">require</span> <span class="hljs-string">'../docco'</span></pre></div></div> </li> <li id="section-2"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-2">¶</a> </div> <p>Determine the test and resources paths</p> </div> <div class="content"><div class='highlight'><pre>testPath = path.dirname fs.realpathSync(__filename) dataPath = path.join testPath, <span class="hljs-string">"data"</span> resourcesPath = path.normalize path.join(testPath, <span class="hljs-string">"/resources"</span>)</pre></div></div> </li> <li id="section-3"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-3">¶</a> </div> <p>test runner</p> </div> <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">test</span> = <span class="hljs-params">(msg, f)</span> -></span> <span class="hljs-built_in">console</span>.log <span class="hljs-string">"\n===========================================\n"</span>, msg f()</pre></div></div> </li> <li id="section-4"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-4">¶</a> </div> <p>a la jasmine: renamed test runnr which does nothing, i.e. is used for (temporarily) disabled tests:</p> </div> <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">xtest</span> = <span class="hljs-params">(msg, f)</span> -></span> <span class="hljs-built_in">console</span>.log <span class="hljs-string">"\n================SKIPPED===================\n"</span>, msg <span class="hljs-keyword">return</span></pre></div></div> </li> <li id="section-5"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-5">¶</a> </div> <p>assert function:</p> </div> <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">equal</span> = <span class="hljs-params">(a, b, msg)</span> -></span> <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error(<span class="hljs-string">"TEST FAILED: "</span> + msg + <span class="hljs-string">" ("</span> + a + <span class="hljs-string">" !== "</span> + b + <span class="hljs-string">")"</span>) <span class="hljs-keyword">if</span> (a != b) a == b <span class="hljs-function"> <span class="hljs-title">ensureDirectory</span> = <span class="hljs-params">(dir, f)</span> -></span> xfs.mkdirsSync(dir) f()</pre></div></div> </li> <li id="section-6"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-6">¶</a> </div> <h3 id="docco-test-assertion-wrapper">Docco Test Assertion Wrapper</h3> </div> </li> <li id="section-7"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-7">¶</a> </div> <p>Run a Docco pass, and check that the number of output files is equal to what is expected. We assume there is one CSS file that is always copied to the output, so we check that the number of output files is (matched_sources + 1).</p> </div> <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">testDoccoRun</span> = <span class="hljs-params">(testName, sources, options=<span class="hljs-literal">null</span>, callback=<span class="hljs-literal">null</span>)</span> -></span> destPath = path.join dataPath, testName</pre></div></div> </li> <li id="section-8"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-8">¶</a> </div> <p>Remove the data directory for this test run</p> </div> <div class="content"><div class='highlight'><pre><span class="hljs-function"> <span class="hljs-title">cleanup</span> = <span class="hljs-params">(callback)</span> -></span> rimraf destPath, callback cleanup (error) -> equal <span class="hljs-keyword">not</span> error, <span class="hljs-literal">true</span>, <span class="hljs-string">"path cleaned up properly"</span> options?.output = destPath opts = options || {} opts.args = sources</pre></div></div> </li> <li id="section-9"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-9">¶</a> </div> <p>console.log “going to run docco with options: “, opts</p> </div> <div class="content"><div class='highlight'><pre> Docco.<span class="hljs-built_in">document</span> opts, <span class="hljs-function"><span class="hljs-params">(error, info)</span> -></span></pre></div></div> </li> <li id="section-10"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-10">¶</a> </div> <p>Calculate the number of expected files in the output, and then the number of files actually found in the output path.</p> </div> <div class="content"><div class='highlight'><pre> files = [] <span class="hljs-keyword">for</span> src, i <span class="hljs-keyword">in</span> sources</pre></div></div> </li> <li id="section-11"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-11">¶</a> </div> <p>console.log “check output for file: “, { index: i src: src }</p> </div> <div class="content"><div class='highlight'><pre> files = files.concat(info.source_infos[i].destDocFile) extra_files = <span class="hljs-number">0</span> <span class="hljs-keyword">if</span> options <span class="hljs-keyword">if</span> options.markdown extra_files = <span class="hljs-number">2</span> <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> options.template extra_files = <span class="hljs-number">0</span> <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> options.css extra_files = <span class="hljs-number">2</span> <span class="hljs-keyword">else</span> extra_files = <span class="hljs-number">2</span> expected = files.length + extra_files found = fs.readdirSync(destPath).length</pre></div></div> </li> <li id="section-12"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-12">¶</a> </div> <p>Check the expected number of files against the number of files that were actually found.</p> </div> <div class="content"><div class='highlight'><pre> equal found, expected, <span class="hljs-string">"find expected output (<span class="hljs-subst">#{expected}</span> files) - (<span class="hljs-subst">#{found}</span>)"</span></pre></div></div> </li> <li id="section-13"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-13">¶</a> </div> <p>Trigger the completion callback if it’s specified</p> </div> <div class="content"><div class='highlight'><pre> callback() <span class="hljs-keyword">if</span> callback?</pre></div></div> </li> <li id="section-14"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-14">¶</a> </div> <p><strong>Optional markdown output should be supported</strong></p> </div> <div class="content"><div class='highlight'><pre>test <span class="hljs-string">"markdown from docco"</span>, <span class="hljs-function">-></span> testDoccoRun <span class="hljs-string">"markdown_output"</span>, [<span class="hljs-string">"<span class="hljs-subst">#{testPath}</span>/tests.coffee"</span>], markdown: <span class="hljs-literal">true</span></pre></div></div> </li> <li id="section-15"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-15">¶</a> </div> <p><strong>Custom jst template files should be supported</strong></p> </div> <div class="content"><div class='highlight'><pre>test <span class="hljs-string">"custom JST template file"</span>, <span class="hljs-function">-></span> testDoccoRun <span class="hljs-string">"custom_jst"</span>, [<span class="hljs-string">"<span class="hljs-subst">#{testPath}</span>/tests.coffee"</span>], template: <span class="hljs-string">"<span class="hljs-subst">#{resourcesPath}</span>/pagelet/docco.jst"</span></pre></div></div> </li> <li id="section-16"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-16">¶</a> </div> <p><strong>Custom CSS files should be supported</strong></p> </div> <div class="content"><div class='highlight'><pre>test <span class="hljs-string">"custom CSS file"</span>, <span class="hljs-function">-></span> testDoccoRun <span class="hljs-string">"custom_css"</span>, [<span class="hljs-string">"<span class="hljs-subst">#{testPath}</span>/tests.coffee"</span>], css: <span class="hljs-string">"<span class="hljs-subst">#{resourcesPath}</span>/pagelet/docco.css"</span></pre></div></div> </li> <li id="section-17"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-17">¶</a> </div> <p><strong>Specifying a filetype independent of extension should be supported</strong></p> </div> <div class="content"><div class='highlight'><pre>test <span class="hljs-string">"specify an extension"</span>, <span class="hljs-function">-></span> testDoccoRun <span class="hljs-string">"specify_extension"</span>, [<span class="hljs-string">"<span class="hljs-subst">#{testPath}</span>/comments/noextension"</span>], extension: <span class="hljs-string">".coffee"</span></pre></div></div> </li> <li id="section-18"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-18">¶</a> </div> <p><strong>Comments should be parsed properly</strong></p> <p>There are special data files located in <code>test/comments</code> for each supported language. The first comment in each file corresponds to the expected number of comments to be parsed from its contents.</p> <p>This test iterates over all the known Docco languages, and tests the ones that have a corresponding data file in <code>test/comments</code>.</p> </div> <div class="content"><div class='highlight'><pre>test <span class="hljs-string">"single line and block comment parsing"</span>, <span class="hljs-function">-></span> commentsPath = path.join testPath, <span class="hljs-string">"comments"</span> options = template: <span class="hljs-string">"<span class="hljs-subst">#{commentsPath}</span>/comments.jst"</span> blocks : <span class="hljs-literal">true</span></pre></div></div> </li> <li id="section-19"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-19">¶</a> </div> <p>Construct a list of languages to test asynchronously. It’s important that these be tested one at a time, to avoid conflicts between multiple file extensions for a language. e.g. <code>c.c</code> and <code>c.h</code> both output to c.html, so they must be run at separate times.</p> </div> <div class="content"><div class='highlight'><pre> languageKeys = (ext <span class="hljs-keyword">for</span> ext,l <span class="hljs-keyword">of</span> Docco.languages) <span class="hljs-function"> <span class="hljs-title">testNextLanguage</span> = <span class="hljs-params">(keys,callback)</span> -></span> <span class="hljs-keyword">return</span> callback?() <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> keys.length extension = keys.shift() language = Docco.languages[extension] languageExample = path.join commentsPath, <span class="hljs-string">"<span class="hljs-subst">#{language.name}</span><span class="hljs-subst">#{extension}</span>"</span> languageTest = <span class="hljs-string">"comments_test/<span class="hljs-subst">#{language.name}</span>"</span> languagePath = path.join dataPath, languageTest languageOutput = path.join languagePath, <span class="hljs-string">"<span class="hljs-subst">#{language.name}</span>.html"</span></pre></div></div> </li> <li id="section-20"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-20">¶</a> </div> <p><em>Skip over this language if there is no corresponding test</em></p> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-keyword">return</span> testNextLanguage(keys, callback) <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> path.existsSync languageExample</pre></div></div> </li> <li id="section-21"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-21">¶</a> </div> <p>Run them through docco with the custom <code>comments.jst</code> file that outputs a CSV list of doc blocks text.</p> </div> <div class="content"><div class='highlight'><pre> testDoccoRun languageTest, [languageExample], options, <span class="hljs-function">-></span></pre></div></div> </li> <li id="section-22"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-22">¶</a> </div> <p>Be sure the expected output file exists</p> </div> <div class="content"><div class='highlight'><pre> equal <span class="hljs-literal">true</span>, path.existsSync(languageOutput), <span class="hljs-string">"<span class="hljs-subst">#{languageOutput}</span> -> output file created properly"</span></pre></div></div> </li> <li id="section-23"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-23">¶</a> </div> <p>Read in the output file contents, split them into a list of comments.</p> </div> <div class="content"><div class='highlight'><pre> content = fs.readFileSync(languageOutput).toString() comments = (c.trim() <span class="hljs-keyword">for</span> c <span class="hljs-keyword">in</span> content.split(<span class="hljs-string">','</span>) <span class="hljs-keyword">when</span> c.trim() != <span class="hljs-string">''</span>) equal <span class="hljs-literal">true</span>, comments.length >= <span class="hljs-number">1</span>, <span class="hljs-string">'expect at least the descriptor comment'</span></pre></div></div> </li> <li id="section-24"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-24">¶</a> </div> <p>Parse the first comment (special case), to identify the expected comment counts, based on whether we’re matching block comments or not.</p> </div> <div class="content"><div class='highlight'><pre> descriptor = comments[<span class="hljs-number">0</span>].match(<span class="hljs-regexp">/^Single:([0-9]*) - Block:([0-9]*)$/</span>) <span class="hljs-keyword">if</span> !descriptor <span class="hljs-built_in">console</span>.log <span class="hljs-string">"comment is malformed! "</span>, comments expected = parseInt(<span class="hljs-keyword">if</span> l.blocks <span class="hljs-keyword">and</span> options.blocks <span class="hljs-keyword">then</span> descriptor[<span class="hljs-number">2</span>] <span class="hljs-keyword">else</span> descriptor[<span class="hljs-number">1</span>]) equal comments.length, expected, [ <span class="hljs-string">""</span> <span class="hljs-string">"<span class="hljs-subst">#{path.basename(languageOutput)}</span> comments"</span> <span class="hljs-string">"------------------------"</span> <span class="hljs-string">" blocks : <span class="hljs-subst">#{options.blocks}</span>"</span> <span class="hljs-string">" expected : <span class="hljs-subst">#{expected}</span>"</span> <span class="hljs-string">" found : <span class="hljs-subst">#{comments.length}</span>"</span> ].join <span class="hljs-string">'\n'</span></pre></div></div> </li> <li id="section-25"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-25">¶</a> </div> <p>Invoke the next test</p> </div> <div class="content"><div class='highlight'><pre> testNextLanguage keys, callback</pre></div></div> </li> <li id="section-26"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-26">¶</a> </div> <p><em>Kick off the first language test</em></p> </div> <div class="content"><div class='highlight'><pre> testNextLanguage languageKeys.slice(), <span class="hljs-function">-></span></pre></div></div> </li> <li id="section-27"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-27">¶</a> </div> <p>Test to be sure block comments are excluded when not explicitly specified. In this case, the test will check for the existence of only 1 comment in all languages (a single-line)</p> </div> <div class="content"><div class='highlight'><pre> options.blocks = <span class="hljs-literal">false</span> testNextLanguage languageKeys.slice()</pre></div></div> </li> <li id="section-28"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-28">¶</a> </div> <p><strong>URL references should resolve across sections</strong></p> <p>Resolves <a href="https://github.com/jashkenas/docco/issues/100">Issue 100</a></p> </div> <div class="content"><div class='highlight'><pre>test <span class="hljs-string">"url references (defined up front)"</span>, <span class="hljs-function">-></span> ensureDirectory dataPath, <span class="hljs-function">-></span> sourceFile = <span class="hljs-string">"<span class="hljs-subst">#{dataPath}</span>/_urlref.coffee"</span> fs.writeFileSync sourceFile, [ <span class="hljs-string">"# [google]: http://www.google.com"</span>, <span class="hljs-string">"#"</span>, <span class="hljs-string">"# Look at this link to [Google][]!"</span>, <span class="hljs-string">"console.log 'This must be Thursday.'"</span>, <span class="hljs-string">"# And this link to [Google][] as well."</span>, <span class="hljs-string">"console.log 'I never could get the hang of Thursdays.'"</span> ].join(<span class="hljs-string">'\n'</span>) outPath = path.join dataPath, <span class="hljs-string">"_urlreferences1"</span> outFile = <span class="hljs-string">"<span class="hljs-subst">#{outPath}</span>/_urlref.html"</span> rimraf outPath, <span class="hljs-function"><span class="hljs-params">(error)</span> -></span> equal <span class="hljs-keyword">not</span> error, <span class="hljs-literal">true</span> Docco.<span class="hljs-built_in">document</span> { cwd: dataPath, output: outPath, args: [sourceFile] }, <span class="hljs-function">-></span> contents = fs.readFileSync(outFile).toString() count = contents.match <span class="hljs-regexp">///<a\shref="http://www.google.com">Google</a>///</span>g equal count?.length, <span class="hljs-number">2</span>, <span class="hljs-string">"find expected (2) resolved url references"</span> test <span class="hljs-string">"url references (defined at the end)"</span>, <span class="hljs-function">-></span> ensureDirectory dataPath, <span class="hljs-function">-></span> sourceFile = <span class="hljs-string">"<span class="hljs-subst">#{dataPath}</span>/_urlref.coffee"</span> fs.writeFileSync sourceFile, [ <span class="hljs-string">"# Look at this link to [Google][]!"</span>, <span class="hljs-string">"console.log 'This must be Thursday.'"</span>, <span class="hljs-string">"# And this link to [Google][] as well."</span>, <span class="hljs-string">"console.log 'I never could get the hang of Thursdays.'"</span>, <span class="hljs-string">"# [google]: http://www.google.com"</span> ].join(<span class="hljs-string">'\n'</span>) outPath = path.join dataPath, <span class="hljs-string">"_urlreferences2"</span> outFile = <span class="hljs-string">"<span class="hljs-subst">#{outPath}</span>/_urlref.html"</span> rimraf outPath, <span class="hljs-function"><span class="hljs-params">(error)</span> -></span> equal <span class="hljs-keyword">not</span> error, <span class="hljs-literal">true</span> Docco.<span class="hljs-built_in">document</span> { cwd: dataPath, output: outPath, args: [sourceFile] }, <span class="hljs-function">-></span> contents = fs.readFileSync(outFile).toString() count = contents.match <span class="hljs-regexp">///<a\shref="http://www.google.com">Google</a>///</span>g equal count?.length, <span class="hljs-number">2</span>, <span class="hljs-string">"find expected (2) resolved url references"</span></pre></div></div> </li> <li id="section-29"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-29">¶</a> </div> <p><strong>Paths should be recursively created if needed</strong></p> <p>ensureDirectory should properly create complex output paths.</p> </div> <div class="content"><div class='highlight'><pre>test <span class="hljs-string">"create complex paths that do not exist"</span>, <span class="hljs-function">-></span> exist = fs.existsSync <span class="hljs-keyword">or</span> path.existsSync outputPath = path.join dataPath, <span class="hljs-string">'complex/path/that/doesnt/exist'</span> rimraf outputPath, <span class="hljs-function"><span class="hljs-params">(error)</span> -></span> equal <span class="hljs-keyword">not</span> error, <span class="hljs-literal">true</span> ensureDirectory outputPath, <span class="hljs-function">-></span> equal exist(outputPath), <span class="hljs-literal">true</span>, <span class="hljs-string">'created output path: '</span> + outputPath stat = fs.statSync outputPath equal stat.isDirectory(), <span class="hljs-literal">true</span>, <span class="hljs-string">"target is directory"</span></pre></div></div> </li> </ul> </div> </body> </html>