Marc Cataford
29202908d4
* feat: expose Expect to allow custom matcher extensions * feat: include generated types * docs: document custom matchers
57 lines
1.7 KiB
Markdown
57 lines
1.7 KiB
Markdown
# 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):
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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`.
|