tessl/npm-hapi--code

BDD assertion library designed to work seamlessly with the hapi ecosystem

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Core Assertion Functions

Name: tessl/npm-hapi--code
Author: tessl

Essential functions for creating assertions, controlling test flow, and integrating with test runners.

Capabilities

expect() Function

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"

fail() Function

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');
}

count() Function

Returns the total number of assertions created using the expect() method. Useful for test runner integration and measuring test comprehensiveness.

/**
 * 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: 3

incomplete() Function

Returns 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 none

thrownAt() Function

Returns 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}`);
}

Integration with Test Runners

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(', ')}`);
    }
});