Essential functions for creating assertions, controlling test flow, and integrating with test runners.
Creates an assertion chain for testing values with optional error message prefix.
/**
* Creates an assertion chain for the given value
* @param {*} value - The value being asserted
* @param {string} [prefix] - Optional string prefix added to error messages
* @returns {Assertion} Assertion object with chainable methods
*/
function expect(value, prefix)Usage Examples:
const Code = require('@hapi/code');
const expect = Code.expect;
// Basic usage
expect(10).to.be.above(5);
expect('hello').to.be.a.string();
// With error message prefix
expect(userAge, 'User age').to.be.above(18);
// Error message will be: "User age: Expected 15 to be above 18"Makes the test fail immediately with a provided error message.
/**
* Makes the test fail with the provided message
* @param {string} [message] - The error message to display
* @throws {Error} Always throws an Error with the message
*/
function fail(message)Usage Examples:
const Code = require('@hapi/code');
// Simple failure
Code.fail('This should not happen');
// Conditional failure
if (someCondition) {
Code.fail('Unexpected condition occurred');
}Returns the total number of assertions created using the
expect()/**
* Returns the total number of assertions created
* @returns {number} Total number of assertions made
*/
function count()Usage Examples:
const Code = require('@hapi/code');
const expect = Code.expect;
// Run some tests
expect(1).to.equal(1);
expect(2).to.equal(2);
expect(3).to.equal(3);
console.log(Code.count()); // Output: 3Returns an array of locations where incomplete assertions were declared, or null if no incomplete assertions found. This helps identify unexecuted assertions that may silently pass tests.
/**
* Returns locations of incomplete assertions
* @returns {string[]|null} Array of file:line.column locations or null if none
*/
function incomplete()Usage Examples:
const Code = require('@hapi/code');
const expect = Code.expect;
// This creates an incomplete assertion (missing execution)
expect(10).to.be.above; // Missing () - this is incomplete!
const incompleteLocations = Code.incomplete();
console.log(incompleteLocations);
// Output: ['/path/to/test.js:5.23'] or null if noneReturns location information (filename, line number, column number) where an error was created. If no error is provided, returns the current location.
/**
* Returns location where error was thrown
* @param {Error} [error] - Error object to analyze (optional)
* @returns {Object} Location object with filename, line, column properties
*/
function thrownAt(error)Location Object:
interface Location {
filename: string; // File path where error occurred
line: string; // Line number as string
column: string; // Column number as string
}Usage Examples:
const Code = require('@hapi/code');
// Get current location
const currentLocation = Code.thrownAt();
console.log(currentLocation);
// Output: { filename: '/path/to/file.js', line: '10', column: '5' }
// Analyze specific error
try {
throw new Error('Something went wrong');
} catch (err) {
const errorLocation = Code.thrownAt(err);
console.log(`Error at ${errorLocation.filename}:${errorLocation.line}`);
}These core functions are designed to integrate with test runners like @hapi/lab:
const Lab = require('@hapi/lab');
const Code = require('@hapi/code');
const lab = exports.lab = Lab.script();
const expect = Code.expect;
lab.test('example test', () => {
expect(2 + 2).to.equal(4);
expect('hello').to.contain('ell');
// Check assertion count for test comprehensiveness
const assertionCount = Code.count();
console.log(`Made ${assertionCount} assertions`);
// Check for incomplete assertions
const incomplete = Code.incomplete();
if (incomplete) {
Code.fail(`Incomplete assertions found: ${incomplete.join(', ')}`);
}
});