@@ -3,23 +3,24 @@ JS.Test.Unit.extend({ * mixin JS.Test.Unit.Assertions * * `JS.Test.Unit.Assertions` contains the standard `JS.Test.Unit` assertions. - * Assertions is included in `JS.Test.Unit.TestCase`. + * `Assertions` is included in `JS.Test.Unit.TestCase`. * * To include it in your own code and use its functionality, you simply - * need to rescue `JS.Test.Unit.AssertionFailedError`. Additionally you may - * override `addAssertion` to get notified whenever an assertion is made. + * need to `catch` `JS.Test.Unit.AssertionFailedError`. Additionally you may + * override `JS.Test.Unit.Assertions#addAssertion` to get notified whenever + * an assertion is made. * * Notes: * * The message to each assertion, if given, will be propagated with the * failure. - * * It is easy to add your own assertions based on `assertBlock()`. + * * It is easy to add your own assertions based on `JS.Test.Unit.Assertions#assertBlock`. **/ Assertions: new JS.Module({ /** * JS.Test.Unit.Assertions#assertBlock(message, block, context) -> undefined * * The assertion upon which all other assertions are based. Passes if the - * block yields true. + * block yields `true`. **/ assertBlock: function(message, block, context) { this._wrapAssertion(function() { @@ -52,7 +53,7 @@ JS.Test.Unit.extend({ /** * JS.Test.Unit.Assertions#assertEqual(expected, actual, message) -> undefined * - * Passes if `expected` == `actual`. + * Passes if `expected == actual` or if `expected.equals(actual) == true`. * * Note that the ordering of arguments is important, since a helpful * error message is generated when this one fails that tells you the @@ -214,7 +215,7 @@ JS.Test.Unit.extend({ /** * JS.Test.Unit.Assertions#assertSend(sendArray, message) -> undefined * - * Passes if the method send returns a true value. + * Passes if the method send returns a truthy value. * * `sendArray` is composed of: * * A receiver @@ -240,7 +241,7 @@ JS.Test.Unit.extend({ * JS.Test.Unit.Assertions#buildMessage(head, template, args) -> JS.Test.Unit.Assertions.AssertionMessage * * Builds a failure message. `head` is added before the `template` and - * `args` replaces the '?'s positionally in the template. + * `args` replaces the `?`s positionally in the template. **/ buildMessage: function() { var args = JS.array(arguments), source/test/assertions.js @@ -16,7 +16,7 @@ JS.Test.Unit.extend({ /** * new JS.Test.Unit.Error(testName, exception) * - * Creates a new `Error` with the given test name and + * Creates a new `JS.Test.Unit.Error` with the given test name and * exception. **/ initialize: function(testName, exception) { source/test/error.js @@ -13,7 +13,7 @@ JS.Test.Unit.extend({ /** * new JS.Test.Unit.Failure(testName, location, message) * - * Creates a new `Failure` with the given location and + * Creates a new `JS.Test.Unit.Failure` with the given location and * message. **/ initialize: function(testName, location, message) { source/test/failure.js @@ -18,7 +18,7 @@ JS.Test.Unit.extend({ /** * JS.Test.Unit.TestCase.suite() -> JS.Test.Unit.TestSuite * - * Rolls up all of the test* methods in the fixture into + * Rolls up all of the `test*` methods in the fixture into * one suite, creating a new instance of the fixture for * each method. **/ @@ -55,7 +55,7 @@ JS.Test.Unit.extend({ * * Runs the individual test method represented by this * instance of the fixture, collecting statistics, failures - * and errors in result. + * and errors in `result`. **/ run: function(result, block, context) { block.call(context || null, this.klass.STARTED, this.name()); @@ -106,8 +106,8 @@ JS.Test.Unit.extend({ * JS.Test.Unit.TestCase#passed() -> Boolean * * Returns whether this individual test passed or - * not. Primarily for use in teardown so that artifacts - * can be left behind if the test fails. + * not. Primarily for use in `JS.Test.Unit.TestCase#teardown` + * so that artifacts can be left behind if the test fails. **/ passed: function() { return this._testPassed; @@ -135,7 +135,7 @@ JS.Test.Unit.extend({ * JS.Test.Unit.TestCase#name() -> String * * Returns a human-readable name for the specific test that - * this instance of TestCase represents. + * this instance of `JS.Test.Unit.TestCase` represents. **/ name: function() { return this._methodName + '(' + this.klass.displayName + ')'; source/test/test_case.js @@ -17,7 +17,7 @@ JS.Test.Unit.extend({ /** * new JS.Test.Unit.TestResult() * - * Constructs a new, empty TestResult. + * Constructs a new, empty `JS.Test.Unit.TestResult`. **/ initialize: function() { this.runCount = this.assertionCount = 0; @@ -72,7 +72,7 @@ JS.Test.Unit.extend({ * JS.Test.Unit.TestResult#toString() -> String * * Returns a string contain the recorded runs, assertions, - * failures and errors in this TestResult. + * failures and errors in this `TestResult`. **/ _toString: function() { return this.runCount + ' tests, ' + this.assertionCount + ' assertions, ' + @@ -82,7 +82,7 @@ JS.Test.Unit.extend({ /** * JS.Test.Unit.TestResult#passed() -> Boolean * - * Returns whether or not this TestResult represents + * Returns whether or not this `TestResult` represents * successful completion. **/ passed: function() { @@ -92,7 +92,7 @@ JS.Test.Unit.extend({ /** * JS.Test.Unit.TestResult#failureCount() -> Number * - * Returns the number of failures this TestResult has + * Returns the number of failures this `TestResult` has * recorded. **/ failureCount: function() { @@ -102,7 +102,7 @@ JS.Test.Unit.extend({ /** * JS.Test.Unit.TestResult#errorCount() -> Number * - * Returns the number of errors this TestResult has + * Returns the number of errors this `TestResult` has * recorded. **/ errorCount: function() { source/test/test_result.js @@ -1,13 +1,13 @@ /** section: test * class JS.Test.Unit.TestSuite * - * A collection of tests which can be `run`. + * A collection of tests which can be `JS.Test.Unit.TestSuite#run`. * - * Note: It is easy to confuse a TestSuite instance with - * something that has a static suite method; I know because _I_ + * Note: It is easy to confuse a `TestSuite` instance with + * something that has a static `suite` method; I know because _I_ * have trouble keeping them straight. Think of something that * has a suite method as simply providing a way to get a - * meaningful TestSuite instance. [Nathaniel Talbott] + * meaningful `TestSuite` instance. [Nathaniel Talbott] **/ JS.Test.Unit.extend({ TestSuite: new JS.Class({ @@ -19,7 +19,7 @@ JS.Test.Unit.extend({ /** * new JS.Test.Unit.TestSuite(name) * - * Creates a new TestSuite with the given name. + * Creates a new `JS.Test.Unit.TestSuite` with the given `name`. **/ initialize: function(name) { this.name = name || 'Unnamed TestSuite'; @@ -44,7 +44,7 @@ JS.Test.Unit.extend({ /** * JS.Test.Unit.TestSuite#push(test) -> this * - * Adds the test to the suite. + * Adds the `test` to the suite. **/ push: function(test) { this.tests.push(test); source/test/test_suite.js @@ -12,10 +12,8 @@ JS.Test.Unit.UI.extend({ /** * new JS.Test.Unit.UI.Console.TestRunner(suite, outputLevel) * - * Creates a new `TestRunner` for running the passed - * suite. If quiet_mode is `true`, the output while - * running is limited to progress dots, errors and - * failures, and the final result. + * Creates a new `JS.Test.Unit.UI.Console.TestRunner` + * for running the passed `suite`. **/ initialize: function(suite, outputLevel) { this._suite = JS.isFn(suite.suite) ? suite.suite() : suite; source/test/ui/console/test_runner.js @@ -4,6 +4,110 @@ JS.Test = new JS.Module('Test', { extend: { + /** section: test + * JS.Test.Unit + * + * `JS.Test.Unit` is a (mostly) direct clone of Ruby's `Test::Unit` + * framework. It provides support for writing unit tests that can + * be run wherever you like, and ships with TestRunner UIs for command-line + * use (V8, Rhino, SpiderMonkey) and for web browsers. + * + * The original `Test::Unit` and all documentation contained here is + * copyright (c) 2000-2003 Nathaniel Talbott. It is free software, and is + * distributed under the Ruby license. See the `COPYING` file in the standard + * Ruby distribution for details. + * + * ### Usage + * + * The general idea behind unit testing is that you write a _test_ + * _method_ that makes certain _assertions_ about your code, working + * against a _test_ _fixture_. A bunch of these _test_ _methods_ are + * bundled up into a _test_ _suite_ and can be run any time the + * developer wants. The results of a run are gathered in a _test_ + * _result_ and displayed to the user through some UI. So, lets break + * this down and see how `JS.Test.Unit` provides each of these necessary + * pieces. + * + * ### Assertions + * + * These are the heart of the framework. Think of an assertion as a + * statement of expected outcome, i.e. "I assert that x should be equal + * to y". If, when the assertion is executed, it turns out to be + * correct, nothing happens, and life is good. If, on the other hand, + * your assertion turns out to be false, an error is propagated with + * pertinent information so that you can go back and make your + * assertion succeed, and, once again, life is good. For an explanation + * of the current assertions, see `JS.Test.Unit.Assertions`. + * + * ### Test Method & Test Fixture + * + * Obviously, these assertions have to be called within a context that + * knows about them and can do something meaningful with their + * pass/fail value. Also, it's handy to collect a bunch of related + * tests, each test represented by a method, into a common test class + * that knows how to run them. The tests will be in a separate class + * from the code they're testing for a couple of reasons. First of all, + * it allows your code to stay uncluttered with test code, making it + * easier to maintain. Second, it allows the tests to be stripped out + * for deployment, since they're really there for you, the developer, + * and your users don't need them. Third, and most importantly, it + * allows you to set up a common test fixture for your tests to run + * against. + * + * What's a test fixture? Well, tests do not live in a vacuum; rather, + * they're run against the code they are testing. Often, a collection + * of tests will run against a common set of data, also called a + * fixture. If they're all bundled into the same test class, they can + * all share the setting up and tearing down of that data, eliminating + * unnecessary duplication and making it much easier to add related + * tests. + * + * `JS.Test.Unit.TestCase` wraps up a collection of test methods together + * and allows you to easily set up and tear down the same test fixture + * for each test. This is done by overriding `JS.Test.Unit.TestCase#setup` + * and/or `JS.Test.Unit.TestCase#teardown`, + * which will be called before and after each test method that is + * run. The `TestCase` also knows how to collect the results of your + * assertions into a `JS.Test.Unit.TestResult`, which can then be reported + * back to you... but I'm getting ahead of myself. To write a test, + * follow these steps: + * + * * Create a class that subclasses `JS.Test.Unit.TestCase`. + * * Add a method that begins with `test` to your class. + * * Make assertions in your test method. + * * Optionally define `setup` and/or `teardown` to set up and/or tear + * down your common test fixture. + * * TODO describe how to run tests + * + * A really simple test might look like this (`setup` and `teardown` are + * commented out to indicate that they are completely optional): + * + * MyTest = new JS.Class('MyTest', JS.Test.Unit.TestCase, { + * // setup: function() { + * // }, + * + * // teardown: function() { + * // }, + * + * testFail: function() { + * this.assert(false, 'Assertion was false.'); + * } + * }); + * + * ### Test Runners + * + * So, now you have this great test class, but you still need a way to + * run it and view any failures that occur during the run. This is + * where `JS.Test.Unit.UI.Console.TestRunner` (and others, such as + * `JS.Test.Unit.UI.Browser.TestRunner`) comes into play. To manually + * invoke a runner, simply call its `run` class method and pass in an + * object that responds to the `suite` message with a + * `JS.Test.Unit.TestSuite`. This can be as simple as passing in your + * `TestCase` class (which has a class `suite` method). It might look + * something like this: + * + * JS.Test.Unit.UI.Console.TestRunner.run(MyTest); + **/ Unit: new JS.Module({ extend: { AssertionFailedError: new JS.Class(Error, { source/test/unit.js @@ -12,7 +12,7 @@ JS.Test.Unit.extend({ extend: { /** * JS.Test.Unit.Util.Observable.NOTHING = {} - * We use this for defaults since nil might mean something + * We use this for defaults since `null` might mean something **/ NOTHING: {} }, @@ -20,7 +20,7 @@ JS.Test.Unit.extend({ /** * JS.Test.Unit.Util.Observable#addListener(channelName, block, context) -> Function * - * Adds the passed block as a listener on the + * Adds the passed `block` as a listener on the * channel indicated by `channelName`. **/ addListener: function(channelName, block, context) { source/test/util/observable.js 66c393f8bad1f1a66737c885a1e53ec2fa6641b1 James Coglan jcoglan@googlemail.com http://github.com/jcoglan/js.class/commit/ad9c8032992c380ee33a5a8dc3f5fef19a33afc1 ad9c8032992c380ee33a5a8dc3f5fef19a33afc1 2009-07-05T05:06:57-07:00 2009-07-05T05:06:57-07:00 Test.Unit documentation updates, including credit for original work and usage documentation from the Ruby version. 4eb2d4199a1ccd9e5f97d260ec9a28b11361cc55 James Coglan jcoglan@googlemail.com