Add some more mochitest docs (firefox-devtools#5319)

* Add some more mochitest docs

* A few word changes

Author: jasonLaster

assets/dictionary.txt

@@ -123,3 +123,6 @@ isPaused
 QuickOpen
 named-evals
 Greenkeeper
+headlessly
+natively
+outputed

docs/mochitests.md

@@ -8,6 +8,8 @@
 
 We use [mochitests] to do integration testing. Mochitests are part of Firefox and allow us to test the debugger literally as you would use it (as a devtools panel).
 
+Mochitests are different from Jest, Mocha, Selenium, because we have access to firefox internals and run inside the browser toolbox. This makes it possible to write tests as if we're a user interacting with the debugger natively :)
+
 ![](http://g.recordit.co/dp6qbK0Jnf.gif)
 
 ### Getting Started
@@ -17,7 +19,6 @@ We use [mochitests] to do integration testing. Mochitests are part of Firefox an
 * mercurial ( `brew install mercurial` )
 * autoconf213 ( `brew install [email protected] && brew unlink autoconf` )
 
-
 **Setup Firefox**
 
 * Inside the main debugger.html folder run:
@@ -39,8 +40,9 @@ reflected in the new firefox directory.
 
 `mochi` passes its params along to `mochitest`, so you can include `--jsdebugger` and test globs
 
-* `yarn mochi -- --jsdebugger` opens a browser toolbox
-* `yarn mochi browser_dbg-editor-highlight` runs just one test
+* `yarn mochi dbg-editor-highlight` runs just one test
+* `yarn mochid dbg-editor-highlight` opens a browser toolbox
+* `yarn mochih dbg-editor-highlight` runs the test headlessly
 
 ## Writing Tests
 
@@ -50,17 +52,60 @@ Here are a few tips for writing mochitests:
 * Try to write async user actions that involve a user action like clicking a button or typing a key press followed by a redux action to listen for. For example, the user step in action involves the user clicking the step in button followed by the "stepIn" action firing.
 * The `dbg` object has several helpful properties (actions, selectors, getState, store, toolbox, win)
 
+### Logging
+
+The mochitests run in a special environment, which make `console.log` a little different than usual.
+`console.log` inside the test will print to the terminal. `console.log` in the debugger source, will be redirected to the browser console and will not be outputed. This is why we recommend using the special firefox `dump` call which is available everywhere.
+
+If you want a convenience method for logging in the test, `log` is a bit cleaner than `dump`.
+
+```js
+  console.log(">>> YO")
+  log("FOO", { t: 3 })
+  dump(">> FOOO\n");
+```
+
+
+### Pausing the test
+
+There are two ways to pause the tests and see what is going on.
+
+The first is to add a `debugger` statement to the test and run `yarn mochid {test_name}` (ex: `dbg-sources`). Here you'll have to click a modal when the test opens. When the test pauses, the browser toolbox will show your test with the `dbg` object you can interact with.
+
+The other way is to add `await waitForever()` to your test. This stops the test and gives you a chance to interact with the debugger as the user would. Both ways of pausing are useful for different use cases!
+
+### Waiting in a test
+
+It's really common to want to wait for something to happen in a test. Generally we wait for one of two things to happen:
+
+* waiting for the Redux state to change
+* waiting for an action to be dispatched
+
+```js
+await waitForState(dbg, state => isPaused(state));
+await waitForDispatch(dbg, "STEP_OVER";)
+```
+
 ### Testing the DOM
 
 You can find common elements in the debugger with the `findElement` function,
 which use shared selectors. You can also find any element with the
 `findElementWithSelector` function.
 
+```js
+  findElement(dbg, "sourceNode", 3);
+  findElementWithSelector(dbg, ".sources-list .focused");
+```
+
 ### Evaluating in the debuggee
 
 If you want to evaluate a function in the debuggee context you can use
 the `invokeInTab` function. Under the hood it is using `ContentTask.spawn`.
 
+```js
+invokeInTab(dbg, "doSomething")
+```
+
 ```js
 ContentTask.spawn(gBrowser.selectedBrowser, null, function* () {
   content.wrappedJSObject.foo();
@@ -94,9 +139,8 @@ We recommend prefixing your logs and formatting them so they are easy to scan e.
 * `info(">> Current breakpoints ${breakpoints.map(bp => bp.location.line).join(", ")}\n")`
 * `info(">> Symbols for source ${source.url} ${JSON.stringify(symbols)}\n")`
 
-At some point, it can be nice to pause the test and debug it. We are working on a debugger after all :)
-Mochitest, makes it easy to pause the test at `debugger` statements  with the `--jsdebugger` flag.
-You can run the test like this `yarn mochid browser_dbg-editor-highlight`.
+At some point, it can be nice to pause the test and debug it.  Mochitest makes it easy to pause the test at `debugger` statements  with the `--jsdebugger` flag.
+You can run the test with `yarn mochid {test_name}` (ex: `browser_dbg-editor-highlight`).
 
 ![](https://shipusercontent.com/e8441c77ab9ff6e84e5561b05bc25da2/Screen%20Shot%202017-10-26%20at%205.45.05%20PM.png)
 ![](https://shipusercontent.com/57e41ae7227a46b2b6ae8b66956729ea/Screen%20Shot%202017-10-26%20at%205.44.54%20PM.png)