Class Assert

Utility class for writing unit-test-style assertions. This class provides a set of static methods to perform common assertions such as checking equality, type, and exceptions, etc. In case of assertion failure, an AssertionError is thrown and the user can provide a descriptive message.

Index

Constructors

constructor

Methods

contains doesNotThrow equals fail isDefined isFalse isInstanceOf isNotInstanceOf isNotNull isNotType isNotUndefined isNull isTrue isType isUndefined notEquals throws

Constructors

constructor

new Assert(): Assert
Returns Assert

Methods

`Static`contains

contains(container: string | unknown[], value: unknown, message?: string): void
Asserts that an array or string contains a specified value or substring. For arrays, uses indexOf for shallow equality. For strings, uses indexOf for substring check. Throws AssertionError if the value is not found.
Parameters
- container: string | unknown[]
  The array or string to search.
- value: unknown
  The value (or substring) to search for.
- message: string = ""
  (Optional) Message to prefix in case of failure.
Returns void
- This method does not return a value.
Throws
AssertionError - If the value is not found.
Example
```
Assert.contains([1, 2, 3], 2, "Array should contain 2")
Assert.contains("hello world", "world", "String should contain 'world'")
Assert.contains([1, 2, 3], 4) // Fails
Assert.contains("hello world", "test") // Fails
Assert.contains([1,2,3], 2)
Assert.contains("hello world", "world")
```
- Defined in src/unit-test-framework.ts:529

`Static`doesNotThrow

doesNotThrow(fn: () => void, message?: string): void
Asserts that the provided function does NOT throw an error. If an error is thrown, an AssertionError is thrown with the provided message or details of the error.
Parameters
- fn: () => void
  A function that is expected to NOT throw. Must be passed as a function reference, e.g. () => codeThatShouldNotThrow().
- message: string = ""
  (Optional) Prefix for the error message if the assertion fails.
Returns void
- This method does not return a value.
Throws
AssertionError - If the function throws any error.
Example
```
Assert.doesNotThrow(() => {
  const x = 1 + 1
}, "Should not throw any error")
```
See
Assert.throws for the opposite assertion.
- Defined in src/unit-test-framework.ts:124

`Static`equals

equals<T>(actual: T, expected: T, message?: string): asserts actual is T
Asserts that two values are equal by type and value. Supports comparison of primitive types, one-dimensional arrays of primitives, and one-dimensional arrays of objects (deep equality via JSON.stringify). If the values differ, a detailed error is thrown. For arrays, mismatches include index, value, and type. For arrays of objects, a shallow comparison using JSON.stringify is performed. If a value cannot be stringified (e.g., due to circular references), it is treated as [unprintable value] in error messages and object equality checks.
Type Parameters
- T
Parameters
- actual: T
  The actual value.
- expected: T
  The expected value.
- message: string = ""
  (Optional) Prefix message included in the thrown error on failure.
Returns asserts actual is T
- Asserts that actual is of type T if the assertion passes.
Throws
AssertionError - If actual and expected are not equal.
Example
```
Assert.equals(2 + 2, 4, "Simple math")
Assert.equals(["a", "b"], ["a", "b"], "Array match")
Assert.equals([1, "2"], [1, 2], "Array doesn't match") // Fails
Assert.equals([{x:1}], [{x:1}], "Object array match") // Passes
Assert.equals([{x:1}], [{x:2}], "Object array mismatch") // Fails
```
See
Assert.notEquals for the opposite assertion.
- Defined in src/unit-test-framework.ts:158

`Static`fail

fail(message?: string): void
Fails the test by throwing an error with the provided message. This method is used to explicitly indicate that a test case has failed, regardless of any conditions or assertions.
Parameters
- Optionalmessage: string
  (Optional) The failure message to display. If not provided, a default Assertion failed message is used.
Returns void
- This method never returns, it always throws an error.
Throws
AssertionError - Always throws an AssertionError with the provided message.
Example
```
Assert.fail("This test should not pass")
```
- Defined in src/unit-test-framework.ts:309

`Static`isDefined

isDefined<T>(value: T, message?: string): asserts value is Exclude<T, undefined>
Asserts that the given value is defined (not undefined). Alias for isNotUndefined method.
Type Parameters
- T
Parameters
- value: T
  The value to check.
- message: string = ""
  (Optional) Message to prefix in case of failure.
Returns asserts value is Exclude<T, undefined>
- This method does not return a value.
Throws
AssertionError - If the value is undefined.
Example
```
Assert.isDefined(42, "Value should be defined")
Assert.isDefined(null, "Null is allowed, but not undefined")
Assert.isDefined(42)
Assert.isDefined(null)
```
See
- Assert.isNotUndefined for the opposite assertion.
- Assert.isUndefined for an alias that checks for undefined values.
- Defined in src/unit-test-framework.ts:503

`Static`isFalse

isFalse(value: unknown, message?: string): void
Asserts that the provided value is falsy. Throws AssertionError if the value is not falsy.
Parameters
- value: unknown
  The value to test for falsiness.
- message: string = ""
  (Optional) Message to prefix in case of failure.
Returns void
- This method does not return a value.
Throws
AssertionError - If the value is not falsy.
Example
```
Assert.isFalse(1 > 2, "Math sanity")
Assert.isFalse(null, "Null should be falsy")
Assert.isFalse(undefined, "Undefined should be falsy")
Assert.isFalse(false, "Boolean false should be falsy")
Assert.isFalse(0, "Zero should be falsy")
Assert.isFalse("", "Empty string should be falsy")
```
See
Assert.isTrue for the opposite assertion.
- Defined in src/unit-test-framework.ts:425

`Static`isInstanceOf

isInstanceOf(value: unknown, ctor: Function, message?: string): void
Asserts that the value is an instance of the specified constructor. Throws AssertionError if not.
Parameters
- value: unknown
  The value to check.
- ctor: Function
  The class/constructor function.
- message: string = ""
  Optional error message prefix.
Returns void
- This method does not return a value.
Throws
AssertionError - If the value is not an instance of the constructor.
Example
```
class MyClass {}
const instance = new MyClass()
Assert.isInstanceOf(instance, MyClass, "Should be an instance of MyClass")
Assert.isInstanceOf(instance, Object) // Passes, since all classes inherit from Object
Assert.isInstanceOf(42, MyClass) // Fails
```
See
Assert.isNotInstanceOf for the opposite assertion.
- Defined in src/unit-test-framework.ts:566

`Static`isNotInstanceOf

isNotInstanceOf(value: unknown, ctor: Function, message?: string): void
Asserts that the value is NOT an instance of the specified constructor. Throws AssertionError if it is.
Parameters
- value: unknown
  The value to check.
- ctor: Function
  The class/constructor function.
- message: string = ""
  Optional error message prefix.
Returns void
- This method does not return a value.
Throws
AssertionError - If the value is an instance of the constructor.
Example
```
class MyClass {}
const instance = new MyClass()
Assert.isNotInstanceOf(instance, String, "Should not be an instance of String")
Assert.isNotInstanceOf(instance, MyClass) // Fails
Assert.isNotInstanceOf(42, MyClass) // Passes, since 42 is not an instance of MyClass
```
See
Assert.isInstanceOf for the opposite assertion.
- Defined in src/unit-test-framework.ts:607

`Static`isNotNull

isNotNull<T>(value: T, message?: string): asserts value is NonNullable<T>
Asserts that the given value is not null. Provides a robust stringification of the value for error messages, guarding against unsafe or error-throwing toString() implementations. Narrows the type of value to NonNullable<T> if assertion passes.
Type Parameters
- T
Parameters
- value: T
  The value to test.
- message: string = ""
  Optional message to prefix in case of failure.
Returns asserts value is NonNullable<T>
- Narrows the type of value to NonNullable<T> if the assertion passes.
Throws
AssertionError if the value is null.
Example
```
Assert.isNotNull(42, "Value should not be null")
Assert.isNotNull(null, "Value should be null") // Fails
```
See
- Assert.isNull for the opposite assertion.
- Assert.isDefined for an alias that checks for defined values (not null or undefined).
- Defined in src/unit-test-framework.ts:285

`Static`isNotType

isNotType(
    value: unknown,
    type:
        | "string"
        | "number"
        | "bigint"
        | "boolean"
        | "symbol"
        | "undefined"
        | "object"
        | "function",
    message?: string,
): void
Asserts that a value is NOT of the specified primitive type.
Parameters
- value: unknown
  The value to check.
- type:
      | "string"
      | "number"
      | "bigint"
      | "boolean"
      | "symbol"
      | "undefined"
      | "object"
      | "function"
  The unwanted type as a string (string, number, etc.)
- message: string = ""
  Optional error message.
Returns void
- This method does not return a value.
Throws
AssertionError - If the type matches.
Example
```
isNotType("hello", "number"); // passes
isNotType(42, "string"); // passes
isNotType({}, "object"); // throws
isNotType(null, "object", "Should not be object"); // throws (null is object in JS)
```
Remarks
This method checks the type using typeof and throws an AssertionError if the type matches. The type parameter must be one of the following strings: string, number, boolean, object, function, undefined, symbol, or bigint.

See
Assert.isType for the positive assertion.
- Defined in src/unit-test-framework.ts:369

`Static`isNotUndefined

isNotUndefined<T>(
value: T,
message?: string,
): asserts value is Exclude<T, undefined>
Asserts that the given value is not undefined. Narrows the type to exclude undefined. Throws AssertionError if the value is undefined.
Type Parameters
- T
Parameters
- value: T
  The value to check.
- message: string = ""
  (Optional) Message to prefix in case of failure.
Returns asserts value is Exclude<T, undefined>
- This method does not return a value.
Throws
AssertionError - If the value is undefined.
Example
```
Assert.isNotUndefined(42, "Value should not be undefined")
Assert.isNotUndefined(null, "Null is allowed, but not undefined")
Assert.isNotUndefined(42)
Assert.isNotUndefined(null)
```
See
- Assert.isUndefined for the opposite assertion.
- Assert.isDefined for an alias that checks for defined values (not undefined).
- Defined in src/unit-test-framework.ts:477

`Static`isNull

isNull(value: unknown, message?: string): asserts value is null
Asserts that the given value is strictly null. Provides a robust stringification of the value for error messages, guarding against unsafe or error-throwing toString() implementations.
Parameters
- value: unknown
  The value to test.
- message: string = ""
  Optional message to prefix in case of failure.
Returns asserts value is null
- Narrows the type of 'value' to null if the assertion passes.
Throws
AssertionError if the value is not exactly null.
Example
```
Assert.isNull(null, "Value should be null")
Assert.isNull(undefined, "Value should not be undefined") // Fails
Assert.isNull(0, "Zero is not null") // Fails
Assert.isNull(null)
Assert.isNull(undefined) // Fails
Assert.isNull(0) // Fails
```
See
Assert.isDefined for an alias that checks for defined values (not null or undefined).
- Defined in src/unit-test-framework.ts:257

`Static`isTrue

isTrue(value: unknown, message?: string): asserts value
Asserts that the provided value is truthy. Throws AssertionError if the value is not truthy.
Parameters
- value: unknown
  The value to test for truthiness.
- message: string = ""
  (Optional) Message to prefix in case of failure.
Returns asserts value
- Narrows the type of value to its original type if the assertion passes.
Throws
AssertionError - If the value is not truthy.
Example
```
Assert.isTrue(1 < 2, "Math sanity")
Assert.isTrue("non-empty string", "String should be truthy")
```
See
Assert.isFalse for the opposite assertion.
- Defined in src/unit-test-framework.ts:398

`Static`isType

isType(
    value: unknown,
    type:
        | "string"
        | "number"
        | "bigint"
        | "boolean"
        | "symbol"
        | "undefined"
        | "object"
        | "function",
    message?: string,
): void
Asserts that a value is of the specified primitive type.
Parameters
- value: unknown
  The value to check.
- type:
      | "string"
      | "number"
      | "bigint"
      | "boolean"
      | "symbol"
      | "undefined"
      | "object"
      | "function"
  The expected type as a string (string, number, etc.)
- message: string = ""
  Optional error message.
Returns void
- This method does not return a value.
Throws
AssertionError - If the type does not match.
Example
```
isType("hello", "string"); // passes
isType(42, "number"); // passes
isType({}, "string"); // throws
isType([], "object", "Expected an object"); // passes
isType(null, "object", "Expected an object"); // throws
```
Remarks
This method checks the type using typeof and throws an AssertionError if the type does not match. It is useful for validating input types in functions or methods. The type parameter must be one of the following strings: string, number, boolean, object, function, undefined, symbol, or bigint. If the value is null, it will be considered an object, which is consistent with JavaScript's behavior.

See
Assert.isNotType for the opposite assertion.
- Defined in src/unit-test-framework.ts:336

`Static`isUndefined

isUndefined(value: unknown, message?: string): asserts value is undefined
Asserts that the given value is strictly undefined. Throws AssertionError if the value is not exactly undefined.
Parameters
- value: unknown
  The value to check.
- message: string = ""
  (Optional) Message to prefix in case of failure.
Returns asserts value is undefined
- Narrows the type of value to undefined if the assertion passes.
Throws
AssertionError - If the value is not undefined.
Example
```
Assert.isUndefined(void 0)
Assert.isUndefined(undefined)
Assert.isUndefined(null, "Null is not undefined") // Fails 
```
See
- Assert.isNotUndefined for the opposite assertion.
- Assert.isDefined for an alias that checks for defined values (not undefined).
- Defined in src/unit-test-framework.ts:450

`Static`notEquals

notEquals<T>(actual: T, notExpected: T, message?: string): void
Asserts that two values are not equal (deep comparison). For arrays and objects, uses deep comparison (via JSON.stringify). Throws AssertionError if the values are equal.
Type Parameters
- T
Parameters
- actual: T
  The actual value.
- notExpected: T
  The value that should NOT match.
- message: string = ""
  (Optional) Message to prefix in case of failure.
Returns void
- This method does not return a value.
Throws
AssertionError - If values are equal.
Example
```
Assert.notEquals(1, 2, "Numbers should not be equal")
Assert.notEquals([1, 2], [2, 1], "Arrays should not be equal")
Assert.notEquals({ a: 1 }, { a: 2 }, "Objects should not be equal")
Assert.notEquals(1, 2)
Assert.notEquals([1,2], [2,1])
```
See
Assert.equals for the opposite assertion.
- Defined in src/unit-test-framework.ts:226

`Static`throws

throws(
    fn: () => void,
    expectedErrorType?: Function,
    expectedMessage?: string,
    message?: string,
): asserts fn is () => never
Asserts that the provided function throws an error. Optionally checks the error type and message.
Parameters
- fn: () => void
  A function that is expected to throw an error. Must be passed as a function reference, e.g. () => codeThatThrows().
- OptionalexpectedErrorType: Function
  (Optional) Expected constructor of the thrown error (e.g., TypeError).
- OptionalexpectedMessage: string
  (Optional) Exact expected error message.
- message: string = ""
  (Optional) Additional prefix for the error message if the assertion fails.
Returns asserts fn is () => never
- Asserts that fn will throw an error if the assertion passes.
Throws
AssertionError - If no error is thrown, or if the thrown error does not match the expected type or message.
Example
```
Assert.throws(() => {
  throw new TypeError("Invalid")
}, TypeError, "Invalid", "Should throw TypeError")
```
See
Assert.doesNotThrow for the opposite assertion.
- Defined in src/unit-test-framework.ts:78

Class Assert

Index

Constructors

Methods

Constructors

constructor

Returns Assert

Methods

Staticcontains

Parameters

Returns void

Throws

Example

StaticdoesNotThrow

Parameters

Returns void

Throws

Example

See

Staticequals

Type Parameters

Parameters

Returns asserts actual is T

Throws

Example

See

Staticfail

Parameters

Returns void

Throws

Example

StaticisDefined

Type Parameters

Parameters

Returns asserts value is Exclude<T, undefined>

Throws

Example

See

StaticisFalse

Parameters

Returns void

Throws

Example

See

StaticisInstanceOf

Parameters

Returns void

Throws

Example

See

StaticisNotInstanceOf

Parameters

Returns void

Throws

Example

See

StaticisNotNull

Type Parameters

Parameters

Returns asserts value is NonNullable<T>

Throws

Example

See

StaticisNotType

Parameters

Returns void

Throws

Example

Remarks

See

StaticisNotUndefined

Type Parameters

Parameters

Returns asserts value is Exclude<T, undefined>

Throws

Example

See

StaticisNull

Parameters

Returns asserts value is null

`Static`contains

`Static`doesNotThrow

`Static`equals

`Static`fail

`Static`isDefined

`Static`isFalse

`Static`isInstanceOf

`Static`isNotInstanceOf

`Static`isNotNull

`Static`isNotType

`Static`isNotUndefined

`Static`isNull

`Static`isTrue

`Static`isType

`Static`isUndefined

`Static`notEquals

`Static`throws