Permalink
Browse files

MOAR DOCS

  • Loading branch information...
1 parent 9ad5bf0 commit c7e4fe9781945e77564e6a63d289dac15cb204db Christian Johansen committed Feb 6, 2012
Showing with 312 additions and 8 deletions.
  1. +2 −2 site/docs/index.html
  2. +6 −6 site/docs/test/index.html
  3. +304 −0 site/docs/test/runner.html
View
@@ -58,15 +58,15 @@
<td>Resolves node modules from strings like <code>"module-name#prop-name"</code>.</td>
</tr>
<tr>
- <td><<a href="/docs/resources/">buster-resources</a></td>
+ <td><a href="/docs/resources/">buster-resources</a></td>
<td>Serialize parts of a file system and serve over a web server.</td>
</tr>
<tr>
<td><a href="/docs/capture-server/">buster-capture-server</a></td>
<td></td>
</tr>
<tr>
- <td><a href="/docs/test/">buster-test</a>></td>
+ <td><a href="/docs/test/">buster-test</a></td>
<td>Test runner, reporters, test cases and specs.</td>
</tr>
<tr>
View
@@ -4,9 +4,9 @@
<dd>0.1.0 <span class="date">(2011-03-23)</span></dd>
</dl>
<p>See specific documentation here:</p>
-<p><a href="/docs/test/reporters/">buster-test/reporters</a></p>
-<p><a href="/docs/test/spec/">buster-test/spec</a></p>
-<p><a href="/docs/test/stack-filter/">buster-test/stack-filter</a></p>
-<p><a href="/docs/test/test-case/">buster-test/test-case</a></p>
-<p><a href="/docs/test/context/">buster-test/context</a></p>
-<p><a href="/docs/test/test-runner/">buster-test/test-runner</a></p>
+<p><a href="/docs/test/reporters/">reporters</a></p>
+<p><a href="/docs/test/spec/">specs</a></p>
+<p><a href="/docs/test/stack-filter/">stack filter</a></p>
+<p><a href="/docs/test/test-case/">test cases</a></p>
+<p><a href="/docs/test/context/">test contexts</a></p>
+<p><a href="/docs/test/runner/">test runner</a></p>
View
@@ -0,0 +1,304 @@
+<div id="doc-nav"></div>
+<div id="doc-content">
+ <h1>buster.testRunner</h1>
+ <dl>
+ <dt>Version</dt>
+ <dd>See <a href="/docs/test/">buster-test</a></dd>
+ <dt>Module</dt>
+ <dd><code>require("buster-test").testRunner;</code></dd>
+ <dt>In browsers</dt>
+ <dd><code>buster.testRunner;</code></dd>
+ </dl>
+ <p>
+ Evented test runner for both synchronous and asynchronous tests. The
+ runner itself always executes asynchronously, making it very good at
+ visualizing ongoing progress and helps avoid long running script
+ warnings in browsers.
+ </p>
+ <pre><code>var testRunner = require("buster-test").testRunner;
+var xUnitConsoleReporter = require("buster-test").xUnitConsoleReporter;
+
+var runner = testRunner.<a href="#create">create</a>();
+var reporter = xUnitConsoleReporter.create({ color: true });
+reporter.listen(runner);
+
+runner.<a href="#runSuite">runSuite</a>([<a href="/docs/test/context/">context</a>, context2, ...]);</code></pre>
+ <div class="section">
+ <h2 id="events">Events</h2>
+ <h3 id="event-suite-start" data-title="+suite:start+">
+ Event: <code>"suite:start", function () {}</code>
+ </h3>
+ <p>
+ Emitted once, as the runner starts running a test suite (typically
+ when <a href="#runSuite"><code>runSuite</code></a> is called).
+ </p>
+ <h3 id="event-suite-end" data-title="+suite:end+">
+ Event: <code>"suite:end", function (<a href="#results"><code>results</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted once, when all contexts are run (typically when
+ <a href="#runSuite"><code>runSuite</code></a> completes).
+ </p>
+ <h3 id="event-context-start" data-title="+context:start+">
+ Event: <code>"context:start", function (<a href="/docs/test/context/"><code>context</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted every time
+ a <a href="/docs/test/context/"><code>context</code></a> is entered.
+ </p>
+ <h3 id="event-context-end" data-title="+context:end+">
+ Event: <code>"context:end", function (<a href="/docs/test/context/"><code>context</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted every time a context is completed.
+ </p>
+ <h3 id="event-context-unsupported" data-title="+context:unsupported+">
+ Event: <code>"context:unsupported", function (<a href="#unsupported"><code>ctx</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted every time a context fails its requirements (when that
+ happens, neither <code>context:start</code> or
+ <code>context:end</code> are emitted).
+ </p>
+ <h3 id="event-test-setUp" data-title="+test:setUp+">
+ Event: <code>"test:setUp", function (<a href="/docs/test/context/"><code>context</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted once per test before the setup method(s) for a test is called.
+ </p>
+ <h3 id="event-test-start" data-title="+test:start+">
+ Event: <code>"test:start", function (<a href="/docs/test/context/"><code>context</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted after running the test's setup(s), but before the test itself
+ runs.
+ </p>
+ <h3 id="event-test-async" data-title="+test:async+">
+ Event: <code>"test:async", function (<a href="/docs/test/context/#test"><code>test</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted when a test has been found to be asynchronous (usually means
+ that the test function was called and has returned).
+ </p>
+ <h3 id="event-test-tearDown" data-title="+test:tearDown+">
+ Event: <code>"test:tearDown", function (<a href="/docs/test/context/#test"><code>test</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted once per test before the tear down method(s) for a test is called.
+ </p>
+ <h3 id="event-test-failure" data-title="+test:failure+">
+ Event: <code>"test:failure", function (<a href="#error"><code>error</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted when the test throws (or <a href="#assertion-failure">otherwise
+ flags</a>) an <code>AssertionFailure</code>. Only emitted once per test.
+ </p>
+ <h3 id="event-test-error" data-title="+test:error+">
+ Event: <code>"test:error", function (<a href="#error"><code>error</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted when the test throws any error that is not an
+ <code>AssertionFailure</code>. Only emitted once per test.
+ </p>
+ <h3 id="event-test-success" data-title="+test:success+">
+ Event: <code>"test:success", function (<a href="/docs/test/context/#test"><code>test</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted if the test passes.
+ </p>
+ <h3 id="event-test-timeout" data-title="+test:timeout+">
+ Event: <code>"test:timeout", function (<a href="/docs/test/context/#test"><code>test</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted if the test runner forcefully aborts the test. This happens
+ when the test is asynchronous and does not resolve within the
+ <a href="#timeout">configured timeout</a>.
+ </p>
+ <h3 id="event-test-deferred" data-title="+test:deferred+">
+ Event: <code>"test:deferred", function (<a href="/docs/test/context/#test"><code>test</code></a>) {}</code>
+ </h3>
+ <p>
+ Emitted when a test is marked as deferred. The test is not run.
+ </p>
+ <h3 id="event-uncaughtException" data-title="+uncaughtException+">
+ Event: <code>"uncaughtException", function (<a href="#exception"><code>err</code></a>) {}</code>
+ </h3>
+ <p>
+ Uncaught errors are errors that the test runner is unable to associate
+ with the test that threw it. They occur in two situations:
+ </p>
+ <ol>
+ <li>
+ A synchronous test spawns an asynchronous task that results in an
+ error. For instance, calling <code>setTimeout</code> with a callback
+ that throws an error in a synchronous test.
+ </li>
+ <li>
+ An aborted asynchronous test throws (for instance, by failing an
+ assertion).
+ </li>
+ </ol>
+ <p>
+ The <code>"uncaughtException"</code> event will only be emitted when
+ the environment supports it and the <a href="#handleUncaughtExceptions"><code>handleUncaughtExceptions</code></a>
+ property is set to <code>true</code>. Browsers that do not support
+ <a href="https://developer.mozilla.org/en/DOM/window.onerror"><code>window.onerror</code></a>
+ are unable to support this feature.
+ </p>
+ </div>
+ <div class="section">
+ <h2 id="methods">Methods</h2>
+ <h3 id="create" data-title="+create([opts])+"><code>var runner = buster.testRunner.create([<a href="#properties">opts</a>]);</code></h3>
+ <p>
+ Creates a new test runner instance.
+ </p>
+ <h3 id="onCreate" data-title="+onCreate(callback)+"><code>buster.testRunner.onCreate(function (<a href="#create">runner</a>) {});</code></h3>
+ <p>
+ Register a callback which is called everytime a runner is created with
+ <a href="#create"><code>create</code></a>.
+ </p>
+ <h3 id="runSuite" data-title="+runSuite(contexts)+"><code><a href="#create">runner</a>.runSuite([<a href="/docs/test/context/">context</a>, context2, ...]);</code></h3>
+ <p>
+ Run an array of <a href="/docs/test/context/">context</a> objects as
+ a test suite.
+ </p>
+ <h3 id="run" data-title="+run(context)+"><code><a href="#create">runner</a>.run(<a href="/docs/test/context/">context</a>);</code></h3>
+ <p>
+ Run a single <a href="/docs/test/context/">context</a>. Note that this
+ method does not trigger
+ the <a href="#event-suite-start"><code>suite:start</code></a> event, and
+ using it instead of <code>runSuite</code> may cause unintended behavior in
+ <a href="/docs/test/reporters/">reporters</a>.
+ </p>
+ <h3 id="assertionCount" data-title="+assertionCount()+"><code>var count = <a href="#create">runner</a>.assertionCount();</code></h3>
+ <p>
+ The default implementation of this method is a no-op function. This
+ method is called by the runner after each test to determine the number
+ of assertions used in the test. It should not accumulate the assertion
+ count.
+ </p>
+ <p>
+ Because the runner itself has no knowledge of the assertion library,
+ this method is intended to be overridden by the assertion library in
+ use. For instance, this is the integration necessary to count
+ assertions with <a href="/docs/assertions/">buster-assertions</a>:
+ </p>
+ <pre><code>var assertions = 0;
+
+buster.assert.on("pass", function () {
+ assertions += 1;
+});
+
+buster.testRunner.onCreate(function (runner) {
+ runner.on("test:start", function () {
+ assertions = 0;
+ });
+});
+
+buster.testRunner.assertionCount = function () {
+ return assertions;
+};</code></pre>
+ <h3 id="assertionFailure" data-title="+assertionFailure()+"><code><a href="#create">runner</a>.assertionFailure(<a href="#exception">exception</a>);</code></h3>
+ <p>
+ Can be called from assertion libraries that do not throw an exception
+ on assertion failure. For assertion failures to be picked up no matter
+ what in asynchronous tests, this method needs to be called, as some
+ exceptions are not possible for the runner to catch.
+ </p>
+ </div>
+ <div class="section">
+ <h2 id="properties">Properties</h2>
+ <p>
+ Test runner properties can be set when creating an instance, or simply
+ by assigning to the property on an existing runner.
+ </p>
+ <pre><code>var runner = buster.testRunner.create({
+ timeout: 500
+});
+
+// Or:
+
+var runner = buster.testRunner.create();
+runner.timeout = 500;</code></pre>
+ <h3 id="failOnNoAssertions" data-title="+failOnNoAssertions+">
+ <code>failOnNoAssertions</code> (<code>true</code>)
+ </h3>
+ <p>
+ When <code>true</code>, a test with no assertions is considered a
+ failure. The number of assertions are measured with
+ <a href="#assertionCount">assertionCount</a>.
+ </p>
+ <h3 id="timeout" data-title="+timeout+">
+ <code>timeout</code> (<code>250</code>)
+ </h3>
+ <p>
+ When an asynchronous test runs for more than <code>timeout</code> ms, the
+ runner will abort it and emit
+ a <a href="#event-test-timeout"><code>test:timeout</code></a> event.
+ </p>
+ <h3 id="handleUncaughtExceptions" data-title="+handleUncaughtExceptions+">
+ <code>handleUncaughtExceptions</code> (<code>true</code>)
+ </h3>
+ <p>
+ When <code>true</code>, the runner will attempt to
+ handle <a href="#uncaughtException">uncaught exceptions</a>, by
+ registering a listener on <code>process</code> for
+ <a href="http://nodejs.org/docs/v0.4.0/api/process.html#event_uncaughtException_"><code>"uncaughtException"</code></a>
+ (node.js) and assigning a callback to
+ <a href="https://developer.mozilla.org/en/DOM/window.onerror"><code>window.onerror</code></a> (browsers).
+ </p>
+ </div>
+ <div class="section">
+ <h2 id="supporting-objects">Supporting objects</h2>
+ <h3 id="results"><code>results</code></h3>
+ <p>
+ A high-level numeric report. Emitted
+ with <a href="#event-suite-end"><code>suite:end</code></a>.
+ </p>
+ <pre><code>{
+ contexts: 0,
+ tests: 0,
+ errors: 0,
+ failures: 0,
+ assertions: 0,
+ timeouts: 0,
+ deferred: 0
+}</code></pre>
+ <h3 id="error"><code>error</code></h3>
+ <p>
+ An object representing a test failure (or error), emitted with
+ <a href="#event-test-failure"><code>test:failure</code></a> and
+ <a href="#event-test-error"><code>test:error</code></a>.
+ </p>
+ <pre><code>{
+ name: "Name of test",
+ error: {
+ name: "Type of exception",
+ message: "Exception message",
+ stack: "Stack trace as string"
+ }
+}</code></pre>
+ <h3 id="exception"><code>exception</code></h3>
+ <p>
+ An exception-like object, emitted with
+ <a href="#event-uncaughtException"><code>uncaughtException</code></a>.
+ In browsers, this object does not have a stack trace.
+ </p>
+ <pre><code>{
+ name: "Type of exception",
+ message: "Exception message",
+ stack: "Stack trace as string"
+}</code></pre>
+ <h3 id="unsupported"><code>unsupported</code></h3>
+ <p>
+ Information about an unsupported context. Emitted with
+ <a href="#event-context-unsupported"><code>context:unsupported</code></a>.
+ Contains an array of names of failed
+ requirements and a context object.
+ </p>
+ <pre><code>{
+ context: <a href="/docs/test/context/">context</a>,
+unsupported: ["label1", "label2"]
+}</code></pre>
+ </div>
+</div>

0 comments on commit c7e4fe9

Please sign in to comment.