You can install lab and code the same way as any other module on npm:

npm install lab code –-save-dev

Note the --save-dev flag added to the preceding install command. Remember your package.json file, which describes an npm module? This adds the modules to the devDependencies section of your package.json file. devDependencies are dependencies that are required for the development and testing of a module, but are not required for using the module.

The reason why these are separated is that when we run npm install in an application codebase, it only installs the dependencies and devDependencies of the package.json in that directory. For all the modules installed, only their dependencies are installed, not their development dependencies. This is because we only want the dependencies required to run that downloaded application; we don't need all the development dependencies for every module downloaded as well.

After you have installed lab, you can then run it with:

./node_modules/lab/bin/lab test.js

This is quite long to type every time, but fortunately, due to a handy feature of npm called npm scripts, we can shorten it. If you look at package.json generated by the npm init in the first chapter, depending on your version of npm, you may see the following within (some code removed for brevity):

…
"scripts": {
  "test": "echo "Error: no test specified" && exit 1"
},
…

The npm scripts are a list of commands related to the project; they can be for testing like we will see in this example, for starting an application, for build steps, and for starting extra servers, among many other options. They offer huge flexibility in how these are combined for managing the scripts related to a module or application. I could spend a chapter or even a book on just these, but they are outside the scope of this book, so let's just focus on what is important to us here. If you would like to learn more, the hoodie team have an excellent comprehensive introduction to npm scripts at https://github.com/hoodiehq/hoodie-css/blob/feature/build-automation/DEVELOPMENT.md.

To get a list of available scripts for a module application, run the following command in the project directory:

$ npm run

To then run any of the listed scripts, such as test, you can just use the following command:

$ npm run test

As you can see, this gives a very clean API for scripts and the context for each of them in the project's package.json. From this point on in this book, most code snippets will use npm scripts for testing or running any examples. We should strive to use these in our projects to simplify and document the commands related to applications and modules for ourselves and others.

Let's now add the ability to run a test file to our package.json. This just requires modifying the scripts section as follows:

…
"scripts": {
  "test": "./node_modules/lab/bin/lab ./test/index.js"
},
…

A handy addition to note here is that when calling a command with npm run, the bin directory of every module in your node_modules directory is added to PATH when running these scripts; so, we can actually shorten this script to:

…
"scripts": {
  "test": "lab ./test/index.js"
},
…

If you remember the last chapter where we used rejoice to launch our applications, we could also have created an npm script to start our application. As in the preceding example, taking advantage of the bin directory of every module in the node_modules directory being added to PATH, this could also have been shortened as follows:

…
"scripts": {
  "start": "rejoice –c index.js –p ."
},
…

Hopefully, this demonstrates the advantage of using npm scripts. Once inside the application directory, a simple call to npm run, and they are given the commands to start the application, or run it's testing suite, like a free form of documentation. You can imagine how, when looking at a new project or module, developers especially, might not know what test runner is used by this project, or what rejoice is, or how to normally start a project. When the npm scripts are in place, as shown in this section, people new to the project don't have to be aware of what the underlying tools are unless they want to.

$ npm install lab

$ npm install lab -g

Let's take a look at what a simple test script in lab looks like, using the code assertion library. Let's create a fresh directory for the examples in this chapter. Create a directory called example-1, and within that another directory called test. As mentioned earlier, in Node, generally all tests are located within the /test directory of a project. Let's create a file called index.js within our new /test directory, and add the following:

const Code = require('code');                    [1]
const Lab = require('lab');                      [1]
const lab = exports.lab = Lab.script();          [2]
lab.experiment('Testing example', () => {        [3]
  lab.test('fails here', (done) => {             [4]
    Code.expect(false).to.be.true();             [4]
      return done();                             [4]
  });                                            [4]
  lab.test('passes here', (done) => {            [4]
    Code.expect(true).to.be.true();              [4]
    return done();                               [4]
  });                                            [4]
});

This preceding script, even though small, includes a number of new concepts; so let's go through it with reference to the numbers given with the code:

The main things to note here are that lab tests are always asynchronous. In every test, we have to call done() to finish the test; there is no counting of function parameters or checking if the synchronous functions have completed to ensure that a test is finished. Although this requires the boilerplate of calling the done function at the end of every test, it means all tests, synchronous or asynchronous, have a consistent structure.

In chai, which was originally used for hapi, some of the assertions such as .ok, .true, and .false used properties instead of functions for assertions, while assertions such as .equal() and .above() used functions. This type of inconsistency leads to easily forgetting that an assertion should be a method call, and omitting the (). This means the assertion is never called, and the test may pass as a false positive. code's API is more consistent in that every assertion is a function call; here is a comparison of the two:

Notice the difference in the second exist() assertion. In chai, you see the property form of the assertion, while in code you see the required function call here. Through this, lab can make sure that all assertions within a test case are called before done is complete, or it will fail the test.

So lets try running our first test script. As we already updated our package.json script, we can run our test with:

$ npm run test

And this will generate the following output:

There are a couple of things to note from this. Tests run are symbolized with a . or an X, depending on whether it passed or not. You can have lab list the full test title by adding the -v or –-verbose flag to our npm test script command.

You may have noticed the No global variable leaks detected message at the bottom. lab assumes the global object shouldn't be polluted, and checks that no extra properties have been added after running tests. lab can be configured to not run this check, or whitelist certain globals. Details of this are in the lab documentation at https://github.com/hapijs/lab.

I mentioned earlier the concept of TDD or Test-driven Development. This is one of the many approaches known for building a test suite, as is BDD (Behavior-driven Development), and like most test runners in Node, lab is unopinionated in how you structure your tests. Details of how to structure your tests in a TDD or BDD can again be found easily in the lab documentation.