Add chapter on Foxx testing

Documentation/Books/Manual/Foxx/Testing.mdpp

@@ -0,0 +1,207 @@
+!CHAPTER Writing tests
+
+Foxx provides out of the box support for running tests against an installed service
+using the [Mocha](https://mochajs.org) test runner.
+
+Test files have full access to the [service context](./Context.md) and all ArangoDB APIs
+but like scripts can not define Foxx routes.
+
+!SECTION Running tests
+
+An installed service's tests can be executed from the administrative web interface:
+
+1. Open the "Services" tab of the web interface
+2. Click on the installed service to be tested
+3. Click on the "Settings" tab
+4. Click on the flask icon in the top right
+5. Accept the confirmation dialog
+
+Note that running tests in a production database is not recommended
+and may result in data loss if the tests access the database.
+
+When running a service in development mode special care needs to be taken as
+performing requests to the service's own routes as part of the test suites
+may result in tests being executed while the database is in an inconsistent state,
+leading to unexpected behaviour.
+
+!SECTION Test file paths
+
+In order to tell Foxx about files containing test suites, one or more patterns need to be specified in the `tests` option of the [service manifest](./Manifest.md):
+
+```json
+{
+  "tests": [
+    "**/test_*.js",
+    "**/*_test.js"
+  ]
+}
+```
+
+These patterns can be either relative file paths or "globstar" patterns where
+
+* `*` matches zero or more characters in a filename
+* `**` matches zero or more nested directories
+
+For example, given the following directory structure:
+
+```
+++ test/
+|++ a/
+||+- a1.js
+||+- a2.js
+||+- test.js
+|+- b.js
+|+- c.js
+|+- d_test.js
++- e_test.js
++- test.js
+```
+
+The following patterns would match the following files:
+
+```
+test.js:
+  test.js
+
+test/*.js:
+  /test/b.js
+  /test/c.js
+  /test/d_test.js
+
+test/**/*.js:
+  /test/a/a1.js
+  /test/a/a2.js
+  /test/a/test.js
+  /test/b.js
+  /test/c.js
+  /test/d_test.js
+
+**/test.js:
+  /test/a/test.js
+
+**/*test.js:
+  /test/a/test.js
+  /test/d_test.js
+  /e_test.js
+  /test.js
+```
+
+Even if multiple patterns match the same file the tests in that file will only be run once.
+
+The order of tests is always determined by the file paths,
+not the order in which they are matched or specified in the manifest.
+
+!SECTION Test structure
+
+Mocha test suites can be defined using one of three interfaces: BDD, TDD or Exports.
+
+The QUnit interface of Mocha is not supported in ArangoDB.
+
+Like all ArangoDB code, test code is always synchronous.
+
+!SUBSECTION BDD interface
+
+The BDD interface defines test suites using the `describe` function
+and each test case is defined using the `it` function:
+
+```js
+'use strict';
+const assert = require('assert');
+const trueThing = true;
+
+describe('True things', () => {
+  it('are true', () => {
+    assert.equal(trueThing, true);
+  });
+});
+```
+
+The BDD interface also offers the alias `context` for `describe` and `specify` for `it`.
+
+Test fixtures can be handled using `before` and `after` for suite-wide fixtures
+and `beforeEach` and `afterEach` for per-test fixtures:
+
+```js
+describe('False things', () => {
+  let falseThing;
+  before(() => {
+    falseThing = !true;
+  });
+  it('are false', () => {
+    assert.equal(falseThing, false);
+  });
+});
+```
+
+!SUBSECTION TDD interface
+
+The TDD interface defines test suites using the `suite` function
+and each test case is defined using the `test` function:
+
+```js
+'use strict';
+const assert = require('assert');
+const trueThing = true;
+
+suite('True things', () => {
+  test('are true', () => {
+    assert.equal(trueThing, true);
+  });
+});
+```
+
+Test fixtures can be handled using `suiteSetup` and `suiteTeardown` for suite-wide fixtures
+and `setup` and `teardown` for per-test fixtures:
+
+```js
+suite('False things', () => {
+  let falseThing;
+  suiteSetup(() => {
+    falseThing = !true;
+  });
+  test('are false', () => {
+    assert.equal(falseThing, false);
+  });
+});
+```
+
+!SUBSECTION Exports interface
+
+The Exports interface defines test cases as methods of plain object properties of the `module.exports` object:
+
+```js
+'use strict';
+const assert = require('assert');
+const trueThing = true;
+
+exports['True things'] = {
+  'are true': function() {
+    assert.equal(trueThing, true);
+  }
+};
+```
+
+The keys `before`, `after`, `beforeEach` and `afterEach` are special-cased
+and behave like the corresponding functions in the BDD interface:
+
+```js
+let falseThing;
+exports['False things'] = {
+  before () {
+    falseThing = false;
+  },
+  'are false': function() {
+    assert.equal(falseThing, false);
+  }
+};
+```
+
+!SECTION Assertions
+
+ArangoDB provides two bundled modules to define assertions:
+
+* `assert` corresponds to the [Node.js `assert` module](http://nodejs.org/api/assert.html),
+  providing low-level assertions that can optionally specify an error message.
+
+* `chai` is the popular [Chai Assertion Library](http://chaijs.com),
+  providing both BDD and TDD style assertions using a familiar syntax.

Documentation/Books/Manual/SUMMARY.md

@@ -85,7 +85,7 @@
       * [Cookie transport](Foxx/Sessions/Transports/Cookie.md)
       * [Header transport](Foxx/Sessions/Transports/Header.md)
   * [Serving files](Foxx/Assets.md)
-#  * [Writing tests](Foxx/Testing.md)
+  * [Writing tests](Foxx/Testing.md)
   * [Scripts and queued jobs](Foxx/Scripts.md)
   * [Migrating 2.x services](Foxx/Migrating2x/README.md)
     * [Migrating from pre-2.8](Foxx/Migrating2x/Wayback.md)