Add toBeSimilarDate matcher

[madriesen]

What

Add a new Jest matcher toBeSimilarDate that checks if two Date objects are approximately equal within a configurable precision (default 50ms). This matcher complements Jest Extended by providing a convenient way to compare dates in tests with minor timing differences.

Usage example:

const date = new Date()
const closeDate = new Date(date.getTime() + 30)

expect(date).toBeSimilarDate(closeDate)       // passes
expect(date).toBeSimilarDate(closeDate, 20)   // fails, precision set to 20ms

Why

In many tests involving timestamps or asynchronous operations, exact date equality is too strict. Minor differences in milliseconds can cause flaky tests. This matcher provides a clear, readable, and safe way to assert that dates are "close enough," improving test reliability and readability.

Notes

Housekeeping

• Unit tests
• Documentation is up to date
• No additional lint warnings
• Typescript definitions are added/updated where relevant

[changeset-bot]

⚠️ No Changeset found

Latest commit: 151e7f8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR