tessl/npm-should

Expressive, readable, framework-agnostic BDD-style assertion library for JavaScript testing.

—

Pending

Overview

Eval results

Files

Basic Assertions

Name: tessl/npm-should
Author: tessl

Core assertion methods for testing fundamental properties like truthiness, equality, and basic value comparisons.

Truth Testing

ok()

Test that a value is truthy.

/**
 * Assert that the value is truthy (not null, undefined, 0, false, '', or NaN)
 * @returns This assertion for chaining
 */
ok(): Assertion;

Usage:

import should from 'should';

true.should.be.ok();
1.should.be.ok();
'hello'.should.be.ok();
[].should.be.ok();
{}.should.be.ok();

// These will fail
false.should.not.be.ok();
0.should.not.be.ok();
''.should.not.be.ok();
null.should.not.be.ok();

true() / True()

Test that a value is exactly true.

/**
 * Assert that the value is exactly true (not just truthy)
 * @param message - Optional error message
 * @returns This assertion for chaining
 */
true(message?: string): Assertion;
True(message?: string): Assertion;

Usage:

true.should.be.true();
true.should.be.True();

// Custom message
const result = true;
result.should.be.true('Expected result to be true');

false() / False()

Test that a value is exactly false.

/**
 * Assert that the value is exactly false (not just falsy)
 * @param message - Optional error message  
 * @returns This assertion for chaining
 */
false(message?: string): Assertion;
False(message?: string): Assertion;

Usage:

false.should.be.false();
false.should.be.False();

const isValid = false;
isValid.should.be.false('Validation should have failed');

Equality Testing

equal() / equals()

Test for strict equality using ===.

/**
 * Assert strict equality (===) between actual and expected values
 * @param expected - The expected value
 * @param description - Optional error message
 * @returns This assertion for chaining
 */
equal(expected: any, description?: string): Assertion;
equals(expected: any, description?: string): Assertion;

Usage:

(42).should.equal(42);
'hello'.should.equal('hello');
true.should.equal(true);

const user = { name: 'john' };
const sameUser = user;
user.should.equal(sameUser); // Same reference

// With description
const count = 5;
count.should.equal(5, 'Count should be 5');

exactly()

Alias for strict equality testing, emphasizing exact comparison.

/**
 * Assert exact equality (===) - alias for equal()
 * @param expected - The expected value
 * @param description - Optional error message
 * @returns This assertion for chaining
 */
exactly(expected: any, description?: string): Assertion;

Usage:

(100).should.be.exactly(100);
'test'.should.be.exactly('test');

const id = 12345;
id.should.be.exactly(12345, 'ID should match exactly');

eql()

Test for deep equality, comparing object contents recursively.

/**
 * Assert deep equality, comparing object contents recursively
 * @param expected - The expected value or object
 * @param description - Optional error message
 * @returns This assertion for chaining
 */
eql(expected: any, description?: string): Assertion;

Usage:

// Objects with same content
({ name: 'john', age: 30 }).should.eql({ name: 'john', age: 30 });

// Arrays with same elements
[1, 2, 3].should.eql([1, 2, 3]);

// Nested objects
const user1 = { profile: { name: 'john' }, roles: ['admin'] };
const user2 = { profile: { name: 'john' }, roles: ['admin'] };
user1.should.eql(user2);

// With description
const actual = { status: 'ok' };
const expected = { status: 'ok' };
actual.should.eql(expected, 'Response should match expected format');

oneOf() / equalOneOf()

Test if a value equals any one of several provided values.

/**
 * Assert that the value equals one of the provided values
 * @param values - Array of acceptable values or individual arguments
 * @returns This assertion for chaining
 */
oneOf(...values: any[]): Assertion;
oneOf(values: any[]): Assertion;
equalOneOf(...values: any[]): Assertion;
equalOneOf(values: any[]): Assertion;

Usage:

'red'.should.be.oneOf('red', 'green', 'blue');
'red'.should.be.oneOf(['red', 'green', 'blue']);

(42).should.be.equalOneOf(40, 41, 42, 43);

const status = 'pending';
status.should.be.oneOf(['pending', 'complete', 'failed']);

Core Assertion Methods

assert()

Manually assert a boolean expression.

/**
 * Assert that the given expression is truthy
 * @param expression - Boolean expression to test
 * @returns This assertion for chaining
 */
assert(expression: boolean): Assertion;

Usage:

const value = 42;
value.should.assert(value > 0);
value.should.assert(value % 2 === 0, 'Value should be even');

// Can be used with complex conditions
const user = { age: 25, active: true };
user.should.assert(user.age >= 18 && user.active);

fail()

Force an assertion failure.

/**
 * Force an assertion failure with optional message
 * @returns This assertion for chaining
 */
fail(): Assertion;

Usage:

// Force failure in conditional logic
if (someCondition) {
  value.should.fail();
}

// Use in test control flow
try {
  riskyOperation();
  // Should not reach here
  true.should.fail();
} catch (error) {
  // Expected error path
  error.should.be.an.Error();
}

Negation

All basic assertions can be negated using .not:

false.should.not.be.ok();
(1).should.not.equal(2);
'hello'.should.not.be.exactly('world');
({ a: 1 }).should.not.eql({ b: 2 });
'yellow'.should.not.be.oneOf('red', 'green', 'blue');

Chaining

Basic assertions return the Assertion object for chaining:

const value = 42;
value.should.be.ok().and.be.a.Number().and.be.above(0);

const user = { name: 'john', active: true };
user.name.should.equal('john').and.be.a.String();
user.active.should.be.true().and.not.be.false();

Install with Tessl CLI