{"id":13370,"library":"jest-date","title":"Jest Date Matchers","description":"jest-date is a utility library providing custom Jest matchers specifically designed for comparing and asserting dates. It simplifies date-related tests by offering a declarative API, such as `toBeBefore`, `toBeSameDayAs`, and `toBeMonday`, eliminating the need for repetitive date manipulation logic in test assertions. The current stable version is 1.1.6, and while no explicit release cadence is stated, its versioning suggests incremental updates. A key differentiator is the helpful, descriptive failure messages it provides, indicating precise differences (e.g., '1 second after' or '3 months after') rather than generic assertion failures, making debugging significantly easier for developers. It leverages underlying date utility libraries, abstracting their complexity for focused testing scenarios.","status":"active","version":"1.1.6","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/pkuczynski/jest-date","tags":["javascript","date","date-fns","jest","jest date","typescript"],"install":[{"cmd":"npm install jest-date","lang":"bash","label":"npm"},{"cmd":"yarn add jest-date","lang":"bash","label":"yarn"},{"cmd":"pnpm add jest-date","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This import globally extends Jest's `expect` object with all provided date matchers. For TypeScript, ensure this is placed in a `.ts` setup file (e.g., `setupTests.ts`) to correctly include global type definitions for `expect`.","wrong":"require('jest-date');","symbol":"Global Extention","correct":"import 'jest-date';"},{"note":"Allows importing specific matchers for manual extension of `expect`. When using this pattern, you must explicitly call `expect.extend({ toBeBefore, toBeSameMonthAs })`. This method does NOT automatically provide type definitions for `expect` in TypeScript; manual type augmentation might be required if not using the global import elsewhere.","wrong":"import toBeBefore from 'jest-date/matchers';","symbol":"Specific Matchers","correct":"import { toBeBefore, toBeSameMonthAs } from 'jest-date/matchers';"},{"note":"The library ships with TypeScript types. The recommended way to include these types is to use the global `import 'jest-date'` statement within a TypeScript setup file (e.g., `jest.setup.ts`). Direct type imports are generally not necessary or provided.","symbol":"TypeScript Types","correct":"// Types are automatically included with `import 'jest-date'` in a .ts setup file."}],"quickstart":{"code":"import 'jest-date';\n\ndescribe('jest-date matchers', () => {\n  const date1 = new Date('2023-01-15T10:00:00.000Z');\n  const date2 = new Date('2023-01-15T11:00:00.000Z');\n  const date3 = new Date('2023-01-16T10:00:00.000Z');\n  const date4 = new Date('2023-02-15T10:00:00.000Z');\n\n  test('should check if a date is before another', () => {\n    expect(date1).toBeBefore(date2);\n  });\n\n  test('should check if a date is on the same day', () => {\n    expect(date1).toBeSameDayAs(date2);\n    expect(date1).not.toBeSameDayAs(date3);\n  });\n\n  test('should check if a date is a Monday', () => {\n    const monday = new Date('2023-01-16T10:00:00.000Z'); // Jan 16, 2023 was a Monday\n    expect(monday).toBeMonday();\n  });\n\n  test('should provide detailed failure messages', () => {\n    // This test will intentionally fail to demonstrate the helpful message\n    const futureDate = new Date('2024-01-01T00:00:00.000Z');\n    const pastDate = new Date('2023-01-01T00:00:00.000Z');\n    // expect(futureDate).toBeBefore(pastDate); // Would fail with 'Expected date 2024-01-01T00:00:00.000Z to be before 2023-01-01T00:00:00.000Z, but it was 1 year after.'\n  });\n});\n","lang":"typescript","description":"This quickstart demonstrates how to install `jest-date`, configure it in a Jest setup file, and use various custom matchers like `toBeBefore`, `toBeSameDayAs`, and `toBeMonday` to assert date comparisons in tests, highlighting their readability and expressive failure messages."},"warnings":[{"fix":"For full type support, use the global import `import 'jest-date';` in a `.ts` Jest setup file (e.g., `jest.setup.ts`). If you must use selective imports, you will need to manually augment Jest's `Expect` interface in your project's `d.ts` files.","message":"When using TypeScript, importing specific matchers (e.g., `import { toBeBefore } from 'jest-date/matchers'`) for manual `expect.extend()` does not automatically provide type definitions for the `expect` object. This can lead to TypeScript errors like 'Property 'toBeBefore' does not exist on type 'Expect<any>''.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `import 'jest-date';` is present in a file configured in Jest's `setupFilesAfterEnv` option. For example, add `\"setupFilesAfterEnv\": [\"<rootDir>/jest.setup.ts\"]` to your `jest.config.js` and create `jest.setup.ts` with the import.","message":"Forgetting to import `jest-date` in a Jest setup file (or at all) will result in matchers not being available, leading to runtime errors like 'expect(...).toBeBefore is not a function'.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you have `import 'jest-date';` in your Jest setup file (e.g., `jest.setup.ts`) and that this file is correctly referenced in your `jest.config.js` under `setupFilesAfterEnv`.","cause":"The TypeScript compiler cannot find the type definitions for `jest-date` matchers on the `expect` object.","error":"Property 'toBeSameDayAs' does not exist on type 'Expect<any>'."},{"fix":"Verify that `import 'jest-date';` is correctly placed and executed in your Jest test environment's setup, typically within a file specified by Jest's `setupFilesAfterEnv` configuration option.","cause":"The `jest-date` matchers have not been loaded and extended into Jest's `expect` object.","error":"TypeError: expect(...).toBeBefore is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}