<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Mocha - the fun, simple, flexible JavaScript test framework</title>
    <link rel="stylesheet" href="normalize.min.css">
    <link rel="stylesheet" href="style.css">
    <link rel="shortcut icon" href="favicon.ico">
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js"></script>
    <script>window.jQuery || document.write('<script src="jquery.js"><\/script>')</script>
    <script src="highlight.js"></script>
    <script>
      setTimeout(function(){
        $('body').addClass('onload');
      }, 0);
    </script>
    <!--[if lt IE 9]>
    <script src="html5shiv.js"></script>
    <![endif]-->
  </head>
  <body>
    <section id="content">
      <h1><a href="https://github.com/visionmedia/mocha">Mocha</a></h1>
      <p id="tag"><em>simple</em>, <em>flexible</em>, <em>fun</em></p>
<p>Mocha is a feature-rich JavaScript test framework running on <a href="http://nodejs.org">node.js</a> and the browser, making asynchronous testing simple and fun. Mocha tests run serially, allowing for flexible and accurate reporting, while mapping uncaught exceptions to the correct test cases. Hosted on <a href="https://github.com/visionmedia/mocha">GitHub</a>.</p>

<h2 id="features">Features</h2>

<ul>
<li>browser support</li>
<li>simple async support</li>
<li>test coverage reporting</li>
<li>string diff support</li>
<li>javascript API for running tests</li>
<li>proper exit status for CI support etc</li>
<li>auto-detects and disables coloring for non-ttys</li>
<li>maps uncaught exceptions to the correct test case</li>
<li>async test timeout support</li>
<li>test-specific timeouts</li>
<li>growl notification support</li>
<li>reports test durations</li>
<li>highlights slow tests</li>
<li>file watcher support</li>
<li>global variable leak detection</li>
<li>optionally run tests that match a regexp</li>
<li>auto-exit to prevent "hanging" with an active loop</li>
<li>easily meta-generate suites &amp; test-cases</li>
<li>mocha.opts file support</li>
<li>clickable suite titles to filter test execution</li>
<li>node debugger support</li>
<li>detects multiple calls to <code>done()</code></li>
<li>use any assertion library you want</li>
<li>extensible reporting, bundled with 9+ reporters</li>
<li>extensible test DSLs or "interfaces"</li>
<li>before, after, before each, after each hooks</li>
<li>arbitrary transpiler support (coffee-script etc)</li>
<li>TextMate bundle</li>
<li>and more!</li>
</ul>

<h2 id="table-of-contents">Table of contents</h2>

<ul>
<li><a href="index.html#installation">Installation</a></li>
<li><a href="index.html#getting-started">1. 2. 3. Mocha!</a></li>
<li><a href="index.html#assertions">Assertions</a></li>
<li><a href="index.html#synchronous-code">Synchronous code</a></li>
<li><a href="index.html#asynchronous-code">Asynchronous code</a></li>
<li><a href="index.html#pending-tests">Pending tests</a></li>
<li><a href="index.html#exclusive-tests">Exclusive tests</a></li>
<li><a href="index.html#inclusive-tests">Inclusive tests</a></li>
<li><a href="index.html#test-duration">Test duration</a></li>
<li><a href="index.html#string-diffs">String diffs</a></li>
<li><a href="index.html#usage">mocha(1)</a></li>
<li><a href="index.html#interfaces">Interfaces</a></li>
<li><a href="index.html#reporters">Reporters</a></li>
<li><a href="index.html#browser-support">Browser support</a></li>
<li><a href="index.html#mocha.opts">mocha.opts</a></li>
<li><a href="index.html#suite-specific-timeouts">Suite specific timeouts</a></li>
<li><a href="index.html#test-specific-timeouts">Test specific timeouts</a></li>
<li><a href="index.html#best-practices">Best practices</a></li>
<li><a href="index.html#editors">Editors</a></li>
<li><a href="index.html#example-test-suites">Example test suites</a></li>
<li><a href="index.html#running-mochas-tests">Running mocha's tests</a></li>
<li><a href="index.html#more-information">More information</a></li>
</ul>

<h2 id="installation">Installation</h2>

<p>Install with <a href="http://npmjs.org">npm</a>:</p>

<pre><code>$ npm install -g mocha
</code></pre>

<h2 id="getting-started">1. 2. 3. Mocha!</h2>

<pre><code>$ npm install -g mocha
$ mkdir test
$ $EDITOR test/test.js

var assert = require("assert")
describe('Array', function(){
  describe('#indexOf()', function(){
    it('should return -1 when the value is not present', function(){
      assert.equal(-1, [1,2,3].indexOf(5));
      assert.equal(-1, [1,2,3].indexOf(0));
    })
  })
})

$  mocha

  .

  ✔ 1 test complete (1ms)
</code></pre>

<h2 id="assertions">Assertions</h2>

<p>Mocha allows you to use any assertion library you want, if it throws an error, it will work! This means you can utilize libraries such as <a href="https://github.com/visionmedia/should.js">should.js</a>, node's regular <code>assert</code> module, or others. The following is a list of known assertion libraries for node and/or the browser:</p>

<ul>
<li><a href="https://github.com/visionmedia/should.js">should.js</a> BDD style shown throughout these docs</li>
<li><a href="https://github.com/LearnBoost/expect.js">expect.js</a> expect() style assertions</li>
<li><a href="http://chaijs.com/">chai</a> expect(), assert() and should style assertions</li>
<li><a href="https://github.com/visionmedia/better-assert">better-assert</a> c-style self-documenting assert()</li>
</ul>

<h2 id="synchronous-code">Synchronous code</h2>

<p>When testing synchronous code, omit the callback and Mocha will automatically continue on to the next test.</p>

<pre><code>describe('Array', function(){
  describe('#indexOf()', function(){
    it('should return -1 when the value is not present', function(){
      [1,2,3].indexOf(5).should.equal(-1);
      [1,2,3].indexOf(0).should.equal(-1);
    })
  })
})
</code></pre>

<h2 id="asynchronous-code">Asynchronous code</h2>

<p>Testing asynchronous code with Mocha could not be simpler! Simply invoke the callback when your test is complete. By adding a callback (usually named <code>done</code>) to <code>it()</code> Mocha will know that it should wait for completion.</p>

<pre><code>describe('User', function(){
  describe('#save()', function(){
    it('should save without error', function(done){
      var user = new User('Luna');
      user.save(function(err){
        if (err) throw err;
        done();
      });
    })
  })
})
</code></pre>

<p>To make things even easier, the <code>done()</code> callback accepts an error, so we may use this directly:</p>

<pre><code>describe('User', function(){
  describe('#save()', function(){
    it('should save without error', function(done){
      var user = new User('Luna');
      user.save(done);
    })
  })
})
</code></pre>

<p>All "hooks", that is <code>before()</code>, <code>after()</code>, <code>beforeEach()</code>, <code>afterEach()</code> may be sync or async as well, behaving much like a regular test-case. For example you may wish to populate database with dummy content before each test:</p>

<pre><code>describe('Connection', function(){
  var db = new Connection
    , tobi = new User('tobi')
    , loki = new User('loki')
    , jane = new User('jane');

  beforeEach(function(done){
    db.clear(function(err){
      if (err) return done(err);
      db.save([tobi, loki, jane], done);
    });
  })

  describe('#find()', function(){
    it('respond with matching records', function(done){
      db.find({ type: 'User' }, function(err, res){
        if (err) return done(err);
        res.should.have.length(3);
        done();
      })
    })
  })
})
</code></pre>

<p>You may also pick any file and add "root" level hooks, for example add <code>beforeEach()</code> outside of <code>describe()</code>s then the callback will run before any test-case regardless of the file its in. This is because Mocha has a root <code>Suite</code> with no name.</p>

<pre><code>beforeEach(function(){
  console.log('before every test')
})
</code></pre>

<h2 id="pending-tests">Pending tests</h2>

<p>Pending test-cases are simply those without a callback:</p>

<pre><code>describe('Array', function(){
  describe('#indexOf()', function(){
    it('should return -1 when the value is not present')
  })
})
</code></pre>

<h2 id="exclusive-tests">Exclusive tests</h2>

<p>The exclusivity feature allows you to run only the specified suite or test-case
 by appending <code>.only()</code> to the call as shown here:</p>

<pre><code>describe('Array', function(){
  describe.only('#indexOf()', function(){
    ...
  })
})
</code></pre>

<p>Or a specific test-case:</p>

<pre><code>describe('Array', function(){
  describe('#indexOf()', function(){
    it.only('should return -1 unless present', function(){

    })

    it('should return the index when present', function(){

    })
  })
})
</code></pre>

<p>Note that currently only one <code>.only()</code> call is respected, this
  effectively turns into a <code>--grep</code>.</p>

<h2 id="inclusive-tests">Inclusive tests</h2>

<p>This feature is similar to <code>.only()</code>, however by appending <code>.skip()</code>
 you may tell Mocha to simply ignore these suite(s) and test-case(s). This
 puts them in a pending state, and is favoured over commenting out tests
 which you may forget to uncomment.</p>

<pre><code>describe('Array', function(){
  describe.skip('#indexOf()', function(){
    ...
  })
})
</code></pre>

<p>Or a specific test-case:</p>

<pre><code>describe('Array', function(){
  describe('#indexOf()', function(){
    it.skip('should return -1 unless present', function(){

    })

    it('should return the index when present', function(){

    })
  })
})
</code></pre>

<h2 id="test-duration">Test duration</h2>

<p>Most of the reporters support some form of displaying
  test duration, as well as flagging tests that are slow,
  as shown here with the "spec" reporter:</p>

<p><img src="images/reporter-spec-duration.png" alt="test duration" title="" /></p>

<h2 id="string-diffs">String diffs</h2>

<p>Mocha supports the <code>err.expected</code>, and <code>err.actual</code> properties
  when available to present expectations to the developer. Currently
  Mocha provides string diffs, however in the future object diffs and
  others may be provided.</p>

<p><img src="images/reporter-string-diffs.png" alt="string diffs" title="" /></p>

<h2 id="usage">mocha(1)</h2>

<pre><code>Usage: mocha [debug] [options] [files]

Commands:

  init &lt;path&gt;
  initialize a client-side mocha setup at &lt;path&gt;

Options:

  -h, --help                      output usage information
  -V, --version                   output the version number
  -r, --require &lt;name&gt;            require the given module
  -R, --reporter &lt;name&gt;           specify the reporter to use
  -u, --ui &lt;name&gt;                 specify user-interface (bdd|tdd|exports)
  -g, --grep &lt;pattern&gt;            only run tests matching &lt;pattern&gt;
  -i, --invert                    inverts --grep matches
  -t, --timeout &lt;ms&gt;              set test-case timeout in milliseconds [2000]
  -s, --slow &lt;ms&gt;                 "slow" test threshold in milliseconds [75]
  -w, --watch                     watch files for changes
  -c, --colors                    force enabling of colors
  -C, --no-colors                 force disabling of colors
  -G, --growl                     enable growl notification support
  -d, --debug                     enable node's debugger, synonym for node --debug
  -b, --bail                      bail after first test failure
  -A, --async-only                force all tests to take a callback (async)
  --recursive                     include sub directories
  --debug-brk                     enable node's debugger breaking on the first line
  --globals &lt;names&gt;               allow the given comma-delimited global [names]
  --check-leaks                   check for global variable leaks
  --interfaces                    display available interfaces
  --reporters                     display available reporters
  --compilers &lt;ext&gt;:&lt;module&gt;,...  use the given module(s) to compile files
</code></pre>

<h3 id="watch-option">-w, --watch</h3>

<p>Executes tests on changes to JavaScript in the CWD, and once initially.</p>

<h3 id="compilers-option">--compilers</h3>

<p>coffee-script is no longer supported out of the box. CS and similar transpilers
  may be used by mapping the file extensions (for use with --watch) and the module
  name. For example <code>--compilers coffee:coffee-script</code>.</p>

<h3 id="bail-option">-b, --bail</h3>

<p>Only interested in the first exception? use <code>--bail</code> !</p>

<h3 id="debug-option">-d, --debug</h3>

<p>Enables node's debugger support, this executes your script(s) with <code>node debug &lt;file ...&gt;</code> allowing you to step through code and break with the <strong>debugger</strong> statement.</p>

<h3 id="globals-option">--globals &lt;names&gt;</h3>

<p>Accepts a comma-delimited list of accepted global variable names. For example suppose your app deliberately exposes a global named <code>app</code> and <code>YUI</code>, you may want to add <code>--globals app,YUI</code>.</p>

<h3 id="ignore-leaks-option">--check-leaks</h3>

<p>By default Mocha will not check for global variables leaked while running tests, to enable this pass <code>--check-leaks</code>, to specify globals that are acceptable use <code>--globals</code>, for example <code>--globals jQuery,MyLib</code>.</p>

<h3 id="require-option">-r, --require &lt;name&gt;</h3>

<p>The <code>--require</code> option is useful for libraries such as <a href="https://github.com/visionmedia/should.js">should.js</a>, so you may simply <code>--require should</code> instead of manually invoking <code>require('should')</code> within each test file. Note that this works well for <code>should</code> as it augments <code>Object.prototype</code>, however if you wish to access a module's exports you will have to require them, for example <code>var should = require('should')</code>.</p>

<h3 id="ui-option">-u, --ui &lt;name&gt;</h3>

<p>The <code>--ui</code> option lets you specify the interface to use, defaulting to "bdd".</p>

<h3 id="reporter-option">-R, --reporter &lt;name&gt;</h3>

<p>The <code>--reporter</code> option allows you to specify the reporter that will be used, defaulting to "dot". This flag may also be used to utilize third-party reporters. For example if you <code>npm install mocha-lcov-reporter</code> you may then do <code>--reporter mocha-lcov-reporter</code>.</p>

<h3 id="timeout-option">-t, --timeout &lt;ms&gt;</h3>

<p>Specifies the test-case timeout, defaulting to 2 seconds. To override you may pass the timeout in milliseconds, or a value with the <code>s</code> suffix, ex: <code>--timeout 2s</code> or <code>--timeout 2000</code> would be equivalent.</p>

<h3 id="slow-option">-s, --slow &lt;ms&gt;</h3>

<p>Specify the "slow" test threshold, defaulting to 75ms. Mocha uses this to highlight test-cases that are taking too long.</p>

<h3 id="grep-option">-g, --grep &lt;pattern&gt;</h3>

<p>The <code>--grep</code> option when specified will trigger mocha to only run tests matching the given <code>pattern</code> which is internally compiled to a <code>RegExp</code>.</p>

<p>Suppose for example you have "api" related tests, as well as "app" related tests, as shown in the following snippet; One could use <code>--grep api</code> or <code>--grep app</code> to run one or the other. The same goes for any other part of a suite or test-case title, <code>--grep users</code> would be valid as well, or even <code>--grep GET</code>.</p>

<pre><code>describe('api', function(){
  describe('GET /api/users', function(){
    it('respond with an array of users')
  })
})

describe('app', function(){
  describe('GET /users', function(){
    it('respond with an array of users')
  })
})
</code></pre>

<h2 id="interfaces">Interfaces</h2>

<p>Mocha "interface" system allows developers to choose their style of DSL. Shipping with <strong>BDD</strong>, <strong>TDD</strong>, and <strong>exports</strong> flavoured interfaces.</p>

<h3 id="bdd-interface">BDD</h3>

<p>The "<strong>BDD</strong>" interface provides <code>describe()</code>, <code>it()</code>, <code>before()</code>, <code>after()</code>, <code>beforeEach()</code>, and <code>afterEach()</code>:</p>

<pre><code>describe('Array', function(){
  before(function(){
    // ...
  });

  describe('#indexOf()', function(){
    it('should return -1 when not present', function(){
      [1,2,3].indexOf(4).should.equal(-1);
    });
  });
});
</code></pre>

<h3 id="tdd-interface">TDD</h3>

<p>The "<strong>TDD</strong>" interface provides <code>suite()</code>, <code>test()</code>, <code>setup()</code>, <code>teardown()</code>, <code>suiteSetup()</code>, and <code>suiteTeardown()</code>.</p>

<pre><code>suite('Array', function(){
  setup(function(){
    // ...
  });

  suite('#indexOf()', function(){
    test('should return -1 when not present', function(){
      assert.equal(-1, [1,2,3].indexOf(4));
    });
  });
});
</code></pre>

<h3 id="exports-interface">Exports</h3>

<p>The "<strong>exports</strong>" interface is much like Mocha's predecessor <a href="https://github.com/visionmedia/expresso">expresso</a>. The keys <code>before</code>, <code>after</code>, <code>beforeEach</code>, and <code>afterEach</code> are special-cased, object values
  are suites, and function values are test-cases.</p>

<pre><code>module.exports = {
  before: function(){
    // ...
  },

  'Array': {
    '#indexOf()': {
      'should return -1 when not present': function(){
        [1,2,3].indexOf(4).should.equal(-1);
      }
    }
  }
};
</code></pre>

<h3 id="qunit-interface">QUnit</h3>

<p>The qunit-inspired interface matches the "flat" look of QUnit where the test suite title is simply defined before the test-cases.</p>

<pre><code>function ok(expr, msg) {
  if (!expr) throw new Error(msg);
}

suite('Array');

test('#length', function(){
  var arr = [1,2,3];
  ok(arr.length == 3);
});

test('#indexOf()', function(){
  var arr = [1,2,3];
  ok(arr.indexOf(1) == 0);
  ok(arr.indexOf(2) == 1);
  ok(arr.indexOf(3) == 2);
});

suite('String');

test('#length', function(){
  ok('foo'.length == 3);
});
</code></pre>

<h2 id="reporters">Reporters</h2>

<p>Mocha reporters adjust to the terminal window,
  and always disable ansi-escape colouring when
  the stdio streams are not associated with a tty.</p>

<h3 id="dot-matrix-reporter">Dot Matrix</h3>

<p>The "dot" matrix reporter is simply a series of dots
  that represent test cases, failures highlight in red,
  pending in blue, slow as yellow.</p>

<p><img src="images/reporter-dot.png" alt="dot matrix reporter" title="" /></p>

<h3 id="spec-reporter">Spec</h3>

<p>The "spec" reporter outputs a hierarchical view
  nested just as the test cases are.</p>

<p><img src="images/reporter-spec.png" alt="spec reporter" title="" />
   <img src="images/reporter-spec-fail.png" alt="spec reporter with failure" title="" /></p>

<h3 id="nyan-reporter">Nyan</h3>

<p>The "nyan" reporter is exactly what you might expect:</p>

<p><img src="images/reporter-nyan.png" alt="js nyan cat reporter" title="" /></p>

<h3 id="tap-reporter">TAP</h3>

<p>The TAP reporter emits lines for a <a href="http://en.wikipedia.org/wiki/Test_Anything_Protocol">Test-Anything-Protocol</a> consumer.</p>

<p><img src="images/reporter-tap.png" alt="test anything protocol" title="" /></p>

<h3 id="landing-strip-reporter">Landing Strip</h3>

<p>The Landing Strip reporter is a gimmicky test reporter simulating
  a plane landing :) unicode ftw</p>

<p><img src="images/reporter-landing.png" alt="landing strip plane reporter" title="" />
  <img src="images/reporter-landing-fail.png" alt="landing strip with failure" title="" /></p>

<h3 id="list-reporter">List</h3>

<p>The "List" reporter outputs a simple specifications list as
  test cases pass or fail, outputting the failure details at
  the bottom of the output.</p>

<p><img src="images/reporter-list.png" alt="list reporter" title="" /></p>

<h3 id="progress-reporter">Progress</h3>

<p>The progress reporter implements a simple progress-bar:</p>

<p><img src="images/reporter-progress.png" alt="progress bar" title="" /></p>

<h3 id="json-reporter">JSON</h3>

<p>The JSON reporter outputs a single large JSON object when
  the tests have completed (failures or not).</p>

<p><img src="images/reporter-json.png" alt="json reporter" title="" /></p>

<h3 id="json-stream-reporter">JSON Stream</h3>

<p>The JSON Stream reporter outputs newline-delimited JSON "events" as they occur, beginning with a "start" event, followed by test passes or failures, and then the final "end" event.</p>

<p><img src="images/reporter-json-stream.png" alt="json stream reporter" title="" /></p>

<h3 id="jsoncov-reporter">JSONCov</h3>

<p>The JSONCov reporter is similar to the JSON reporter, however when run against a library instrumented by <a href="https://github.com/visionmedia/node-jscoverage">node-jscoverage</a> it will produce coverage output.</p>

<h3 id="htmlcov-reporter">HTMLCov</h3>

<p>The HTMLCov reporter extends the JSONCov reporter. The library being tested should first be instrumented by <a href="https://github.com/visionmedia/node-jscoverage">node-jscoverage</a>, this allows Mocha to capture the coverage information necessary to produce a single-page HTML report.</p>

<p>Click to view the current <a href="coverage.html">Express test coverage</a> report. For an integration example view the mocha test coverage support <a href="https://github.com/visionmedia/express/commit/b6ee5fafd0d6c79cf7df5560cb324ebee4fe3a7f">commit</a> for Express.</p>

<p><img src="images/reporter-htmlcov.png" alt="code coverage reporting" title="" /></p>

<h3 id="min-reporter">Min</h3>

<p>The "min" reporter displays the summary only, while still outputting errors
  on failure. This reporter works great with <code>--watch</code> as it clears the terminal
  in order to keep your test summary at the top.</p>

<p><img src="images/reporter-min.png" alt="min reporter" title="" /></p>

<h3 id="doc-reporter">Doc</h3>

<p>The "doc" reporter outputs a hierarchical HTML body representation
 of your tests, wrap it with a header, footer, some styling and you
 have some fantastic documentation!</p>

<p><img src="images/reporter-doc.png" alt="doc reporter" title="" /></p>

<p>For example suppose you have the following JavaScript:</p>

<pre><code>describe('Array', function(){
  describe('#indexOf()', function(){
    it('should return -1 when the value is not present', function(){
      [1,2,3].indexOf(5).should.equal(-1);
      [1,2,3].indexOf(0).should.equal(-1);
    })
  })
})
</code></pre>

<p>The command <code>mocha --reporter doc array</code> would yield:</p>

<pre><code>&lt;section class="suite"&gt;
  &lt;h1&gt;Array&lt;/h1&gt;
  &lt;dl&gt;
    &lt;section class="suite"&gt;
      &lt;h1&gt;#indexOf()&lt;/h1&gt;
      &lt;dl&gt;
      &lt;dt&gt;should return -1 when the value is not present&lt;/dt&gt;
      &lt;dd&gt;&lt;pre&gt;&lt;code&gt;[1,2,3].indexOf(5).should.equal(-1);
[1,2,3].indexOf(0).should.equal(-1);&lt;/code&gt;&lt;/pre&gt;&lt;/dd&gt;
      &lt;/dl&gt;
    &lt;/section&gt;
  &lt;/dl&gt;
&lt;/section&gt;
</code></pre>

<p>The SuperAgent request library <a href="../superagent/docs/test.html">test documentation</a> was generated with Mocha's doc reporter using this simple make target:</p>

<pre><code>test-docs:
    make test REPORTER=doc \
        | cat docs/head.html - docs/tail.html \
        &gt; docs/test.html
</code></pre>

<p>View the entire <a href="https://github.com/visionmedia/superagent/blob/master/Makefile">Makefile</a> for reference.</p>

<h3 id="xunit-reporter">XUnit</h3>

<p>Documentation needed.</p>

<h3 id="teamcity-reporter">TeamCity</h3>

<p>Documentation needed.</p>

<h3 id="markdown-reporter">Markdown</h3>

<p>The "markdown" reporter generates a markdown TOC and body for your
  test suite. This is great if you want to use the tests as documentation
  within a Github wiki page, or a markdown file in the repository that
  Github can render. For example here is the Connect <a href="https://github.com/senchalabs/connect/blob/90a725343c2945aaee637e799b1cd11e065b2bff/tests.md">test output</a>.</p>

<h3 id="html-reporter">HTML</h3>

<p>The <strong>HTML</strong> reporter is currently the only browser reporter
 supported by Mocha, and it looks like this:</p>

<p><img src="images/reporter-html.png" alt="HTML test reporter" title="" /></p>

<h2 id="browser-support">Browser support</h2>

<p>Mocha runs in the browser. Every release of Mocha will have new builds of <em>./mocha.js</em> and <em>./mocha.css</em> for use in the browser. To setup Mocha for browser use all you have to do is include the script, stylesheet, tell Mocha which interface you wish to use, and then run the tests. A typical setup might look something like the following, where we call <code>mocha.setup('bdd')</code> to use the <strong>BDD</strong> interface before loading the test scripts, running them <code>onload</code> with <code>mocha.run()</code>.</p>

<pre><code>&lt;html&gt;
&lt;head&gt;
  &lt;meta charset="utf-8"&gt;
  &lt;title&gt;Mocha Tests&lt;/title&gt;
  &lt;link rel="stylesheet" href="mocha.css" /&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;div id="mocha"&gt;&lt;/div&gt;
  &lt;script src="jquery.js"&gt;&lt;/script&gt;
  &lt;script src="expect.js"&gt;&lt;/script&gt;
  &lt;script src="mocha.js"&gt;&lt;/script&gt;
  &lt;script&gt;mocha.setup('bdd')&lt;/script&gt;
  &lt;script src="test.array.js"&gt;&lt;/script&gt;
  &lt;script src="test.object.js"&gt;&lt;/script&gt;
  &lt;script src="test.xhr.js"&gt;&lt;/script&gt;
  &lt;script&gt;
    mocha.checkLeaks();
    mocha.globals(['jQuery']);
    mocha.run();
  &lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;
</code></pre>

<h3 id="grep-query">grep</h3>

<p>The client-side may utilize <code>--grep</code> as well, however you use the query-string, for example <code>?grep=api</code>.</p>

<h2 id="mocha.opts">mocha.opts</h2>

<p>Mocha will attempt to load <code>./test/mocha.opts</code>, these are concatenated with <code>process.argv</code>, though command-line args will take precedence. For example suppose you have the following <em>mocha.opts</em> file:</p>

<pre><code>--require should
--reporter dot
--ui bdd
</code></pre>

<p>This will default the reporter to <code>dot</code>, require the <code>should</code> library,
  and use <code>bdd</code> as the interface. With this you may then invoke <code>mocha(1)</code>
  with additional arguments, here enabling growl support and changing
  the reporter to <code>spec</code>:</p>

<pre><code>$ mocha --reporter list --growl
</code></pre>

<h2 id="suite-specific-timeouts">Suite specific timeouts</h2>

<p>Suite-level timeouts may be applied to entire test "suites", or disabled
  via <code>this.timeout(0)</code>. This will be inherited by all nested suites and test-cases
  that do not override the value.</p>

<pre><code>describe('a suite of tests', function(){
  this.timeout(500);

  it('should take less than 500ms', function(done){
    setTimeout(done, 300);
  })

  it('should take less than 500ms as well', function(done){
    setTimeout(done, 200);
  })
})
</code></pre>

<h2 id="test-specific-timeouts">Test specific timeouts</h2>

<p>Test-specific timeouts may also be applied, or the use of <code>this.timeout(0)</code>
  to disable timeouts all together:</p>

<pre><code>it('should take less than 500ms', function(done){
  this.timeout(500);
  setTimeout(done, 300);
})
</code></pre>

<h2 id="best-practices">Best practices</h2>

<h3 id="test-directory">test/*</h3>

<p>By default <code>mocha(1)</code> will use the pattern <code>./test/*.js</code>, so
 it's usually a good place to put your tests.</p>

<h3 id="makefiles">Makefiles</h3>

<p>Be kind and don't make developers hunt around in your docs to figure
 out how to run the tests, add a <code>make test</code> target to your <em>Makefile</em>:</p>

<pre><code>test:
   ./node_modules/.bin/mocha --reporter list

 .PHONY: test
</code></pre>

<h2 id="editors">Editors</h2>

<p>The following editor-related packages are available:</p>

<h3 id="textmate-bundle">TextMate bundle</h3>

<p>The Mocha TextMate bundle includes snippets to
  make writing tests quicker and more enjoyable.
  To install the bundle run:</p>

<pre><code>$ make tm
</code></pre>

<h2 id="example-test-suites">Example test suites</h2>

<p>The following test suites are from real projects putting Mocha to use,
  so they serve as good examples:</p>

<ul>
<li><a href="https://github.com/visionmedia/express/tree/master/test">Express</a></li>
<li><a href="https://github.com/senchalabs/connect/tree/master/test">Connect</a></li>
<li><a href="https://github.com/visionmedia/superagent/tree/master/test/node">SuperAgent</a></li>
<li><a href="https://github.com/LearnBoost/websocket.io/tree/master/test">WebSocket.io</a></li>
<li><a href="https://github.com/visionmedia/mocha/tree/master/test">Mocha</a></li>
</ul>

<h2 id="running-mochas-tests">Running mocha's tests</h2>

<p>Run the tests:</p>

<pre><code>$ make test
</code></pre>

<p>Run all tests, including interfaces:</p>

<pre><code>$ make test-all
</code></pre>

<p>Alter the reporter:</p>

<pre><code>$ make test REPORTER=list
</code></pre>

<h2 id="more-information">More information</h2>

<p>For additional information such as using spies, mocking, and shared behaviours be sure to check out the <a href="https://github.com/visionmedia/mocha/wiki">Mocha Wiki</a> on GitHub. For discussions join the <a href="http://groups.google.com/group/mochajs">Google Group</a>. For a running example of mocha view <a href="example/tests.html">example/tests.html</a>. For the JavaScript API view the <a href="https://github.com/visionmedia/mocha/blob/master/lib/mocha.js#L51">source</a>.</p>
    </section>
    <footer>
      <span>© 2011 TJ Holowaychuk. All rights reserved.</span>
    </footer>
  </body>
</html>