dojo-util/doh/README

Dojo utilities including build system for optimizing JavaScript application performance, and DOH testing tool

DOH: The Dojo Object Harness
============================

DOH is a unit test framework developed by the Dojo Toolkit Community. For the tutorial published
with the latest release see: http://dojotoolkit.org/reference-guide/util/doh.html#util-doh.

DOH is a constructed as an AMD package that uses doh/main.js for its main entry point. It may
be executed in the browser or by node.js or rhino. Typically, it is loaded by the dojo AMD
loader; however, it is also possible to use any complying loader. 


node.js
=======

To run DOH via node.js, issue the command

> node path/to/dojo/dojo.js load=doh test=path/to/test/module

For example, from the util/doh/ directory you can run the self test as follows:

~/dev/dojotoolkit/util/doh> node ../../dojo/dojo.js load=doh test=doh/tests/selfTest

Since node.js includes executing scripts to discover their location, the dojo node bootstrap
can discover baseUrl (the dojo directory) without further help.


rhino
=====

To run DOH via rhino, issue the command

>java -jar path/to/js.jar path/to/dojo/dojo.js baseUrl=path/to/dojo load=doh test=path/to/test/module

For example, from the util/doh/ directory, you can run the self test as follows (assumes js.jar is in the user's
home directory):

~/dev/dojotoolkit/util/doh> java -jar ../shrinksafe/js.jar ../../dojo/dojo.js baseUrl=../../dojo load=doh test=doh/tests/selfTest

Since rhino does not give scripts the ability to discover their location, you must do one of the following

  * provide a baseUrl command line argument that specifies the dojo directory
  * execute the command form the the dojo directory

Here's the equivalent example command from the dojo directory:

~/dev/dojotoolkit/dojo> java -jar ../util/shrinksafe/js.jar dojo.js load=doh test=doh/tests/selfTest


browser
=======

To run DOH in the browser, point your browser to util/DOH/runner.html. You'll also need to provide at least one
test module to execute by the query parameter "test". For example, to run the dojo unit tests, the URL would
look something like...

http://localhost/dev/dojotoolkit/util/doh/runner.html?test=dojo/tests/module

(Of course the host and path--localhost and dev/dojotoolkit/util in the example--will depend on how you've configured
your test environment.

DOH includes the following query parameters:

test: 
a comma-separated-list of AMD module identifiers that contain the tests to load.

testUrl:
deprecated alias for test

paths:
a semicolon-separated-list of comma-separated-pairs of (module-identifier -> path-prefix) to provide to the loader's
path configuration property.

registerModulePath:
deprecated alias for paths

boot:
a comma-separated-list of Javascript resources to script inject to bootstrap DOH. Defaults to "../../dojo/dojo.js",
which causes DOH to use the dojo AMD loader. You may use this parameter to provide and alternate loader.

dojoUrl:
deprecated alias for boot

async:
If provided, instructs the dojo loader to operate in async mode.

breakOnError:
If provided, instructs DOH to break into the debugger upon an error.


About Hard Dojo Dependency
==========================

As of v1.7 DOH depends on dojo base via AMD define dependency lists. If this causes you concern, you
may sandbox dojo by setting dojoConfig.scopeMap.dojo to falsy which will result in *not* publishing
dojo to the global namespace. Alternatively, you may provide a custom library that includes the
part of the dojo base API used by DOH and map the AMD module identifier "dojo" to this custom library.
However, we know of no good reason to follow either of these paths.