diff --git a/docs/CUSTOM_MATCHERS.md b/docs/CUSTOM_MATCHERS.md new file mode 100644 index 0000000..8562634 --- /dev/null +++ b/docs/CUSTOM_MATCHERS.md @@ -0,0 +1,57 @@ +# 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`. diff --git a/docs/README.md b/docs/README.md index a3be4ff..02fc2f1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,4 @@ # Table of contents - [Writing tests](./WRITING_TESTS.md) +- [Extending with custom matchers](./CUSTOM_MATCHERS.md) diff --git a/package.json b/package.json index a952b82..a4141bd 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,8 @@ "license": "MIT", "packageManager": "yarn@3.5.0", "files": [ - "dist/**/*.js" + "dist/**/*.js", + "dist/**/*.d.ts" ], "bin": { "womm": "dist/cli.js" diff --git a/src/index.ts b/src/index.ts index 908e7dd..4bd70c5 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,4 +1,4 @@ export { default as test, it } from './testComponents/test' export { default as describe } from './testComponents/describe' -export { default as expect } from './testComponents/expect' +export { default as expect, Expect } from './testComponents/expect' export { beforeEach, afterEach } from './testComponents/hooks' diff --git a/src/testComponents/expect.ts b/src/testComponents/expect.ts index b21fba4..18f7875 100644 --- a/src/testComponents/expect.ts +++ b/src/testComponents/expect.ts @@ -20,7 +20,7 @@ class TestAssertionFailed extends Error { } } -class Expect { +export class Expect { static #rawMatchers: RawMatchersMap = { comparisonMatchers: [], noArgMatchers: [],