Add custom test runner docs

book/03-hacking-atom/sections/A02-writing-specs.asc

@@ -133,3 +133,34 @@ describe "when a test is written", ->
 ===== Running on CI
 
 It is now easy to run the specs in a CI environment like Travis and AppVeyor. See the http://blog.atom.io/2014/04/25/ci-for-your-packages.html[Travis CI For Your Packages] and http://blog.atom.io/2014/07/28/windows-ci-for-your-packages.html[AppVeyor CI For Your Packages] posts for more details.
+
+
+===== Running via the command line
+
+To run tests on the command line, run Atom with the `--test` flag followed by one or more paths to test files or directories. You can also specify a `--timeout` option, which will force-terminate your tests after a certain number of seconds have passed.
+
+```
+atom --test --timeout 60 ./test/test-1.js ./test/test-2.js
+```
+
+==== Customizing your test runner
+
+**Note: This API is available as of 1.2.0-beta0, and it is experimental and subject to change. Test runner authors should be prepared to test their code against future beta releases until it stabilizes.**
+
+By default, package tests are run with Jasmine 1.3, which is outdated but can't be changed for compatibility reasons. You can specify your own custom test runner by including an `atomTestRunner` field in your `package.json`. Atom will require whatever module you specify in this field, so you can use a relative path or the name of a module in your package's dependencies.
+
+Your test runner module must export a single function, which Atom will call within a new window to run your package's tests. Your function will be called with the following parameters:
+
+* `testPaths` An array of paths to tests to run. Could be paths to files or directories.
+* `buildAtomEnvironment` A function that can be called to construct an instance of the `atom` global. No `atom` global will be explicitly assigned, but you can assign one in your runner if desired. This function should be called with the following parameters:
+  * `applicationDelegate` An object responsible for Atom's interaction with the browser process and host OS. Use `buildDefaultApplicationDelegate` for a default instance. You can override specific methods on this object to prevent or test these interactions.
+  * `window` A window global.
+  * `document` A document global.
+  * `configDirPath` A path to the configuration directory (usually `~/.atom`).
+  * `enablePersistence` A boolean indicating whether the Atom environment should save or load state from the file system. You probably want this to be `false`.
+* `buildDefaultApplicationDelegate` A function that builds a default instance of the application delegate, suitable to be passed as the `applicationDelegate` parameter to `buildAtomEnvironment`.
+* `logFile` An optional path to a log file to which test output should be logged.
+* `headless` A boolean indicating whether or not the tests are being run from the command line via `atom --test`.
+* `legacyTestRunner` This function can be invoked to run the legacy Jasmine runner, giving your package a chance to transition to a new test runner while maintaining a subset of its tests in the old environment.
+
+Your function should return a promise that resolves to an exit code when your tests are finish running. This exit code will be returned when running your tests via the command line.