works-on-my-machine/docs/CUSTOM_MATCHERS.md

Adding custom matchers

You can extend the set of matchers available by implementing your own and extending womm with them. This way, you can extend the library as needed by your use case.

Matchers come in two flavours: comparison matchers and no-args matchers.

Comparison & No-Arg matchers

A comparison matcher takes two values (and an optional negation marker):

function myComparisonMatcher(value, other, negated = false) {
    // Validate that value and other are comparable.
}

A no-arg matcher asserts the properties of the value passed to expect, but does not allow any additional inputs:

function myNoArgMatcher(value, negated = false) {
    // Validate `value` on its own.
}

Either types of matchers are expected to implement their own negation variant, which is triggered with the negated argument is truthy. In those cases, the check should be inverted such that expect(value).not.myMatcher(...) is the inverse of expect(value).myMatcher.

Return values

Matchers are expected to return a MatcherReport object of the form:

interface MatcherReport {
    // Whether the assertion passed or not.
    pass: boolean

    // Message to attach to failures, blank on a passing test.
    message: string
}

Extending Expect with new matchers

Once your custom matcher is defined, you can extend the Expect class with it to make it available:

import { Expect } from 'works-on-my-machine`

function myMatcher(value, other, negated = false) {
    // Validation...
}

Expect.addMatcher(myMatcher)

Any uses of expect past this point will have access to myMatcher as a matcher, as well as the negation variant of it through chaining with .not.