tessl/npm-should

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

—

Pending

Overview

Eval results

Files

Number and Range Assertions

Name: tessl/npm-should
Author: tessl

Methods for numeric comparisons, range validation, and testing special number values.

Comparison Assertions

above() / greaterThan()

Test that a number is greater than a specified value.

/**
 * Assert that the number is greater than the specified value
 * @param value - The value to compare against
 * @param description - Optional error message
 * @returns This assertion for chaining
 */
above(value: number, description?: string): Assertion;
greaterThan(value: number, description?: string): Assertion;

Usage:

import should from 'should';

(10).should.be.above(5);
(3.14).should.be.greaterThan(3);
(-5).should.be.above(-10);

// With description
const score = 85;
score.should.be.above(80, 'Score should be above passing grade');

// Chaining with other assertions
const temperature = 25.5;
temperature.should.be.above(20).and.be.a.Number();

below() / lessThan()

Test that a number is less than a specified value.

/**
 * Assert that the number is less than the specified value
 * @param value - The value to compare against
 * @param description - Optional error message
 * @returns This assertion for chaining
 */
below(value: number, description?: string): Assertion;
lessThan(value: number, description?: string): Assertion;

Usage:

(5).should.be.below(10);
(2.5).should.be.lessThan(3);
(-10).should.be.below(-5);

// With description
const age = 16;
age.should.be.below(18, 'Age should be below adult threshold');

// Chaining
const price = 99.99;
price.should.be.below(100).and.be.above(90);

aboveOrEqual() / greaterThanOrEqual()

Test that a number is greater than or equal to a specified value.

/**
 * Assert that the number is greater than or equal to the specified value
 * @param value - The value to compare against
 * @param description - Optional error message
 * @returns This assertion for chaining
 */
aboveOrEqual(value: number, description?: string): Assertion;
greaterThanOrEqual(value: number, description?: string): Assertion;

Usage:

(10).should.be.aboveOrEqual(10); // Equal case
(15).should.be.aboveOrEqual(10); // Greater case
(0).should.be.greaterThanOrEqual(0);

// Minimum value validation
const minAge = 18;
const userAge = 18;
userAge.should.be.aboveOrEqual(minAge, 'User must meet minimum age');

belowOrEqual() / lessThanOrEqual()

Test that a number is less than or equal to a specified value.

/**
 * Assert that the number is less than or equal to the specified value
 * @param value - The value to compare against
 * @param description - Optional error message
 * @returns This assertion for chaining
 */
belowOrEqual(value: number, description?: string): Assertion;
lessThanOrEqual(value: number, description?: string): Assertion;

Usage:

(5).should.be.belowOrEqual(10); // Less case
(10).should.be.belowOrEqual(10); // Equal case
(-5).should.be.lessThanOrEqual(0);

// Maximum value validation
const maxScore = 100;
const userScore = 95;
userScore.should.be.belowOrEqual(maxScore, 'Score cannot exceed maximum');

Range Testing

within()

Test that a number falls within a specified range (inclusive).

/**
 * Assert that the number is within the specified range (inclusive)
 * @param start - Range start value (inclusive)
 * @param finish - Range end value (inclusive)
 * @param description - Optional error message
 * @returns This assertion for chaining
 */
within(start: number, finish: number, description?: string): Assertion;

Usage:

(5).should.be.within(1, 10);
(10).should.be.within(10, 20); // Boundaries are inclusive
(15.5).should.be.within(15, 16);

// Temperature range validation
const temperature = 22.5;
temperature.should.be.within(20, 25, 'Temperature should be in comfort range');

// Percentage validation
const progress = 75;
progress.should.be.within(0, 100).and.be.a.Number();

// Negative ranges
const value = -5;
value.should.be.within(-10, 0);

approximately()

Test that a number is approximately equal to another number within a delta.

/**
 * Assert that the number is approximately equal to expected within delta
 * @param expected - The expected value
 * @param delta - The allowed difference (tolerance)
 * @param description - Optional error message
 * @returns This assertion for chaining
 */
approximately(expected: number, delta: number, description?: string): Assertion;

Usage:

(3.14159).should.be.approximately(3.14, 0.01);
(10.05).should.be.approximately(10, 0.1);
(0.1 + 0.2).should.be.approximately(0.3, 0.0001); // Floating point precision

// Scientific calculations
const measurement = 9.807; // Gravity
measurement.should.be.approximately(9.8, 0.01, 'Gravity measurement within tolerance');

// Large numbers
const population = 1000500;
population.should.be.approximately(1000000, 1000);

Special Number Values

NaN()

Test that a value is NaN (Not a Number).

/**
 * Assert that the value is NaN
 * @returns This assertion for chaining
 */
NaN(): Assertion;

Usage:

NaN.should.be.NaN();
(0/0).should.be.NaN();
Number('invalid').should.be.NaN();
parseInt('not-a-number').should.be.NaN();

// Math operations resulting in NaN
const result = Math.sqrt(-1);
result.should.be.NaN();

// NaN is still type 'number'
NaN.should.be.NaN().and.be.a.Number();

Infinity()

Test that a value is positive or negative Infinity.

/**
 * Assert that the value is positive or negative Infinity
 * @returns This assertion for chaining
 */
Infinity(): Assertion;

Usage:

Infinity.should.be.Infinity();
(-Infinity).should.be.Infinity();
(1/0).should.be.Infinity();
(-1/0).should.be.Infinity();

// Division by zero
const positiveInf = Number.POSITIVE_INFINITY;
positiveInf.should.be.Infinity();

const negativeInf = Number.NEGATIVE_INFINITY;
negativeInf.should.be.Infinity();

// Infinity is still type 'number'
Infinity.should.be.Infinity().and.be.a.Number();

Practical Examples

Range Validation

function validateAge(age) {
  age.should.be.a.Number();
  age.should.be.within(0, 150);
  age.should.not.be.NaN();
}

function validatePercentage(percent) {
  percent.should.be.a.Number()
    .and.be.within(0, 100)
    .and.not.be.Infinity()
    .and.not.be.NaN();
}

Mathematical Calculations

// Testing mathematical results
const result = Math.PI * 2;
result.should.be.approximately(6.283, 0.001);

// Testing ratios
const ratio = 22/7; // Approximation of PI
ratio.should.be.approximately(Math.PI, 0.01);

// Testing geometric calculations
const area = Math.PI * Math.pow(5, 2); // Circle area, radius 5
area.should.be.above(75).and.be.below(80);

Financial Calculations

// Currency precision
const price = 19.99;
const tax = price * 0.08;
const total = price + tax;

total.should.be.approximately(21.59, 0.01);
total.should.be.above(price);

// Percentage calculations
const discount = 0.15;
const discountAmount = price * discount;
const finalPrice = price - discountAmount;

finalPrice.should.be.below(price);
finalPrice.should.be.approximately(16.99, 0.01);

Scientific Measurements

// Physical constants
const speedOfLight = 299792458; // m/s
speedOfLight.should.be.approximately(3e8, 1e6);

// Measurement tolerance
const measurement = 9.81; // gravity
measurement.should.be.within(9.8, 9.82);
measurement.should.be.approximately(9.8, 0.1);

Edge Cases and Error Handling

// Testing for invalid calculations
const invalidResult = Math.sqrt(-1);
invalidResult.should.be.NaN();

// Division by zero
const infinite = 1/0;
infinite.should.be.Infinity();

// Very large numbers
const veryLarge = Number.MAX_VALUE;
veryLarge.should.be.above(1e300);
veryLarge.should.not.be.Infinity();

// Very small numbers
const verySmall = Number.MIN_VALUE;
verySmall.should.be.above(0);
verySmall.should.be.below(1);

Chaining and Negation

All number assertions support chaining and negation:

const value = 42;

// Chaining multiple conditions
value.should.be.a.Number()
  .and.be.above(40)
  .and.be.below(50)
  .and.not.be.NaN()
  .and.not.be.Infinity();

// Range with negation
value.should.not.be.within(50, 100);
value.should.not.be.approximately(50, 5);

// Special values negation
value.should.not.be.NaN();
value.should.not.be.Infinity();

Install with Tessl CLI