Creating Custom Jasmine Matchers for Type-Safe Array Validation

The Problem: Repetitive Array Type Checking

When testing data pipelines or API responses, you often need to verify that a collection contains only a specific data type. Using standard Jasmine matchers like toEqual() or looping through an array with forEach() inside a spec leads to verbose tests and generic failure messages that don't explain why the validation failed.

The solution is a Custom Matcher. This allows you to encapsulate the validation logic into a readable method—such as toBeNumericArray()—that provides a precise failure message when a non-numeric value is encountered.

Prerequisites

• Jasmine (v3.0 or later) installed in your project.
• A JavaScript environment (Node.js or Browser) where your specs are executed.
• Basic familiarity with the expect() syntax.

Implementing the Numeric Array Matcher

A custom matcher is a factory function that returns a compare function. This compare function must return an object containing a pass boolean and a message string.

// custom-matchers.js
const NumericArrayMatcher = {
    compare: function(actual) {
        // 1. Handle non-array inputs to avoid runtime errors
        if (!Array.isArray(actual)) {
            return {
                pass: false,
                message: `Expected ${actual} to be an Array, but it was ${typeof actual}.`
            };
        }

        // 2. Check if every element is a number and not NaN
        const allNumeric = actual.every(item => typeof item === 'number' && !isNaN(item));

        if (allNumeric) {
            return {
                pass: true,
                message: `Expected array not to contain only numbers, but it did.`
            };
        } else {
            // Find the first offending element for a better error message
            const firstInvalid = actual.find(item => typeof item !== 'number' || isNaN(item));
            return {
                pass: false,
                message: `Expected array to contain only numbers, but found ${typeof firstInvalid}: ${firstInvalid}.`
            };
        }
    }
};

Registering the Matcher

To avoid duplicate registration errors, add the matcher in a beforeEach block or a global helper file. If you are using a test runner like Karma or the Jasmine CLI, place this in a helper file that loads before your specs.

describe("Data Validation Suite", () => {
    beforeEach(() => {
        jasmine.addMatchers({ 
            toBeNumericArray: NumericArrayMatcher.compare 
        });
    });

    it("should validate a clean numeric array", () => {
        expect([1, 2, 3.5, 100]).toBeNumericArray();
    });

    it("should fail when a string is present", () => {
        expect([1, "2", 3]).not.toBeNumericArray();
    });
});

Technical Decision: Handling Edge Cases

When designing the compare function, consider how the matcher should behave with empty arrays or NaN. In the implementation above, Array.prototype.every() returns true for empty arrays. This is mathematically consistent (a vacuous truth), but if your business logic requires the array to be non-empty, you must add a length check.

Input Case	Expected Result	Reasoning
[1, 2, 3]	Pass	All elements are numbers.
[]	Pass	No elements violate the numeric rule.
[1, NaN, 3]	Fail	NaN is technically a number type but usually invalid for data.
"not an array"	Fail	Type mismatch handled by Array.isArray check.

Verification and Diagnostics

To verify the matcher is working correctly, run your specs and intentionally trigger a failure. A well-implemented matcher should not just say Expected false to be true, but should output the custom message defined in the compare function.

Expected Failure Output:
Expected array to contain only numbers, but found string: 2.

Risk Note: Never mutate the actual value inside the compare function (e.g., avoid actual.sort() or actual.pop()). Mutating the input can cause subsequent tests in the same suite to fail unpredictably.

Rollback and Cleanup

Because jasmine.addMatchers modifies the global Jasmine environment for the duration of the test run, there is no built-in "removeMatcher" method. To isolate matchers to a specific suite, ensure they are registered within a describe block's beforeEach rather than a global configuration file.