Testing Foxx services

Foxx provides out of the box support for running tests against aninstalled service using an API similar tothe Mocha test runner.

Test files have full access to the service contextand all ArangoDB APIs but can not define Foxx routes.

Test files can be specified in the service manifestusing either explicit paths of each individual file or patterns that canmatch multiple files (even if multiple patterns match the same file,it will only be executed once):

{
  "tests": [
    "some-specific-test-file.js",
    "test/**/*.js",
    "**/*.spec.js",
    "**/__tests__/**/*.js"
  ]
}

To run a service’s tests you can usethe web interface,the Foxx CLI orthe Foxx HTTP API.Foxx will execute all test cases in the matching files andgenerate a report in the desired format.

Running tests in a production environment is not recommended andmay result in data loss if the tests involve database access.

Writing tests

ArangoDB bundles the chai library,which can be used to define test assertions:

"use strict";
const { expect } = require("chai");
// later
expect("test".length).to.equal(4);

Alternatively ArangoDB also provides an implementation ofNode’s assert module:

"use strict";
const assert = require("assert");
// later
assert.equal("test".length, 4);

Test cases can be defined in any of the following ways using helper functionsinjected by Foxx when executing the test file:

Functional style

Test cases are defined using the it function and can be grouped intest suites using the describe function. Test suites can use thebefore and after functions to prepare and cleanup the suite andthe beforeEach and afterEach functions to prepare and cleanupeach test case individually.

The it function also has the aliases test and specify.

The describe function also has the aliases suite and context.

The before and after functions also havethe aliases suiteSetup and suiteTeardown.

The beforeEach and afterEach functions also havethe aliases setup and teardown.

Note: These functions are automatically injected into the test file anddon’t have to be imported explicitly. The aliases can be used interchangeably.

"use strict";
const { expect } = require("chai");
test("a single test case", () => {
  expect("test".length).to.equal(4);
});
describe("a test suite", () => {
  before(() => {
    // This runs before the suite's first test case
  });
  after(() => {
    // This runs after the suite's last test case
  });
  beforeEach(() => {
    // This runs before each test case of the suite
  });
  afterEach(() => {
    // This runs after each test case of the suite
  });
  it("is a test case in the suite", () => {
    expect(4).to.be.greaterThan(3);
  });
  it("is another test case in the suite", () => {
    expect(4).to.be.lessThan(5);
  });
});
suite("another test suite", () => {
  test("another test case", () => {
    expect(4).to.be.a("number");
  });
});
context("yet another suite", () => {
  specify("yet another case", () => {
    expect(4).to.not.equal(5);
  });
});

Exports style

Test cases are defined as methods of plain objects assigned to test suiteproperties on the exports object:

"use strict";
const { expect } = require("chai");
exports["this is a test suite"] = {
  "this is a test case": () => {
    expect("test".length).to.equal(4);
  }
};

Methods named before, after, beforeEach and afterEach behave similarlyto the corresponding functions in the functional style described above:

exports["a test suite"] = {
  before: () => {
    // This runs before the suite's first test case
  },
  after: () => {
    // This runs after the suite's last test case
  },
  beforeEach: () => {
    // This runs before each test case of the suite
  },
  afterEach: () => {
    // This runs after each test case of the suite
  },
  "a test case in the suite": () => {
    expect(4).to.be.greaterThan(3);
  },
  "another test case in the suite": () => {
    expect(4).to.be.lessThan(5);
  }
};

Unit testing

The easiest way to make your Foxx service unit-testable is to extractcritical logic into side-effect-free functions and move these functions intomodules your tests (and router) can require:

// in your router
const lookupUser = require("../util/users/lookup");
const verifyCredentials = require("../util/users/verify");
const users = module.context.collection("users");
router.post("/login", function (req, res) {
  const { username, password } = req.body;
  const user = lookupUser(username, users);
  verifyCredentials(user, password);
  req.session.uid = user._id;
  res.json({ success: true });
});
// in your tests
const verifyCredentials = require("../util/users/verify");
describe("verifyCredentials", () => {
  it("should throw when credentials are invalid", () => {
    expect(() => verifyCredentials(
      { authData: "whatever" },
      "invalid password"
    )).to.throw()
  });
})

Integration testing

You should avoid running integration tests while a serviceis mounted in development mode as each requestwill cause the service to be reloaded.

You can use the @arangodb/request moduleto let tests talk to routes of the same service.

When the request module is used with a path instead of a full URL,the path is resolved as relative to the ArangoDB instance.Using the baseUrl property of the service contextwe can use this to make requests to the service itself:

"use strict";
const { expect } = require("chai");
const request = require("@arangodb/request");
const { baseUrl } = module.context;
describe("this service", () => {
  it("should say 'Hello World!' at the index route", () => {
    const response = request.get(baseUrl);
    expect(response.status).to.equal(200);
    expect(response.body).to.equal("Hello World!");
  });
  it("should greet us with name", () => {
    const response = request.get(`${baseUrl}/Steve`);
    expect(response.status).to.equal(200);
    expect(response.body).to.equal("Hello Steve!");
  });
});

An implementation passing the above tests could look like this:

"use strict";
const createRouter = require("@arangodb/foxx/router");
const router = createRouter();
module.context.use(router);
router.get((req, res) => {
  res.write("Hello World!");
})
.response(["text/plain"]);
router.get("/:name", (req, res) => {
  res.write(`Hello ${req.pathParams.name}!`);
})
.response(["text/plain"]);