Custom Matchers

← Table Driven Tests Extending Jest Matchers →

∙ Jest

Custom Matchers focuses on a domain-specific assertion expressed as a reusable matcher. It uses `expect.extend()` to confirm failures reporting a clear domain message and received value.

📝Syntax

expect.extend({ toBeValid(received) { ... } })

custom-matchers.test.js

📝 Jest Example

// Topic: Custom Matchers
expect.extend({
  toBeEven(value) {
    return { pass: value % 2 === 0, message: () => 'expected an even number' };
  }
});
test('is even', () => expect(4).toBeEven());

👁 Expected Result

💡 Run the test from isolated state and read the matcher diff when it fails.

👀Output

Custom Matchers: pASS — is even

🔍Line-by-Line Explanation

Line	Meaning
`expect.extend({`	In Custom Matchers, line 2 implements setup, action, or verification for this example.
`toBeEven(value) {`	In Custom Matchers, line 3 implements setup, action, or verification for this example.
`return { pass: value % 2 === 0, message: () => 'expected an even number' };`	In Custom Matchers, line 4 implements setup, action, or verification for this example.
`}`	In Custom Matchers, line 5 implements setup, action, or verification for this example.
`});`	In Custom Matchers, line 6 implements setup, action, or verification for this example.
`test('is even', () => expect(4).toBeEven());`	In Custom Matchers, line 7 declares a named Jest test.

🌐Real-World Uses

1Use Custom Matchers to verify a domain-specific assertion expressed as a reusable matcher.
2Custom Matchers is valuable in real application testing when the test must prove failures reporting a clear domain message and received value.
3A useful failure record for Custom Matchers contains custom pass/fail message and matcher context.

⚠Common Mistakes

1Custom Matchers commonly fails because of hiding complex test setup inside a matcher.
2Starting Custom Matchers without a repeated assertion with stable domain semantics makes the result nondeterministic.
3For Custom Matchers, executing code without asserting failures reporting a clear domain message and received value is incomplete.
4Using Custom Matchers to cover one-off assertions used only once creates the wrong test boundary.

✓Best Practices

1Prepare a repeated assertion with stable domain semantics before running Custom Matchers.
2Implement Custom Matchers with `expect.extend()`.
3Make the central Custom Matchers assertion prove failures reporting a clear domain message and received value.
4Preserve custom pass/fail message and matcher context whenever Custom Matchers fails.

💡Core behavior

1Custom Matchers target: a domain-specific assertion expressed as a reusable matcher.
2Custom Matchers API: `expect.extend()`.
3Custom Matchers expected result: failures reporting a clear domain message and received value.
4Custom Matchers primary risk: hiding complex test setup inside a matcher.

💡Implementation steps

1Set up Custom Matchers with a repeated assertion with stable domain semantics.
2For Custom Matchers, invoke the behavior that produces a domain-specific assertion expressed as a reusable matcher.
3In Custom Matchers, apply `expect.extend()` to the observed result.
4Finish Custom Matchers by asserting failures reporting a clear domain message and received value.

💡Verification

1Run Custom Matchers once with input that should satisfy failures reporting a clear domain message and received value.
2Add a negative Custom Matchers case that must produce a readable failure.
3Repeat Custom Matchers from fresh state to reveal shared-data or ordering dependencies.
4Diagnose Custom Matchers through custom pass/fail message and matcher context.

💡Scope

1Custom Matchers covers a domain-specific assertion expressed as a reusable matcher.
2Custom Matchers does not directly prove one-off assertions used only once.
3Mocks and fixtures used by Custom Matchers must continue to match its real dependency contracts.
4For evidence outside the Custom Matchers process boundary, prefer ordinary Jest matchers.

✅Summary

Custom Matchers setup: a repeated assertion with stable domain semantics.
Custom Matchers action: `expect.extend()`.
Custom Matchers assertion: failures reporting a clear domain message and received value.
Custom Matchers diagnostics: custom pass/fail message and matcher context.
Custom Matchers boundary: choose ordinary Jest matchers for one-off assertions used only once.

🧑‍💻Interview Questions

Q1. What does Custom Matchers verify?

Answer: Custom Matchers verifies a domain-specific assertion expressed as a reusable matcher.

Q2. Which Jest API is central to Custom Matchers?

Answer: The central Custom Matchers API is `expect.extend()`.

Q3. What proves Custom Matchers passed?

Answer: A passing Custom Matchers test shows failures reporting a clear domain message and received value.

Q4. What makes Custom Matchers unreliable?

Answer: A common Custom Matchers cause is hiding complex test setup inside a matcher.

Q5. When should another test type replace Custom Matchers?

Answer: Replace Custom Matchers with ordinary Jest matchers for one-off assertions used only once.

🎯Quick Quiz

Which approach correctly implements Custom Matchers?

←

PreviousTable Driven Tests

Jest Roadmap

NextExtending Jest Matchers →