1 files changed, 393 insertions, 0 deletions
diff --git a/tools/addon-sdk-1.5/packages/api-utils/docs/unit-test.md b/tools/addon-sdk-1.5/packages/api-utils/docs/unit-test.md
new file mode 100644
index 0000000..6962c41
--- /dev/null
+++ b/tools/addon-sdk-1.5/packages/api-utils/docs/unit-test.md
@@ -0,0 +1,393 @@
+<!-- This Source Code Form is subject to the terms of the Mozilla Public
+   - License, v. 2.0. If a copy of the MPL was not distributed with this
+   - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
+
+<!-- contributed by Atul Varma [atul@mozilla.com]  -->
+<!-- edited by Noelle Murata [fiveinchpixie@gmail.com]  -->
+<!-- edited by Shane Tomlinson[stomlinson@mozilla.com] -->
+
+The `unit-test` module makes it easy to find and run unit tests.
+
+<api name="test">
+@class
+Each function which represents a test case is passed a single argument
+`test`, which represents the test runner.
+
+<api name="pass">
+@method
+  Marks a test as passing, with the given optional message.
+
+@param [message] {string}
+  Optional passing message.
+</api>
+
+
+<api name="fail">
+@method
+  Marks a test as failing, with the given optional message.
+
+@param [message] {string}
+  Optional failure message.
+</api>
+
+<api name="expectFail">
+@method
+  *experimental* Expect the test enclosed within `func` to fail. 
+
+@param func {function}
+  A function that should contain a test that is expected to fail.
+</api>
+
+<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.
+
+@param e {exception}
+  An exception.
+</api>
+
+<api name="assert">
+@method
+  Ensures that `a` has a truthy value.
+
+@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>
+
+
+<api name="assertEqual">
+@method
+  Ensures that `a == b` without recursing into `a` or `b`.
+
+@param a {value}
+  A value.
+
+@param b {value}
+  Another value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
+
+<api name="assertNotEqual">
+@method
+  Ensures that `a != b` without recursing into `a` or `b`.
+
+@param a {value}
+  A value.
+
+@param b {value}
+  Another value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
+
+<api name="assertStrictEqual">
+@method
+  Ensures that `a === b` without recursing into `a` or `b`.
+
+@param a {value}
+  A value.
+
+@param b {value}
+  Another value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
+
+
+<api name="assertNotStrictEqual">
+@method
+  Ensures that `a !== b` without recursing into `a` or `b`.
+
+@param a {value}
+  A value.
+
+@param b {value}
+  Another value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
+
+<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.
+
+@param func {function}
+  A function that should raise an exception when called.
+
+@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="assertFunction">
+@method
+  Ensures that `a` is a function.
+
+@param a {value}
+  A value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+  
+</api>  
+
+
+<api name="assertUndefined">
+@method
+  Ensures that `a` is `undefined`.  `null`, `0`, and `false` will all fail.
+
+@param a {value}
+  A value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+  
+</api>  
+
+
+<api name="assertNotUndefined">
+@method
+  Ensures that `a` is not `undefined`.  `null`, `0`, and `false` will all pass.
+
+@param a {value}
+  A value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+  
+</api>  
+
+
+<api name="assertNull">
+@method
+  Ensures that `a` is `null`.  `undefined`, `0`, and `false` will all fail.
+
+@param a {value}
+  A value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+  
+</api>  
+
+
+<api name="assertNotNull">
+@method
+  Ensures that `a` is not `null`.  `undefined`, `0`, and `false` will all pass.
+
+@param a {value}
+  A value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+  
+</api>  
+
+
+<api name="assertObject">
+@method
+  Ensures that `a` is an object.  A function, string, or number will fail.
+
+@param a {value}
+  A value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+  
+</api>  
+
+
+<api name="assertString">
+@method
+  Ensures that `a` is a string.
+
+@param a {value}
+  A value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+  
+</api>  
+
+
+<api name="assertArray">
+@method
+  Ensures that `a` is an array.
+
+@param a {value}
+  A value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+  
+</api>  
+
+
+<api name="assertNumber">
+@method
+  Ensures that `a` is a number.
+
+@param a {value}
+  A value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+  
+</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>
+
+</api>
+
+
+<api name="waitUntil">
+@method
+  Ensures that `a` returns a truthy value within a reasonable amount of time.
+
+@param a {function}
+  Function that returns the value to verify.
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
+
+
+<api name="waitUntilEqual">
+@method
+  Ensures that `a == b` returned values or values without without recursing
+  into `a` or `b`.
+
+@param a {Function}
+  A value, or a function that returns a value.
+
+@param b {value}
+  Another value, or a function that returns value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
+
+<api name="waitUntilNotEqual">
+@method
+  Ensures that `a != b` without recursing into `a` or `b`.
+
+@param a {Function}
+  A value, or a function that returns a value.
+
+@param b {value}
+  Another value, or a function that returns another value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
+
+
+<api name="waitUntilMatches">
+@method
+  Ensures that the given string matches the given regular expression.
+  If it does, marks the test as passing, otherwise marks the test as
+  failing.
+
+@param string {Function}
+  A function that returns 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="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
+    `require()`.
+  @prop onDone {function}
+    A function to call when testing is complete.
+</api>