Update documentation and comments

README.md

@@ -6,7 +6,7 @@ A simple test runner for testing asynchronous code.
 **node-async-testing**...
 
 + fully embraces Node's async environoment
-+ supports parallel test execution
++ supports parallel test and suite execution
 + has true test _and_ suite setup and teardown functions
 + helps your organize your suites by allowing you to group different tests
   together in sub-suites

docs/index.html

@@ -14,7 +14,7 @@ <h2>Simple, intuitive testing for node.js</h2>
 
       <nav>
         <ul>
-          <li class="current"><a href="index.html">Home</a></li>
+          <li class="current"><a href="./">Home</a></li>
           <li><a href="writing-tests.html">Writing Tests</a></li>
           <li><a href="running-tests.html">Running Tests</a></li>
         </ul>
@@ -29,8 +29,8 @@ <h1>Overview:</h1>
 
         <ul>
           <li>fully embraces Node's async environoment</li>
-          <li>supports parallel test execution</li>
-          <li>has true test <i>and</i> suite setup and teardown functions</li>
+          <li>supports parallel test and suite execution</li>
+          <li>has true test and suite setup and teardown functions</li>
           <li>
             helps your organize your suites by allowing you to group different
             tests together in sub-suites

docs/running-tests.html

@@ -14,7 +14,7 @@ <h2>Simple, intuitive testing for node.js</h2>
 
       <nav>
         <ul>
-          <li><a href="index.html">Home</a></li>
+          <li><a href="./">Home</a></li>
           <li><a href="writing-tests.html">Writing Tests</a></li>
           <li class="current"><a href="running-tests.html">Running Tests</a></li>
         </ul>
@@ -25,7 +25,7 @@ <h1>Running Test Suites</h1>
 
         <p>
         <b>node-async-testing</b> includes two different means of running suites:
-        A simple, streamlined interface for running suite files and a low-level API
+        A simple, recommended interface for running suite files and a low-level API
         (which is used by the previous method) which gives you fine-grained control.
         </p>
 
@@ -76,7 +76,7 @@ <h1>Running Suite Files</h1>
         <p>
         To make a file easy to execute with the <code>node</code> command, we need
         how to make our file run the suite when it is the script being ran.  Some where
-        in the file we put this code:
+        in the file we put this code (I like to put it at the very top):
         </p>
 
         <div class="highlight"><pre>
@@ -99,13 +99,14 @@ <h1>Running Suite Files</h1>
         </p>
 
         <div class="highlight"><pre>
+<span class="k">if</span> <span class="p">(</span><span class="nx">module</span> <span class="o">===</span> <span class="nx">require</span><span class="p">.</span><span class="nx">main</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;async_testing&#39;</span><span class="p">).</span><span class="nx">run</span><span class="p">(</span><span class="nx">process</span><span class="p">.</span><span class="nx">ARGV</span><span class="p">);</span>
+<span class="p">}</span>
+
 <span class="nx">exports</span><span class="p">[</span><span class="s1">&#39;first test&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">test</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
 <span class="nx">exports</span><span class="p">[</span><span class="s1">&#39;second test&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">test</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
 <span class="nx">exports</span><span class="p">[</span><span class="s1">&#39;third test&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">test</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
-
-<span class="k">if</span> <span class="p">(</span><span class="nx">module</span> <span class="o">===</span> <span class="nx">require</span><span class="p">.</span><span class="nx">main</span><span class="p">)</span> <span class="p">{</span>
-  <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;async_testing&#39;</span><span class="p">).</span><span class="nx">run</span><span class="p">(</span><span class="nx">__filename</span><span class="p">,</span> <span class="nx">process</span><span class="p">.</span><span class="nx">ARGV</span><span class="p">);</span>
-<span class="p">}</span></pre></div>
+</pre></div>
 
         <p>
         Now, you can tell <b>node-async-testing</b> to run the tests in parallel:
@@ -189,7 +190,9 @@ <h1>Running suites using the API</h1>
 
         <ul>
           <li><a href="#runSuite">runSuite()</a></li>
+          <li><a href="#runFile">runFile()</a></li>
           <li><a href="#expandFiles">expandFiles()</a></li>
+          <li><a href="#run">run()</a></li>
           <li><a href="#registerRunner">registerRunner()</a></li>
         </ul>
 
@@ -233,8 +236,36 @@ <h1>Running suites using the API</h1>
               </dd>
             </dl>
 
-            In addition to those properties, any of the options in the
+            <p>
+            In addition to those properties, the options in the
             <a href="#running-events">events callbacks</a> section are supported.
+            </p>
+
+            <p>
+            <code>runSuite</code> adds a listener to the process for uncaught exceptions,
+            and as such, there should be no other code running while <code>runSuite</code>
+            is doing its thing, otherwise the other code could interfere with the 
+            suite being ran.
+            </p>
+          </dd>
+
+          <dt id="runFile"><code>runFile(suitePath, options)</code></dt>
+          <dd>
+          <p>
+          The <code>runFile</code> function is similar to <code>runSuite</code> except instead of
+          running the suite in the main process, it opens up a child process and runs it
+          there. The benefits of this are that it is able to report on syntax errors, and
+          also be run while other suites are running.
+          </p>
+          <p>
+          The first argument is a module path to the suite for Node's
+          <code>require()</code> function.
+          </p>
+          <p>
+          The second argument is an object with options for running the suite.  It is practically
+          the same as the second argument for <code>runSuite</code>, except it has one for additional
+          event callback.  See the <a href="#running-events">events callbacks</a> section for
+          the full list.
           </dd>
 
           <dt id="expandFiles"><code>expandFiles(list, [filter], callback)</code></dt>
@@ -271,23 +302,90 @@ <h1>Running suites using the API</h1>
               <dt><code>name</code></dt>
               <dd>This is the file name that was passed in.</dd>
               <dt><code>path</code></dt>
-              <dd>This is an absolute path to the file.</dd>
+              <dd>This is an absolute module path to the file that can be <code>require()</code>ed.</dd>
             </dl>
           </dd>
 
+          <dt id="run"><code>run()</code></dt>
+          <dd>
+            <p>
+            The <code>run</code> method is talked about at length in the
+            <a href="#suite-files">Running Suite Files</a> section. It handles
+            outputing the results of suites for you, so you don't have to worry about it.
+            <b>node-async-testing</b> comes with two built-in runners, one for consoles and one
+            for web browsers.
+            </p>
+
+            <p>
+            Now async_testing.run can take any number of arguments, which can be any
+            one of:
+            </p>
+
+            <ul>
+              <li>
+              A string, the name of a file to run.  The exports object of the file should be
+              a suite object.
+              </li>
+              <li>
+              An array of command line arguments, like <code>process.ARGV</code>.
+              </li>
+              <li>
+              An options object, for manipulating the options for the function directly.  The
+              options you can set here correspond directly to the ones you can set in via the 
+              command line.
+              </li>
+              <li>
+                <p>
+                The last argument can be a callback which will get called when all the specified
+                suites have finished running.  The callback will receive one argument, the number
+                of suites that didn't complete successfully.
+                </p>
+                <p>
+                If a callback is not supplied, <b>node-async-testing</b> assumes that you don't
+                want to do anything after the suites have completed, so the <code>run</code>
+                function creates its own callback which exits the process and sets the exit
+                code to the number of suites that didn't complete successfully.
+                </p>
+              </li>
+            </ul>
+
+
+            <p>
+            The order matters, latter settings override earlier ones. Here are some examples:
+            </p>
+
+            <p>Run a file:</p>
+            <div class="highlight"><pre>async_testing.run<span class="o">(<span class="s1">&#39;myFile.js&#39;</span><span class="o">)</span>;</pre></div>
+
+            <p>Change options:</p>
+            <div class="highlight"><pre>async_testing.run<span class="o">({</span>parallel: <span class="nb">true</span><span class="o">}</span>, <span class="s1">&#39;myFile.js&#39;</span><span class="o">)</span>;</pre></div>
+
+
+            <p>Use command line arguments:</p>
+            <div class="highlight"><pre>async_testing.run<span class="o">(</span>process.ARGV<span class="o">)</span>;</pre></div>
+
+            <p>Use command line arguments with defaults:</p>
+            <div class="highlight"><pre>async_testing.run<span class="o">({</span>parallel: <span class="nb">true</span><span class="o">}</span>, process.ARGV<span class="o">)</span>;</pre></div>
+
+            <p>Overwrite command line arguments:</p>
+            <div class="highlight"><pre>async_testing.run<span class="o">(</span>process.ARGV, <span class="o">{</span>parallel: <span class="nb">true</span><span class="o">})</span>;</pre></div>
+          </dd>
+
           <dt id="registerRunner"><code>registerRunner(modulePath, [default])</code></dt>
           <dd>
             <p>
             Use this function to add your own custom runners to <b>node-async-testing</b>.
             See <a href="http://github.com/bentomas/node-async-testing/blob/master/lib/console-runner.js">lib/console-runner.js</a>
-            for an example of how to write a runner.
+            or <a href="http://github.com/bentomas/node-async-testing/blob/master/lib/web-runner.js">lib/web-runner.js</a>
+            for examples of how to write a runner.
             </p>
             <p>
             The first argument is the path to the runner which you are registering.
             The second variable is for whether or not you want this to be the
             default runner.
             </p>
           </dd>
+
         </dl>
       </section>
 
@@ -303,17 +401,6 @@ <h1>Description of event callbacks</h1>
         <h2>Events</h2>
 
         <dl>
-          <dt><code>onSuiteStart([suiteName])</code></dt>
-          <dd>Called when a suite is started. A suite might not
-          have name, depending how it is ran.
-          </dd>
-
-          <dt><code>onSuiteDone(suiteResult)</code></dt>
-          <dd>
-          Called when a suite finishes. See <a href="#suite-result">Suite result</a>
-          below.
-          </dd>
-
           <dt><code>onTestStart(testName)</code></dt>
           <dd>Called when a test is started.
           </dd>
@@ -324,20 +411,33 @@ <h2>Events</h2>
           below.
           </dd>
 
-          <dt><code>onError(err, testNames)</code></dt>
+          <dt><code>onSuiteCompleted(suiteResult)</code></dt>
+          <dd>
+          Called when a suite finishes. See <a href="#suite-result">Suite result</a>
+          below.
+          </dd>
+
+          <dt><code>onSuiteError(err, testNames)</code></dt>
           <dd>
-          Called when an uncaught error is thrown from a test.  The first argument is
-          the error, the second argument is an array of the names of the tests that
-          could have thrown it.
+          Called when an uncaught error is thrown from a test. This stops running
+          the suite. The first argument is the error, the second argument is an
+          array of the names of the tests that could have thrown it.
           </dd>
 
-          <dt><code>onPrematureExit(testNames)</code></dt>
+          <dt><code>onSuiteExit(testNames)</code></dt>
           <dd>
           Called when the process exits and there are still tests that haven't
           finished. This occurs when people forget to finish their tests or their
           tests don't work like they expected.  This gets one argument: an array of
           the names of the tests that haven't finished.
           </dd>
+
+          <dt><code>onSuiteLoadError(err)</code></dt>
+          <dd>
+          Only called from <code>runFile</code>, and called when the child process
+          can't load the suite.  This gets one argument, the contents of what
+          was written to <code>stderr</code> when the child process exited.
+          </dd>
         </dl>
 
         <h2 id="suite-result">Suite Result</h2>

docs/writing-tests.html

@@ -14,7 +14,7 @@ <h2>Simple, intuitive testing for node.js</h2>
 
       <nav>
         <ul>
-          <li><a href="index.html">Home</a></li>
+          <li><a href="./">Home</a></li>
           <li class="current"><a href="writing-tests.html">Writing Tests</a></li>
           <li><a href="running-tests.html">Running Tests</a></li>
         </ul>
@@ -25,7 +25,7 @@ <h1>Writing Test Suites</h1>
 
         <p>
         The hard part of writing a test suite for asynchronous code is figuring out
-        when a test is done, and feeling confident that all the code was ran.
+        when a test is done, and feeling confident that all the code was run.
         </p>
 
         <p>
@@ -320,7 +320,7 @@ <h2 id="wrap"><code>wrap()</code></h2>
         <p>
         <b>node-async-testing</b> comes with a convenience function for wrapping all tests
         in an object with setup/teardown functions. This function is called <code>wrap</code>
-        and it takes one argument which is an object with the following properties:
+        and it takes one argument which is an object which can have the following properties:
         </p>
 
         <dl>
@@ -334,21 +334,21 @@ <h2 id="wrap"><code>wrap()</code></h2>
           to pass additional data/objects to the test, you should set them on the
           <code>test</code> object directly.  Because <code>setup</code> might need
           to be asynchronous, you have to call the second argument, <code>done()</code>,
-          when it is finished.
+          when it is finished.  Optional.
           </dd>
 
           <dt><code>teardown(test, done)</code></dt>
           <dd>
           This function is run after every single test in the suite. <code>teardown</code>
           functions are called regardless of whether or not the test succeeds or
-          fails. It gets the same arguments as <code>setup</code>.
+          fails. It gets the same arguments as <code>setup</code>.  Optional.
           </dd>
 
           <dt><code>suiteSetup(done)</code></dt>
           <dd>
           This function is run <i>once</i> before any test in the suite.  Because
           <code>suiteSetup</code> might need to be asynchronous, you have to call the
-          only argument, <code>done()</code>, when it is finished.
+          only argument, <code>done()</code>, when it is finished.  Optional.
           </dd>
 
           <dt><code>suiteTeardown(done)</code></dt>
@@ -357,6 +357,7 @@ <h2 id="wrap"><code>wrap()</code></h2>
           finished. <code>suiteTeardown</code>
           functions are called regardless of whether or not the tests in the suite
           succeed or fail. It gets the same arguments as <code>suiteSetup</code>.
+          Optional.
           </dd>
         </dl>
 

lib/async_testing.js

@@ -10,12 +10,3 @@ exports.registerAssertion = testing.registerAssertion;
 
 var wrap = require('./wrap');
 exports.wrap = wrap.wrap;
-
-// deprecated
-exports.wrapTests = function(obj, wrapper) {
-  console.log('`wrapTests` is deprecated, use `wrap` instead');
-  for(var key in obj) {
-    obj[key] = wrapper(obj[key]);
-  }
-}
-