Skip to content
This repository has been archived by the owner on Feb 26, 2022. It is now read-only.

Commit

Permalink
Bug 569711 - convert unit-test.md to apidocs format. r=adw, a0.7=myk
Browse files Browse the repository at this point in the history
  • Loading branch information
@fiveinchpixie
fiveinchpixie committed Aug 19, 2010
1 parent 2bbcdb9 commit 6a3cdf8
Showing 1 changed file with 129 additions and 60 deletions.
189 changes: 129 additions & 60 deletions packages/jetpack-core/docs/unit-test.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
<!-- contributed by Atul Varma [atul@mozilla.com] -->
<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] -->


The `unit-test` module makes it easy to find and run unit tests.

## Test Runner Objects ##
Expand All @@ -6,89 +10,154 @@ Each function which represents a test case is passed a single argument
`test`, which represents the test runner. It has the following
methods:

<code>test.**pass**([*message*])</code>
<api name="pass">
@method
Marks a test as passing, with the given optional message.

Marks a test as passing, with the given optional message.
@param [message] {string}
Optional passing message.
</api>

<code>test.**fail**([*message*])</code>

Marks a test as failing, with the given optional message.
<api name="fail">
@method
Marks a test as failing, with the given optional message.

<code>test.**exception**(*e*)</code>
@param [message] {string}
Optional failure message.
</api>

Marks a test as failing due to the given exception having been thrown.
This can be put in a `catch` clause.

<code>test.**assert**(*a*[, *message*])</code>
<api name="exception">
@method
Marks a test as failing due to the given exception having been thrown.
This can be put in a `catch` clause.

Ensures that *a* has a truthy value. A test is marked as passing or
failing depending on the result, logging *message* with it.
@param e {exception}
An exception.
</api>

<code>test.**assertEqual**(*a*, *b*[, *message*])</code>
<api name="assert">
@method
Ensures that `a` has a truthy value.

Simply ensures that *a* `==` *b* without recursing into
*a* or *b*. A test is marked as passing or failing depending on
the result, logging *message* with it.
@param a {value}
Value to verify.
@param [message] {string}
The test is marked as passing or failing depending on the result, logging
*message* with it.
</api>

<code>test.**assertNotEqual**(*a*, *b*[, *message*])</code>

Simply ensures that *a* `!=` *b* without recursing into
*a* or *b*. A test is marked as passing or failing depending on
the result, logging *message* with it.
<api name="assertEqual">
@method
Simply ensures that `a == b` without recursing into `a` or `b`.

<code>test.**assertMatches**(*string*, *regexp*[, *message*])</code>
@param a {value}
A value.

Ensures that the given string matches the given regular expression.
If it does, marks a test as passing, otherwise marks a test as
failing. *message* is logged with the pass or fail.
@param b {value}
Another value.

<code>test.**assertRaises**(*func*, *predicate*[, *message*])</code>
@param [message] {string}
The test is marked as passing or failing depending on the result, logging
*message* with it.
</api>

Calls the function *func* with no arguments, expecting an exception
to be raised. If nothing is raised, marks the test as failing. If an
exception is raised, the exception's `message` property is
compared with *predicate*: if *predicate* is a string, then a
simple equality comparison is done with `message`. Otherwise,
if *predicate* is a regular expression, `message` is tested
against it. Depending on the outcome, a test is marked as passing or
failing, and *message* is logged.
<api name="assertNotEqual">
@method
Simply ensures that `a != b` without recursing into `a` or `b`.

<code>test.**waitUntilDone**([*timeout*])</code>
@param a {value}
A value.

Puts the test runner into asynchronous testing mode, waiting up to
*timeout* milliseconds for `test.done()` to be called. This
is intended for use in situations where a test suite schedules a
callback, calls `test.waitUntilDone`, and then calls
`test.done()` in the callback.
@param b {value}
Another value.

<code>test.**done**()</code>
@param [message] {string}
The test is marked as passing or failing depending on the result, logging
*message* with it.
</api>

Marks a test as being complete. Assumes a previous call to
`test.waitUntilDone()`.

## Functions ##
<api name="assertMatches">
@method
Ensures that the given string matches the given regular expression.
If it does, marks a test as passing, otherwise marks a test as
failing.

@param string {string}
The string to test.

@param regexp {regexp}
The string should match this regular expression.

@param [message] {string}
The test is marked as passing or failing depending on the result, logging
*message* with it.
</api>


<api name="assertRaises">
@method
Calls the function `func` with no arguments, expecting an exception
to be raised. If nothing is raised, marks the test as failing. If an
exception is raised, the exception's `message` property is
compared with `predicate`: if `predicate` is a string, then a
simple equality comparison is done with `message`. Otherwise,
if `predicate` is a regular expression, `message` is tested
against it.

<code>unit-test.**findAndRunTests**(*options*)</code>
@param func {function}
A function that should raise an exception when called.

*options* should contain the following properties:
@param predicate {string,regexp}
A string or regular expression to compare to the exception's message.

@param [message] {string}
Depending on the outcome, a test is marked as passing or failing, and
*message* is logged.
</api>


<api name="waitUntilDone">
@method
Puts the test runner into asynchronous testing mode, waiting up to
*timeout* milliseconds for `test.done()` to be called. This
is intended for use in situations where a test suite schedules a
callback, calls `test.waitUntilDone()`, and then calls
`test.done()` in the callback.

@param [timeout] {integer}
If this number of milliseconds elapses and `test.done()` has not yet been
called, the test is marked as failing.
</api>

<api name="done">
@method
Marks a test as being complete. Assumes a previous call to
`test.waitUntilDone()`.
</api>


## Functions ##

<table>
<tr>
<td><code>dirs</code></td>
<td>A list of absolute paths representing directories to search
<api name="findAndRunTests">
@function
The list of directories is searched for SecurableModules that start
with the prefix `test-`. Each module matching this criteria is
expected to export functions that are test cases or a suite of test
cases; each is called with a single argument, which is a Test Runner
Object.

@param options {object}
An object with the following properties:
@prop dirs {string}
A list of absolute paths representing directories to search
for tests in. It's assumed that all of these directories are also
in the module search path, i.e. any JS files found in them are
SecurableModules that can be loaded via a call to
<code>require()</code>.</td>
</tr>
<tr>
<td><code>onDone</code></td>
<td>A function to call when testing is complete.</td>
</tr>
</table>

The list of directories is searched for SecurableModules that start
with the prefix `test-`. Each module matching this criteria is
expected to export functions that are test cases or a suite of test
cases; each is called with a single argument, which is a Test Runner
Object.
`require()`.
@prop onDone {function}
A function to call when testing is complete.
</api>

0 comments on commit 6a3cdf8

Please sign in to comment.