Helpers you can use in tests that relate to the passage of time (i.e. code that
65 | involves setTimeout, setInterval, new Date(), Date.now(), etc.). Allows
66 | you to "set the clock" to a particular point in time, advancing any setTimeout
67 | or setInterval calls that need advancing at the same time. Makes it possible
68 | (even pleasant!) to test code that would normally be dependent on the passage of
69 | time, such as scheduled events.
This helper library was born out of 72 | adding cron functionality to 73 | Graphile Worker and needing a reliable way 74 | to test it.
75 |If you find this useful, please give it a star ⭐
76 | 77 |For full documentation, please 80 | click the headers. The following acts as a quick-reference.
81 | 82 |setupFakeTimers()Import and call the setupFakeTimers helper at the top of your test file:
import { setupFakeTimers } from "jest-time-helpers";
86 | const { setTime } = setupFakeTimers();
87 | Then inside your tests you can call setTime(timestamp) to pretend that the
89 | system time is the timestamp you gave. When you set the timestamp to a value
90 | after the previous timestamp, all timers (setTimeout, setInterval, etc) will
91 | be advanced by that amount, as well as the "clock". When you set the timestamp
92 | to a value before the previous timestamp, only the clock will be updated and no
93 | timeouts/intervals will be effected.
Example:
95 |const REFERENCE_TIMESTAMP = 950536800000; /* 14th February 2000, 2pm UTC */
96 |
97 | test("new Date().toISOString() returns the expected timestamp", () => {
98 | setTime(REFERENCE_TIMESTAMP);
99 | // Note, time may have advanced a millisecond or two, so we can't be too precise
100 | expect(new Date().toISOString()).toMatch(/^2000-02-14T14:00:0.*Z$/);
101 | });
102 | sleep(ms: number)A trivial method that returns a promise that resolves after the given number of 107 | real-time milliseconds. The important part about this method (as opposed to one 108 | that you might write yourself) is that it is not inhibited or influenced by fake 109 | timers.
110 | 111 |sleepUntil(condition: () => void, maxDuration = 2000, pollInterval = 2)Polls the condition callback every pollInterval milliseconds, and resolves
114 | success when condition() returns a truthy value. If maxDuration elapses
115 | before condition() returns true, returns a rejected promise.
Useful for waiting on external actions without putting arbitrary sleeps in your 117 | code (e.g. waiting for a database record to be created).
118 |Like sleep(), it is not inhibited or influenced by fake timers.
SECOND - number of milliseconds in a secondMINUTE - number of milliseconds in a minuteHOUR - number of milliseconds in a hourDAY - number of milliseconds in a dayWEEK - number of milliseconds in a weekTo help us develop software sustainably under the MIT license, we ask all 133 | individuals and businesses that use our software to help support its ongoing 134 | maintenance and development via sponsorship.
135 | 136 |Checkout the repository, then run the following commands:
142 |yarn
143 | yarn test
144 | Generated using TypeDoc
195 |One hour in milliseconds
114 |One minute in milliseconds
129 |One second in milliseconds
144 |One week in milliseconds
159 |Sets up fake timers and Date implementation within your Jest test file. You 181 | should call this at the top of the file (not within a test or an 182 | after/before); tests that need fake timers should go into their own test 183 | file.
184 |Returns an object containing a setTime function which you can use to set
186 | the current (fake) date within your test to a particular JavaScript
187 | timestamp (number of milliseconds since 1970-01-01T00:00:00Z).
Enables the jest.useFakeTimers() integration, and overwrites global.Date
189 | with a custom function that automatically applies your test file's given
190 | offset.
Returns the real-world current timestamp (unaffected by fake timers).
206 |Sets the offset such that a call to Date.now() (or new Date()) would
226 | return this timestamp if called immediately (but time continues to
227 | progress as expected after this). Also advances the timers by the
228 | difference from the previous offset, if positive. Setting time backwards
229 | is allowed (like setting back the system clock on a computer), but will
230 | not advance (or undo the advancement of) any timers.
Since advancing the time a few hours might not run all the intermediary 233 | code quite right, we actually step it up by a configurable increment 234 | (defaults to one minute) at a time. Setting time backwards (no matter how 235 | far back) is done all at once.
236 |the target timestamp
243 |the maximum we should advance time by at once in order to step towards timestamp
Wait a number of milliseconds of real time (not mocked time); useful for 278 | allowing the runloop or external systems to advance.
279 |Polls until the condition passes.
307 |Polls the condition callback every pollInterval ms of real time. If/when
309 | it returns a truthy value, resolves successfully. If maxDuration is
310 | exceeded before condition() returns true, rejects with an error.
a callback function that should return true when no more sleep is required
318 |an optional maximum duration to sleep
336 |an optional period of how long we should wait between checks; lower values increase load on the server but may make tests pass faster, larger values are more efficient but increase test latency.
342 |Generated using TypeDoc
399 |
One day in milliseconds
99 |