diff --git a/docs/modules/README.md b/docs/modules/README.md index 5c8dda3..3365a92 100644 --- a/docs/modules/README.md +++ b/docs/modules/README.md @@ -75,6 +75,7 @@ ESLint plugin. - [`lodash`, `underscore` and related](./lodash-underscore.md) - [`materialize-css`](./materialize-css.md) - [`md5`](./md5.md) +- [`mockdate`](./mockdate.md) - [`mkdirp`](./mkdirp.md) - [`moment.js`](./moment.md) - [`npm-run-all`](./npm-run-all.md) diff --git a/docs/modules/mockdate.md b/docs/modules/mockdate.md new file mode 100644 index 0000000..405fdae --- /dev/null +++ b/docs/modules/mockdate.md @@ -0,0 +1,65 @@ +--- +description: Modern alternatives to the mockdate package for mocking time in tests +--- + +# Replacements for `mockdate` + +`mockdate` is mainly used in tests, and modern test runners already include built-in APIs for mocking time without pulling in an extra dependency. + +## `vitest` + +[`vitest`](https://vitest.dev/guide/mocking.html#mock-the-current-date) provides `vi.useFakeTimers()` and `vi.setSystemTime()` for mocking the current date during tests. + +```ts +import MockDate from 'mockdate' // [!code --] +import { vi, test, expect } from 'vitest' // [!code ++] + +test('freeze date', () => { + MockDate.set('2026-01-01') // [!code --] + vi.useFakeTimers() // [!code ++] + vi.setSystemTime(new Date('2026-01-01')) // [!code ++] + + expect(new Date().toISOString()).toBe('2026-01-01T00:00:00.000Z') + + MockDate.reset() // [!code --] + vi.useRealTimers() // [!code ++] +}) +``` + +## `node:test` + +[`node:test`](https://nodejs.org/en/learn/test-runner/mocking#time) supports mocking time via `mock.timers` since node 20.4.0 and later. + +```ts +import MockDate from 'mockdate' // [!code --] +import { test } from 'node:test' // [!code ++] +import assert from 'node:assert/strict' // [!code ++] + +test('freeze date', (t) => { + MockDate.set('2026-01-01') // [!code --] + t.mock.timers.enable({ apis: ['Date'], now: new Date('2026-01-01') }) // [!code ++] + + assert.equal(new Date().toISOString(), '2026-01-01T00:00:00.000Z') + + MockDate.reset() // [!code --] +}) +``` + +## `bun:test` + +[`bun:test`](https://bun.com/docs/guides/test/mock-clock) provides `mock.timers.enable()` for mocking time in tests. + +```ts +import MockDate from 'mockdate' // [!code --] +import { test, expect, mock } from 'bun:test' // [!code ++] + +test('freeze date', () => { + MockDate.set('2026-01-01') // [!code --] + mock.timers.enable({ now: new Date('2026-01-01') }) // [!code ++] + + expect(new Date().toISOString()).toBe('2026-01-01T00:00:00.000Z') + + MockDate.reset() // [!code --] + mock.timers.reset() // [!code ++] +}) +``` diff --git a/manifests/preferred.json b/manifests/preferred.json index c06ac71..e317b34 100644 --- a/manifests/preferred.json +++ b/manifests/preferred.json @@ -2394,6 +2394,12 @@ "replacements": ["fs.mkdir"], "url": {"type": "e18e", "id": "mkdirp"} }, + "mockdate": { + "type": "module", + "moduleName": "mockdate", + "replacements": ["node:test", "vitest", "bun:test"], + "url": {"type": "e18e", "id": "mockdate"} + }, "moment": { "type": "module", "moduleName": "moment", @@ -2831,10 +2837,7 @@ "featureId": "async-clipboard", "compatKey": "api.Clipboard" }, - "url": { - "type": "mdn", - "id": "Web/API/Clipboard_API" - } + "url": {"type": "mdn", "id": "Web/API/Clipboard_API"} }, "Date": { "id": "Date", @@ -2931,6 +2934,11 @@ }, "url": {"type": "node", "id": "api/module.html#modulebuiltinmodules"} }, + "bun:test": { + "id": "bun:test", + "type": "native", + "url": "https://bun.com/docs/test" + }, "concurrently": { "id": "concurrently", "type": "documented", @@ -3288,6 +3296,12 @@ "nodeFeatureId": {"moduleName": "node:stream"}, "url": {"type": "node", "id": "api/stream.html"} }, + "node:test": { + "id": "node:test", + "type": "native", + "nodeFeatureId": {"moduleName": "test"}, + "url": {"type": "node", "id": "api/test.html"} + }, "npm-run-all2": { "id": "npm-run-all2", "type": "documented", @@ -3542,6 +3556,12 @@ "nodeFeatureId": {"moduleName": "node:util", "exportName": "types"}, "url": {"type": "node", "id": "api/util.html#utiltypes"} }, + "vitest": { + "id": "vitest", + "type": "documented", + "url": {"type": "e18e", "id": "mockdate"}, + "replacementModule": "vitest" + }, "webpack-bundle-analyzer": { "id": "webpack-bundle-analyzer", "type": "documented",