How to Simulate Date and Time in Tests: Freezing, Mocking, and Time Travel
How to simulate the date and time in tests: inject a clock, freeze time in JavaScript, Python, Java, and the shell, and pick the dates to test.
Code that depends on the current time is hard to test, because "now" never repeats. A subscription that expires at midnight, a report that runs on the last day of the month, or a scheduler that has to survive a daylight saving change cannot wait for the real calendar to line up. The fix is to simulate the date and time: make "now" a value your test controls. This guide shows the three main approaches, working examples in JavaScript, Python, Java, Go, and the shell, and a list of dates that find real bugs. To get the exact Unix timestamp for any test date, use the Unix timestamp converter.
Three ways to simulate time
- Inject a clock. Pass the current time into your code as a parameter or a dependency instead of reading it from a global. This is the cleanest option because nothing has to be patched.
- Mock the global clock. A test library replaces the system clock for the duration of a test. This works on code you cannot change, at the cost of some hidden global state.
- Fake time below your code. A tool at the operating system or process level changes what every program sees. This is the heaviest option and is mostly useful for integration tests and legacy binaries.
Prefer the first one for new code, and reach for the others when you cannot.
JavaScript and TypeScript
Vitest and Jest can both freeze the system clock:
import { vi, beforeEach, afterEach } from 'vitest';
beforeEach(() => {
vi.useFakeTimers();
vi.setSystemTime(new Date('2026-03-08T06:59:59Z'));
});
afterEach(() => {
vi.useRealTimers();
});
In Jest the calls are jest.useFakeTimers() and jest.setSystemTime(...). Fake timers also replace setTimeout and setInterval, so a test that awaits a real timer will hang until you advance the fake clock with the library's timer-advancing functions.
If you use Luxon, you can also set its notion of "now" directly:
import { Settings } from 'luxon';
Settings.now = () => new Date('2026-03-08T06:59:59Z').valueOf();
Settings.defaultZone = 'America/New_York';
Remember to restore both settings after the test.
Python
Two popular libraries freeze or move the clock. With freezegun:
from freezegun import freeze_time
@freeze_time("2026-03-08 06:59:59")
def test_before_spring_forward():
...
With time-machine, which can also let time keep ticking from a chosen starting point:
import datetime as dt
import time_machine
@time_machine.travel(dt.datetime(2026, 3, 8, 6, 59, 59, tzinfo=dt.timezone.utc))
def test_before_spring_forward():
...
Java
The java.time API was built for injection. Every "now" method accepts a Clock:
Clock fixed = Clock.fixed(Instant.parse("2026-03-08T06:59:59Z"), ZoneOffset.UTC);
LocalDateTime now = LocalDateTime.now(fixed);
Pass the Clock into your service in production as Clock.systemUTC() and in tests as a fixed or offset clock.
Go and other languages
Go has no standard clock mock, so the common pattern is to inject a function: give your struct a now func() time.Time field that defaults to time.Now and override it in tests. The same pattern works in any language and needs no library.
Shell and whole programs
For a program you cannot modify, libfaketime fakes the clock for a single command:
TZ=UTC faketime '2026-03-08 06:59:59' date
Always set the time zone explicitly when you do this, because a bare date string is otherwise ambiguous.
Dates worth testing
Pick dates where time behaves oddly. The epoch values below were computed in UTC, so you can paste them straight into a test.
| Scenario | UTC instant | Unix timestamp |
|---|---|---|
| US spring forward, last second before | 2026-03-08T06:59:59Z | 1772953199 |
| US spring forward, first second after | 2026-03-08T07:00:00Z | 1772953200 |
| US fall back, 01:59:59 EDT | 2026-11-01T05:59:59Z | 1793512799 |
| US fall back, 01:00:00 EST (the repeated hour) | 2026-11-01T06:00:00Z | 1793512800 |
| EU spring forward | 2026-03-29T01:00:00Z | 1774746000 |
| EU fall back | 2026-10-25T01:00:00Z | 1792890000 |
| Leap day | 2028-02-29T12:00:00Z | 1835438400 |
| Year boundary | 2026-12-31T23:59:59Z | 1798761599 |
| 32-bit Unix limit | 2038-01-19T03:14:07Z | 2147483647 |
The US spring-forward row sits at 01:59:59 Eastern, one second before a 02:00 that never exists. Check that your code handles both a skipped local time and a repeated one, and see DST scheduling bugs for the failures this finds. The last row is the moment 32-bit signed time runs out, covered in the Year 2038 problem. For queries that cross midnight, see handling midnight crossings. To shift a timestamp by a number of days or months from one of these dates, use epoch math.
Pitfalls
- Faking time but not the time zone. Run the test with an explicit zone, for example by setting the
TZenvironment variable when you start the test runner, so results do not depend on the machine. - Clocks captured too early. Code that reads the time at import or construction keeps the real value. Create the object after you freeze the clock.
- Mixing real and fake clocks. Timeouts, retries, and network clients may keep using real time and behave strangely against a frozen "now".
- Leaking fake time. Always restore the real clock in a teardown step so one test does not poison the next.
Frequently asked questions
Should I mock the clock or inject it? Inject when you control the code. Mock when you do not.
How do I get the Unix timestamp for a test date? Use the Unix timestamp converter, or compute it in code and assert it against the converter once.
Is it safe to fake time in production? No. Time simulation belongs in tests and staging, not in a live system.
Sources
- vi.setSystemTime, Vitest documentation
- Timer Mocks, Jest documentation
- freezegun, GitHub
- time-machine documentation
- java.time.Clock, Java SE 21 API documentation
- libfaketime, GitHub
- Luxon API documentation: Settings
We build practical, free time and date tools at epochcalc.com — every calculation runs in your browser using IANA tzdb via Luxon, so DST and zone math are correct by construction.