Content and Relationship Testing

/**
 * Asserts that the reference value includes provided values
 * @param {*} values - Values to check for inclusion
 * @returns {Assertion} Assertion chain object for further chaining
 */
include(values)

includes()

contain()

contains()

const Code = require('@hapi/code');
const expect = Code.expect;

// String contains substring
expect('hello world').to.include('world');
expect('hello world').to.include('hello');
expect('abc123').to.contain('123');

// Multiple substrings
expect('hello world').to.include(['hello', 'world']);
expect('abc123def').to.contain(['abc', '123', 'def']);

// Array contains elements
expect([1, 2, 3]).to.include(2);
expect([1, 2, 3]).to.include([1, 3]);
expect(['a', 'b', 'c']).to.contain('b');

// Array contains objects (deep comparison)
expect([{a: 1}, {b: 2}]).to.include({a: 1});
expect([{a: 1, b: 2}]).to.include({a: 1}); // Partial match with part flag

// Object contains properties
expect({a: 1, b: 2, c: 3}).to.include('a');
expect({a: 1, b: 2, c: 3}).to.include(['a', 'c']);

// Object contains key-value pairs
expect({a: 1, b: 2, c: 3}).to.include({a: 1});
expect({a: 1, b: 2, c: 3}).to.include({a: 1, c: 3});

// once flag - requires single occurrence
expect('hello hello').to.once.include('hello'); // Fails - appears twice
expect('hello world').to.once.include('hello'); // Passes - appears once

// only flag - requires exact match (no extra elements)
expect([1, 2]).to.only.include([1, 2]); // Passes
expect([1, 2, 3]).to.only.include([1, 2]); // Fails - has extra element

// part flag - allows partial matching for objects
expect({a: 1, b: 2}).to.part.include({a: 1}); // Passes - partial match
expect([{a: 1, b: 2}]).to.part.include([{a: 1}]); // Passes - partial object match

// shallow flag - uses strict equality
expect([1, 2, 3]).to.shallow.include(2); // Passes - same reference

/**
 * Asserts that the reference value exists (not null or undefined)
 * @returns {Assertion} Assertion chain object for further chaining
 */
exist()

exists()

expect(0).to.exist();        // Passes - 0 is not null/undefined
expect('').to.exist();       // Passes - empty string exists
expect(false).to.exist();    // Passes - false is not null/undefined
expect([]).to.exist();       // Passes - empty array exists
expect({}).to.exist();       // Passes - empty object exists

expect(null).to.not.exist(); // Passes - null doesn't exist
expect(undefined).to.not.exist(); // Passes - undefined doesn't exist

// Common usage patterns
const user = getUser();
expect(user).to.exist();
expect(user.name).to.exist();

// Special behavior with errors and 'not' flag
const error = new Error('test');
expect(error).to.not.exist(); // This will throw the original error!

/**
 * Asserts that the reference value is empty
 * @returns {Assertion} Assertion chain object for further chaining
 */
empty()

// Strings
expect('').to.be.empty();
expect('hello').to.not.be.empty();

// Arrays
expect([]).to.be.empty();
expect([1, 2, 3]).to.not.be.empty();

// Objects
expect({}).to.be.empty();
expect({a: 1}).to.not.be.empty();

// Buffers
expect(Buffer.alloc(0)).to.be.empty();
expect(Buffer.from('hello')).to.not.be.empty();

// Error cases - only works with objects, arrays, strings
expect(123).to.throw(); // Will throw error - can't check empty on number

/**
 * Asserts that the reference value has specific length or key count
 * @param {number} size - Expected length or key count
 * @returns {Assertion} Assertion chain object for further chaining
 */
length(size)

// Strings
expect('hello').to.have.length(5);
expect('').to.have.length(0);

// Arrays
expect([1, 2, 3]).to.have.length(3);
expect([]).to.have.length(0);

// Objects (counts keys)
expect({a: 1, b: 2}).to.have.length(2);
expect({}).to.have.length(0);

// Buffers
expect(Buffer.from('hello')).to.have.length(5);
expect(Buffer.alloc(10)).to.have.length(10);

// Common patterns
const items = getItems();
expect(items).to.be.an.array().and.have.length.above(0);
expect(items).to.have.length.within(5, 10);

/**
 * Asserts that the reference value equals the provided value
 * @param {*} value - Value to compare against
 * @param {Object} [options] - Comparison options passed to Hoek.deepEqual
 * @returns {Assertion} Assertion chain object for further chaining
 */
equal(value, options)

equals()

// Primitives
expect(5).to.equal(5);
expect('hello').to.equal('hello');
expect(true).to.equal(true);

// Objects (deep comparison)
expect({a: 1, b: 2}).to.equal({a: 1, b: 2});
expect([1, 2, 3]).to.equal([1, 2, 3]);

// Nested objects
expect({
    user: {name: 'John', age: 30},
    active: true
}).to.equal({
    user: {name: 'John', age: 30}, 
    active: true
});

// Use shallow flag for strict equality (===)
const obj1 = {a: 1};
const obj2 = {a: 1};
const obj3 = obj1;

expect(obj1).to.shallow.equal(obj3); // Passes - same reference
expect(obj1).to.not.shallow.equal(obj2); // Passes - different references
expect(obj1).to.equal(obj2); // Passes - deep equality

// Custom comparison options (passed to Hoek.deepEqual)
const options = {
    prototype: false,     // Ignore prototypes
    deepFunction: true    // Compare function implementations
};

expect(obj1).to.equal(obj2, options);

// Using global settings
const Code = require('@hapi/code');
Code.settings.comparePrototypes = true;
expect(obj1).to.equal(obj2); // Will include prototype comparison

const Code = require('@hapi/code');
const expect = Code.expect;

// Complex object testing
const user = {
    name: 'John Doe',
    age: 30,
    roles: ['admin', 'user'],
    profile: {
        email: 'john@example.com',
        verified: true
    }
};

expect(user)
    .to.be.an.object()
    .and.include(['name', 'age', 'roles'])
    .and.include({name: 'John Doe'})
    .and.have.length(4); // 4 keys

expect(user.roles)
    .to.be.an.array()
    .and.include('admin')
    .and.have.length(2);

expect(user.name)
    .to.be.a.string()
    .and.not.be.empty()
    .and.include('John');

// Array of objects
const users = [
    {id: 1, name: 'Alice'},
    {id: 2, name: 'Bob'},
    {id: 3, name: 'Charlie'}
];

expect(users)
    .to.be.an.array()
    .and.have.length(3)
    .and.include({id: 1, name: 'Alice'});

// Partial matching with part flag
expect(users).to.part.include([{id: 1}, {id: 2}]);

// Check for specific patterns
const userIds = users.map(u => u.id);
expect(userIds).to.equal([1, 2, 3]);
expect(userIds).to.include([1, 3]);