tessl/npm-should

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

—

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

Should.js

Name: tessl/npm-should
Author: tessl

Should.js is an expressive, readable, framework-agnostic BDD-style assertion library for JavaScript testing. It provides intuitive assertion syntax that reads like natural language, making tests more readable and error messages more helpful.

Package Information

Package Name: should
Package Type: npm
Language: JavaScript (with TypeScript definitions)
Installation: npm install should --save-dev

Core Imports

ES6 Modules

import should from 'should';

CommonJS

const should = require('should');

As Function (no prototype extension)

const should = require('should/as-function');

Browser (UMD)

<script src="should.js"></script>
<!-- window.should is available globally -->

Basic Usage

Should.js provides two main usage patterns for writing assertions:

Prototype Extension (Default)

import should from 'should';

const user = { name: 'john', age: 25 };

// Assertions using prototype extension
user.should.have.property('name', 'john');
user.should.have.property('age').which.is.a.Number();
user.age.should.be.above(18);

Functional API

const should = require('should/as-function');

const user = { name: 'john', age: 25 };

// Assertions using functional syntax
should(user).have.property('name', 'john');
should(user.age).be.above(18);
should(null).not.be.ok();

Architecture

Should.js is built around a core Assertion object that wraps the value being tested. All assertion methods return the same Assertion object, enabling method chaining. The library includes:

Core Assertion Object: Wraps values and provides assertion methods
Extension System: Modular assertion plugins for different types
Chainable Syntax: Fluent API with readable method names
Error Handling: Custom assertion errors with helpful messages

Capabilities

Basic Assertions

Test fundamental properties like truthiness, equality, and types.

/**
 * Core assertion methods for basic value testing
 */
interface BasicAssertions {
  ok(): Assertion;
  true(message?: string): Assertion;
  false(message?: string): Assertion;
  equal(expected: any, description?: string): Assertion;
  exactly(expected: any, description?: string): Assertion;
}

Basic Assertions - Truth testing, equality checks, and fundamental assertions.

Type Assertions

Verify the type and class of values using built-in JavaScript types.

/**
 * Type checking and instanceof testing methods
 */
interface TypeAssertions {
  type(typeName: string, description?: string): Assertion;
  instanceof(constructor: Function, description?: string): Assertion;
  Number(): Assertion;
  String(): Assertion;
  Array(): Assertion;
  Object(): Assertion;
  Function(): Assertion;
}

Type Assertions - Type checking, instanceof tests, and built-in type assertions.

Object and Property Assertions

Test object properties, structure, and ownership.

/**
 * Object and property testing methods
 */
interface PropertyAssertions {
  property(name: string, value?: any): Assertion;
  properties(...names: string[]): Assertion;
  ownProperty(name: string, description?: string): Assertion;
  keys(...keys: any[]): Assertion;
  empty(): Assertion;
  length(value: number, description?: string): Assertion;
}

Object and Property Assertions - Object structure, property existence, and collection testing.

Number and Range Assertions

Numeric comparisons, ranges, and special number values.

/**
 * Numeric comparison and range testing methods
 */
interface NumberAssertions {
  above(value: number, description?: string): Assertion;
  below(value: number, description?: string): Assertion;
  within(start: number, finish: number, description?: string): Assertion;
  approximately(value: number, delta: number, description?: string): Assertion;
  NaN(): Assertion;
  Infinity(): Assertion;
}

Number and Range Assertions - Numeric comparisons, range checks, and special values.

String Assertions

String prefix/suffix testing and content validation.

/**
 * String content testing methods
 */
interface StringAssertions {
  startWith(prefix: string, description?: string): Assertion;
  endWith(postfix: string, description?: string): Assertion;
}

String Assertions - String content testing and pattern matching.

Pattern Matching

Advanced pattern matching using regular expressions, functions, and object matchers.

/**
 * Pattern matching methods for any value type
 */
interface PatternMatchingAssertions {
  match(pattern: RegExp | Function | object, description?: string): Assertion;
  matchEach(pattern: RegExp | string | Function, description?: string): Assertion;
  matchEvery(pattern: RegExp | string | Function, description?: string): Assertion;
  matchAny(pattern: RegExp | string | Function, description?: string): Assertion;
  matchSome(pattern: RegExp | string | Function, description?: string): Assertion;
}

Pattern Matching - Advanced pattern matching for strings, collections, and objects.

Collection and Containment Assertions

Array and object containment, deep equality, and collection testing.

/**
 * Collection containment and deep testing methods
 */
interface ContainmentAssertions {
  containEql(obj: any): Assertion;
  containDeep(obj: any): Assertion;
  containDeepOrdered(obj: any): Assertion;
  eql(obj: any, description?: string): Assertion;
  deepEqual(obj: any, description?: string): Assertion;
}

Collection and Containment Assertions - Array/object containment and deep equality testing.

Error and Exception Assertions

Exception throwing, error handling, and error property testing.

/**
 * Exception and error testing methods
 */
interface ErrorAssertions {
  throw(): Assertion;
  throw(message: RegExp | string | Function, properties?: object): Assertion;
  throwError(): Assertion;
  throwError(message: RegExp | string | Function, properties?: object): Assertion;
}

Error and Exception Assertions - Exception testing and error property validation.

Promise Assertions

Async testing, promise states, and async assertion chaining.

/**
 * Promise state and async testing methods
 */
interface PromiseAssertions {
  Promise(): Assertion;
  fulfilled(): Promise<any>;
  rejected(): Promise<any>;
  fulfilledWith(obj: any): Promise<any>;
  rejectedWith(error: RegExp | string | Error, properties?: object): Promise<any>;
  finally: PromisedAssertion;
  eventually: PromisedAssertion;
}

Promise Assertions - Async testing, promise state checking, and async assertion chains.

Configuration and Extension

Library configuration, custom assertions, and plugin system.

/**
 * Configuration and extension methods
 */
interface ConfigurationMethods {
  extend(propertyName?: string, proto?: object): object;
  noConflict(descriptor?: object): Function;
  use(plugin: Function): Function;
  config: {
    checkProtoEql: boolean;
    plusZeroAndMinusZeroEqual: boolean;
  };
}

Configuration and Extension - Library configuration, prototype extension, and custom assertion plugins.

Static Methods

Should.js provides Node.js assert-compatible static methods that can be used without creating assertion chains:

/**
 * Static assertion methods compatible with Node.js assert module
 */
interface StaticMethods {
  // Core assertion methods
  fail(actual: any, expected: any, message?: string, operator?: string): void;
  ok(value: any, message?: string): void;
  
  // Equality testing
  equal(actual: any, expected: any, message?: string): void;
  notEqual(actual: any, expected: any, message?: string): void;
  deepEqual(actual: any, expected: any, message?: string): void;
  notDeepEqual(actual: any, expected: any, message?: string): void;
  strictEqual(actual: any, expected: any, message?: string): void;
  notStrictEqual(actual: any, expected: any, message?: string): void;
  
  // Exception testing
  throws(block: Function, error?: Function | RegExp, message?: string): void;
  doesNotThrow(block: Function, message?: string): void;
  ifError(err: any): void;
  
  // Existence testing
  exist(obj: any, message?: string): void;
  exists(obj: any, message?: string): void;
}

// Negated existence testing
interface StaticNotMethods {
  exist(obj: any, message?: string): void;
  exists(obj: any, message?: string): void;
}

Usage Examples

import should from 'should';

// Basic assertions
should.ok(true);
should.fail(1, 2, 'Values should be equal', '==');

// Equality testing
should.equal(42, 42);
should.notEqual('hello', 'world');
should.deepEqual({ a: 1 }, { a: 1 });
should.strictEqual('5', '5');

// Exception testing
should.throws(() => { throw new Error('test'); });
should.doesNotThrow(() => { return 'safe'; });
should.ifError(null); // Passes if no error

// Existence testing
should.exist('hello');
should.exist([1, 2, 3]);
should.not.exist(null);
should.not.exist(undefined);

These methods are compatible with Node.js built-in assert methods and provide the same functionality as their instance method counterparts.