@hapi/lab Documentation

You can integrate Lab with any assertion library using the --assert argument. When an assertion library is specified, it is imported and assigned to the Lab.assertions property.

If you use @hapi/code, Lab provides additional features:

• Missing Assertion Detection: Lab will report incomplete assertions (e.g., if you reference a property instead of calling a method) and return a failure.
• Verbosity Reporting: Lab calculates the ratio of assertions to tests and outputs this value when using the console reporter.

lab --assert @hapi/code

To run tests written in TypeScript, use the --typescript CLI option. Lab includes a TypeScript definition file to facilitate usage. If your project uses custom paths (e.g., via tsconfig-paths), you can pass --require 'tsconfig-paths/register' to the command.

TypeScript Example:

import * as Lab from '@hapi/lab';
import { expect } from '@hapi/code';

const lab = Lab.script();
const { describe, it, before } = lab;
export { lab };

describe('experiment', () => {
    before(() => {});
    it('verifies 1 equals 1', () => {
        expect(1).to.equal(1);
    });
});

Execution Commands:

# Basic TypeScript execution
$ lab --typescript

# TypeScript execution with custom path resolution
$ lab --typescript --require 'tsconfig-paths/register'

To debug your tests using the V8 Inspector, use the --inspect flag. This will print a URL to the console that you can use with Chrome DevTools or other V8 inspector extensions.

If your tests are mapped to npm test, you can pass the flag through npm: npm test -- --inspect.

You can also specify a custom port: lab --inspect={port}.

Add @hapi/lab as a development dependency in your package.json. You can define scripts to run tests with specific configurations, such as setting a coverage threshold or generating HTML coverage reports.

By default, running lab loads all *.js, *.cjs, or *.mjs files inside the local test directory. To run specific files, pass them as arguments to the CLI.

{
  "devDependencies": {
    "@hapi/lab": "21.x.x"
  },
  "scripts": {
    "test": "lab -t 100",
    "test-cov-html": "lab -r html -o coverage.html"
  }
}

# Run tests for a specific file
$ lab unit.js

# Run tests via npm
$ npm test

You can configure your Lab.script() export to follow Behavior Driven Development (BDD) or Test Driven Development (TDD) naming conventions by destructuring specific methods.

// BDD Style
const { describe, it, before, after } = exports.lab = Lab.script();

describe('math', () => {
    it('returns true when 1 + 1 equals 2', () => {
        expect(1 + 1).to.equal(2);
    });
});

// TDD Style
const { suite, test } = exports.lab = Lab.script();

suite('math', () => {
    test('returns true when 1 + 1 equals 2', () => {
        expect(1 + 1).to.equal(2);
    });
});

To use lab, you must require the module and export a test script using Lab.script(). The exported object must be named lab for the runner to find it. You can use either the it pattern or the test pattern.

Note: lab works best with @hapi/code, but is compatible with any assertion library that throws an error on failure. For asynchronous tests, use async/await or return a Promise.

const Code = require('@hapi/code');
const Lab = require('@hapi/lab');

const { expect } = Code;
// Exporting the script as 'lab' is required
const { it } = exports.lab = Lab.script();

it('returns true when 1 + 1 equals 2', () => {
    expect(1 + 1).to.equal(2);
});

Lab does not natively support code coverage for ES modules. For ESM projects, it is recommended to use c8.

Setup with c8:

1. Install c8: npm install --save-dev c8.
2. Update your test script in package.json to prefix the lab command with c8.

   "scripts": {
-      "test": "lab -a @hapi/code -t 100"
+      "test": "c8 --100 lab -a @hapi/code"
   }

To use the recommended hapi-specific linting rules with lab, you must add @hapi/eslint-plugin to your project and extend its configuration in your ESLint setup.

1. Add @hapi/eslint-plugin as a dependency in package.json.
2. In your ESLint configuration file, add "extends": "plugin:@hapi/recommended".

To ignore specific files in your ESLint configuration while preserving hapi rules, use the ignores property.

import HapiPlugin from '@hapi/eslint-plugin';

export default [
    {
        ignores: ['node_modules/*', '**/vendor/*.js'],
    },
    ...HapiPlugin.configs.module,
];