that testing our code is an important and important a part of the software program improvement life cycle. That is maybe much more essential after we’re discussing AI and ML programs, the place an inherent uncertainty and hallucinatory aspect are probably already baked in from the outset.
And inside that basic testing framework, testing code that behaves in a different way based mostly on the present date or time is usually a actual headache. How do you reliably verify logic that triggers solely at midnight, calculates relative dates (“2 hours in the past”), or handles tough conditions like leap years or month-ends? Manually mocking Python’s datetime module may be cumbersome and error-prone.
When you’ve ever wrestled with this, you’re not alone. However what when you may merely … cease time? And even journey via it inside your exams?
That’s exactly what the Freezegun library enables you to do. It’s a chic answer to a typical testing drawback, but many skilled Python builders have by no means heard of it.
Freezegun permits your Python exams to simulate particular moments in time by mocking the datetime, date, time, and pendulum Python modules. It’s easy to make use of however highly effective for creating deterministic and dependable exams for time-sensitive code.
Why is Freezegun so useful?
- Determinism. That is Freezegun’s main profit. Assessments involving time develop into fully predictable. Operating datetime.now() inside a frozen block returns the identical frozen timestamp, eliminating flaky exams brought on by millisecond variations or date rollovers throughout take a look at execution.
- Simplicity. In comparison with manually patching datetime.now or utilizing unittest.mock, Freezegun is commonly a lot cleaner and requires much less boilerplate code, particularly when briefly altering the time.
- Time Journey. Simply simulate particular dates and instances — previous, current, or future. That is essential for testing edge circumstances, corresponding to year-end processing, leap seconds, daylight saving time transitions, or just verifying logic tied to particular occasions.
- Relative Time Testing. Take a look at capabilities that calculate relative instances (e.g., “expires in 3 days”) by freezing time and creating timestamps relative to that frozen second.
- Tick Tock. Freezegun permits time to advance (“tick”) from the frozen second inside a take a look at, which is ideal for testing timeouts, durations, or sequences of time-dependent occasions.
Hopefully, I’ve satisfied you that Freezegun might be a beneficial addition to your Python toolbox. Let’s see it in motion by trying via some pattern code snippets.
Organising a dev surroundings
However earlier than that, let’s arrange a improvement surroundings to experiment with. I exploit Miniconda for this, however you should utilize any software with which you’re acquainted.
I’m a Home windows person, however I typically develop utilizing WSL2 Ubuntu for Home windows, which is what I’ll be doing right here.
All of the code I present ought to work equally properly beneath Home windows or Unix-like working programs.
# Create and activate a brand new dev surroundings
#
(base) $ conda create -n freezegun python=3.12 -y
(base) $ conda activate freezegunNow, we will set up the remaining obligatory libraries.
(freezegun) $ pip set up freezegun jupyterI’ll be utilizing Jupyter Pocket book to run my code. To observe alongside, sort jupyter pocket book into your command immediate. You must see a jupyter pocket book open in your browser. If that doesn’t occur robotically, you’ll possible see a screenful of data after the jupyter pocket book command. Close to the underside, one can find a URL to repeat and paste into your browser to launch the Jupyter Pocket book.
Your URL shall be totally different to mine, nevertheless it ought to look one thing like this:-
http://127.0.0.1:8888/tree?token=3b9f7bd07b6966b41b68e2350721b2d0b6f388d248cc69daA fast apart: The code I’m displaying in my examples under makes heavy use of the Python assert command. When you haven’t come throughout this perform earlier than or haven’t achieved a lot unit testing in Python, assert is used to check if a situation is true, and if it isn’t, it raises an
AssertionError.This helps catch points throughout improvement and is usually used for debugging and validating assumptions within the code.
Instance 1: Fundamental Time Freezing utilizing a Decorator
The commonest means to make use of Freezegun is by way of its decorator, @freeze_time, which lets you “set” a selected time of day to check varied time-related capabilities.
import datetime
from freezegun import freeze_time
def get_greeting():
now = datetime.datetime.now()
print(f" Inside get_greeting(), now = {now}") # Added print
if now.hour < 12:
return "Good morning!"
elif 12 <= now.hour < 18:
return "Good afternoon!"
else:
return "Good night!"
# Take a look at the morning greeting
@freeze_time("2023-10-27 09:00:00")
def test_morning_greeting():
print("Operating test_morning_greeting:")
greeting = get_greeting()
print(f" -> Acquired greeting: '{greeting}'")
assert greeting == "Good morning!"
# Take a look at the night greeting
@freeze_time("2023-10-27 21:30:00")
def test_evening_greeting():
print("nRunning test_evening_greeting:")
greeting = get_greeting()
print(f" -> Acquired greeting: '{greeting}'")
assert greeting == "Good night!"
# Run the exams
test_morning_greeting()
test_evening_greeting()
print("nBasic decorator exams handed!")
# --- Failure Situation ---
# What occurs if we do not freeze time?
print("n--- Operating with out freeze_time (would possibly fail relying on precise time) ---")
def test_morning_greeting_unfrozen():
print("Operating test_morning_greeting_unfrozen:")
greeting = get_greeting()
print(f" -> Acquired greeting: '{greeting}'")
# This assertion is now unreliable! It depends upon if you run the code.
strive:
assert greeting == "Good morning!"
print(" (Handed by likelihood)")
besides AssertionError:
print(" (Failed as anticipated - time wasn't 9 AM)")
test_morning_greeting_unfrozen()And the output.
Operating test_morning_greeting:
Inside get_greeting(), now = 2023-10-27 09:00:00
-> Acquired greeting: 'Good morning!'
Operating test_evening_greeting:
Inside get_greeting(), now = 2023-10-27 21:30:00
-> Acquired greeting: 'Good night!'
Fundamental decorator exams handed!
--- Operating with out freeze_time (would possibly fail relying on precise time) ---
Operating test_morning_greeting_unfrozen:
Inside get_greeting(), now = 2025-04-16 15:00:37.363367
-> Acquired greeting: 'Good afternoon!'
(Failed as anticipated - time wasn't 9 AM)Instance 2: Fundamental Time Freezing utilizing a Context Supervisor
Create a “block” of frozen time.
import datetime
from freezegun import freeze_time
def process_batch_job():
start_time = datetime.datetime.now()
# Simulate work
end_time = datetime.datetime.now() # In actuality, time would cross
print(f" Inside job: Begin={start_time}, Finish={end_time}") # Added print
return (start_time, end_time)
def test_job_timestamps_within_frozen_block():
print("nRunning test_job_timestamps_within_frozen_block:")
frozen_time_str = "2023-11-15 10:00:00"
with freeze_time(frozen_time_str):
print(f" Getting into frozen block at {frozen_time_str}")
begin, finish = process_batch_job()
print(f" Asserting begin == finish: {begin} == {finish}")
assert begin == finish
print(f" Asserting begin == frozen time: {begin} == {datetime.datetime(2023, 11, 15, 10, 0, 0)}")
assert begin == datetime.datetime(2023, 11, 15, 10, 0, 0)
print(" Assertions inside block handed.")
print(" Exited frozen block.")
now_outside = datetime.datetime.now()
print(f" Time exterior block: {now_outside} (needs to be actual time)")
# This assertion simply exhibits time is unfrozen, worth depends upon actual time
assert now_outside != datetime.datetime(2023, 11, 15, 10, 0, 0)
test_job_timestamps_within_frozen_block()
print("nContext supervisor take a look at handed!")The output.
Operating test_job_timestamps_within_frozen_block:
Getting into frozen block at 2023-11-15 10:00:00
Inside job: Begin=2023-11-15 10:00:00, Finish=2023-11-15 10:00:00
Asserting begin == finish: 2023-11-15 10:00:00 == 2023-11-15 10:00:00
Asserting begin == frozen time: 2023-11-15 10:00:00 == 2023-11-15 10:00:00
Assertions inside block handed.
Exited frozen block.
Time exterior block: 2025-04-16 15:10:15.231632 (needs to be actual time)
Context supervisor take a look at handed!Instance 3: Advancing Time with tick
Simulate time passing inside a frozen interval.
import datetime
import time
from freezegun import freeze_time
def check_if_event_expired(event_timestamp, expiry_duration_seconds):
now = datetime.datetime.now()
expired = now > event_timestamp + datetime.timedelta(seconds=expiry_duration_seconds)
print(f" Checking expiry: Now={now}, Occasion={event_timestamp}, ExpiresAt={event_timestamp + datetime.timedelta(seconds=expiry_duration_seconds)} -> Expired={expired}")
return expired
# --- Guide ticking utilizing context supervisor ---
def test_event_expiry_manual_tick():
print("nRunning test_event_expiry_manual_tick:")
with freeze_time("2023-10-27 12:00:00") as freezer:
event_time_in_freeze = datetime.datetime.now()
expiry_duration = 60
print(f" Occasion created at: {event_time_in_freeze}")
print(" Checking instantly after creation:")
assert not check_if_event_expired(event_time_in_freeze, expiry_duration)
# Advance time by 61 seconds
delta_to_tick = datetime.timedelta(seconds=61)
print(f" Ticking ahead by {delta_to_tick}...")
freezer.tick(delta=delta_to_tick)
print(f" Time after ticking: {datetime.datetime.now()}")
print(" Checking after ticking:")
assert check_if_event_expired(event_time_in_freeze, expiry_duration)
print(" Guide tick take a look at completed.")
# --- Failure Situation ---
@freeze_time("2023-10-27 12:00:00") # No tick=True or guide tick
def test_event_expiry_fail_without_tick():
print("n--- Operating test_event_expiry_fail_without_tick (EXPECT ASSERTION ERROR) ---")
event_time = datetime.datetime.now()
expiry_duration = 60
print(f" Occasion created at: {event_time}")
# Simulate work or ready - with out tick, time would not advance!
time.sleep(0.1)
print(f" Time after simulated wait: {datetime.datetime.now()}")
print(" Checking expiry (incorrectly, time did not transfer):")
strive:
# This could ideally be True, however shall be False with out ticking
assert check_if_event_expired(event_time, expiry_duration)
besides AssertionError:
print(" AssertionError: Occasion didn't expire, as anticipated with out tick.")
print(" Failure situation completed.")
# Run each exams
test_event_expiry_manual_tick()
test_event_expiry_fail_without_tick()This outputs the next.
Operating test_event_expiry_manual_tick:
Occasion created at: 2023-10-27 12:00:00
Checking instantly after creation:
Checking expiry: Now=2023-10-27 12:00:00, Occasion=2023-10-27 12:00:00, ExpiresAt=2023-10-27 12:01:00 -> Expired=False
Ticking ahead by 0:01:01...
Time after ticking: 2023-10-27 12:01:01
Checking after ticking:
Checking expiry: Now=2023-10-27 12:01:01, Occasion=2023-10-27 12:00:00, ExpiresAt=2023-10-27 12:01:00 -> Expired=True
Guide tick take a look at completed.
--- Operating test_event_expiry_fail_without_tick (EXPECT ASSERTION ERROR) ---
Occasion created at: 2023-10-27 12:00:00
Time after simulated wait: 2023-10-27 12:00:00
Checking expiry (incorrectly, time did not transfer):
Checking expiry: Now=2023-10-27 12:00:00, Occasion=2023-10-27 12:00:00, ExpiresAt=2023-10-27 12:01:00 -> Expired=False
AssertionError: Occasion didn't expire, as anticipated with out tick.
Failure situation completed.Instance 4: Testing Relative Dates
Freezegun ensures steady “time in the past” logic.
import datetime
from freezegun import freeze_time
def format_relative_time(timestamp):
now = datetime.datetime.now()
delta = now - timestamp
rel_time_str = ""
if delta.days > 0:
rel_time_str = f"{delta.days} days in the past"
elif delta.seconds >= 3600:
hours = delta.seconds // 3600
rel_time_str = f"{hours} hours in the past"
elif delta.seconds >= 60:
minutes = delta.seconds // 60
rel_time_str = f"{minutes} minutes in the past"
else:
rel_time_str = "simply now"
print(f" Formatting relative time: Now={now}, Timestamp={timestamp} -> '{rel_time_str}'")
return rel_time_str
@freeze_time("2023-10-27 15:00:00")
def test_relative_time_formatting():
print("nRunning test_relative_time_formatting:")
# Occasion occurred 2 days and three hours in the past relative to frozen time
past_event = datetime.datetime(2023, 10, 25, 12, 0, 0)
assert format_relative_time(past_event) == "2 days in the past"
# Occasion occurred 45 minutes in the past
recent_event = datetime.datetime.now() - datetime.timedelta(minutes=45)
assert format_relative_time(recent_event) == "45 minutes in the past"
# Occasion occurred simply now
current_event = datetime.datetime.now() - datetime.timedelta(seconds=10)
assert format_relative_time(current_event) == "simply now"
print(" Relative time exams handed!")
test_relative_time_formatting()
# --- Failure Situation ---
print("n--- Operating relative time with out freeze_time (EXPECT FAILURE) ---")
def test_relative_time_unfrozen():
# Use the identical previous occasion timestamp
past_event = datetime.datetime(2023, 10, 25, 12, 0, 0)
print(f" Testing with past_event = {past_event}")
# This may evaluate in opposition to the *precise* present time, not Oct twenty seventh, 2023
formatted_time = format_relative_time(past_event)
strive:
assert formatted_time == "2 days in the past"
besides AssertionError:
# The precise distinction shall be a lot bigger!
print(f" AssertionError: Anticipated '2 days in the past', however obtained '{formatted_time}'. Failed as anticipated.")
test_relative_time_unfrozen()The output.
Operating test_relative_time_formatting:
Formatting relative time: Now=2023-10-27 15:00:00, Timestamp=2023-10-25 12:00:00 -> '2 days in the past'
Formatting relative time: Now=2023-10-27 15:00:00, Timestamp=2023-10-27 14:15:00 -> '45 minutes in the past'
Formatting relative time: Now=2023-10-27 15:00:00, Timestamp=2023-10-27 14:59:50 -> 'simply now'
Relative time exams handed!
--- Operating relative time with out freeze_time (EXPECT FAILURE) ---
Testing with past_event = 2023-10-25 12:00:00
Formatting relative time: Now=2023-10-27 12:00:00, Timestamp=2023-10-25 12:00:00 -> '2 days in the past'Instance 5: Dealing with Particular Dates (Finish of Month)
Take a look at edge circumstances, corresponding to leap years, reliably.
import datetime
from freezegun import freeze_time
def is_last_day_of_month(check_date):
next_day = check_date + datetime.timedelta(days=1)
is_last = next_day.month != check_date.month
print(f" Checking if {check_date} is final day of month: Subsequent day={next_day}, IsLast={is_last}")
return is_last
print("nRunning particular date logic exams:")
@freeze_time("2023-02-28") # Non-leap 12 months
def test_end_of_february_non_leap():
at this time = datetime.date.at this time()
assert is_last_day_of_month(at this time) is True
@freeze_time("2024-02-28") # Bissextile year
def test_end_of_february_leap_not_yet():
at this time = datetime.date.at this time()
assert is_last_day_of_month(at this time) is False # Feb twenty ninth exists
@freeze_time("2024-02-29") # Bissextile year - final day
def test_end_of_february_leap_actual():
at this time = datetime.date.at this time()
assert is_last_day_of_month(at this time) is True
@freeze_time("2023-12-31")
def test_end_of_year():
at this time = datetime.date.at this time()
assert is_last_day_of_month(at this time) is True
test_end_of_february_non_leap()
test_end_of_february_leap_not_yet()
test_end_of_february_leap_actual()
test_end_of_year()
print("Particular date logic exams handed!")
#
# Output
#
Operating particular date logic exams:
Checking if 2023-02-28 is final day of month: Subsequent day=2023-03-01, IsLast=True
Checking if 2024-02-28 is final day of month: Subsequent day=2024-02-29, IsLast=False
Checking if 2024-02-29 is final day of month: Subsequent day=2024-03-01, IsLast=True
Checking if 2023-12-31 is final day of month: Subsequent day=2024-01-01, IsLast=True
pecific date logic exams handed!Instance 6: Time Zones
Take a look at timezone-aware code appropriately, dealing with offsets and transitions like BST/GMT.
# Requires Python 3.9+ for zoneinfo or `pip set up pytz` for older variations
import datetime
from freezegun import freeze_time
strive:
from zoneinfo import ZoneInfo # Python 3.9+
besides ImportError:
from pytz import timezone as ZoneInfo # Fallback for older Python/pytz
def get_local_and_utc_time():
# Assume native timezone is Europe/London for this instance
local_tz = ZoneInfo("Europe/London")
now_utc = datetime.datetime.now(datetime.timezone.utc)
now_local = now_utc.astimezone(local_tz)
print(f" Getting instances: UTC={now_utc}, Native={now_local} ({now_local.tzname()})")
return now_local, now_utc
# Freeze time as 9 AM UTC. London is UTC+1 in summer time (BST). Oct 27 is BST.
@freeze_time("2023-10-27 09:00:00", tz_offset=0) # tz_offset=0 means the frozen time string IS UTC
def test_time_in_london_bst():
print("nRunning test_time_in_london_bst:")
local_time, utc_time = get_local_and_utc_time()
assert utc_time.hour == 9
assert local_time.hour == 10 # London is UTC+1 on this date
assert local_time.tzname() == "BST"
# Freeze time as 9 AM UTC. Use December twenty seventh, which is GMT (UTC+0)
@freeze_time("2023-12-27 09:00:00", tz_offset=0)
def test_time_in_london_gmt():
print("nRunning test_time_in_london_gmt:")
local_time, utc_time = get_local_and_utc_time()
assert utc_time.hour == 9
assert local_time.hour == 9 # London is UTC+0 on this date
assert local_time.tzname() == "GMT"
test_time_in_london_bst()
test_time_in_london_gmt()
print("nTimezone exams handed!")
#
# Output
#
Operating test_time_in_london_bst:
Getting instances: UTC=2023-10-27 09:00:00+00:00, Native=2023-10-27 10:00:00+01:00 (BST)
Operating test_time_in_london_gmt:
Getting instances: UTC=2023-12-27 09:00:00+00:00, Native=2023-12-27 09:00:00+00:00 (GMT)
Timezone exams handed!Instance 7: Express Time Journey with the move_to perform
Bounce between particular time factors in a single take a look at for advanced temporal sequences.
import datetime
from freezegun import freeze_time
class ReportGenerator:
def __init__(self):
self.creation_time = datetime.datetime.now()
self.information = {"standing": "pending", "generated_at": None}
print(f" Report created at {self.creation_time}")
def generate(self):
self.information["status"] = "generated"
self.information["generated_at"] = datetime.datetime.now()
print(f" Report generated at {self.information['generated_at']}")
def get_status_update(self):
now = datetime.datetime.now()
if self.information["status"] == "generated":
time_since_generation = now - self.information["generated_at"]
standing = f"Generated {time_since_generation.seconds} seconds in the past."
else:
time_since_creation = now - self.creation_time
standing = f"Pending for {time_since_creation.seconds} seconds."
print(f" Standing replace at {now}: '{standing}'")
return standing
def test_report_lifecycle():
print("nRunning test_report_lifecycle:")
with freeze_time("2023-11-01 10:00:00") as freezer:
report = ReportGenerator()
assert report.information["status"] == "pending"
# Test standing after 5 seconds
target_time = datetime.datetime(2023, 11, 1, 10, 0, 5)
print(f" Shifting time to {target_time}")
freezer.move_to(target_time)
assert report.get_status_update() == "Pending for five seconds."
# Generate the report at 10:01:00
target_time = datetime.datetime(2023, 11, 1, 10, 1, 0)
print(f" Shifting time to {target_time} and producing report")
freezer.move_to(target_time)
report.generate()
assert report.information["status"] == "generated"
assert report.get_status_update() == "Generated 0 seconds in the past."
# Test standing 30 seconds after technology
target_time = datetime.datetime(2023, 11, 1, 10, 1, 30)
print(f" Shifting time to {target_time}")
freezer.move_to(target_time)
assert report.get_status_update() == "Generated 30 seconds in the past."
print(" Complicated lifecycle take a look at handed!")
test_report_lifecycle()
# --- Failure Situation ---
def test_report_lifecycle_fail_forgot_move():
print("n--- Operating lifecycle take a look at (FAIL - forgot move_to) ---")
with freeze_time("2023-11-01 10:00:00") as freezer:
report = ReportGenerator()
assert report.information["status"] == "pending"
# We INTEND to verify standing after 5 seconds, however FORGET to maneuver time
print(f" Checking standing (time remains to be {datetime.datetime.now()})")
# freezer.move_to("2023-11-01 10:00:05") # <-- Forgotten!
strive:
assert report.get_status_update() == "Pending for five seconds."
besides AssertionError as e:
print(f" AssertionError: {e}. Failed as anticipated.")
test_report_lifecycle_fail_forgot_move()Right here’s the output.
Operating test_report_lifecycle:
Report created at 2023-11-01 10:00:00
Shifting time to 2023-11-01 10:00:05
Standing replace at 2023-11-01 10:00:05: 'Pending for five seconds.'
Shifting time to 2023-11-01 10:01:00 and producing report
Report generated at 2023-11-01 10:01:00
Standing replace at 2023-11-01 10:01:00: 'Generated 0 seconds in the past.'
Shifting time to 2023-11-01 10:01:30
Standing replace at 2023-11-01 10:01:30: 'Generated 30 seconds in the past.'
Complicated lifecycle take a look at handed!
--- Operating lifecycle take a look at (FAIL - forgot move_to) ---
Report created at 2023-11-01 10:00:00
Checking standing (time remains to be 2023-11-01 10:00:00)
Standing replace at 2023-11-01 10:00:00: 'Pending for 0 seconds.'
AssertionError: . Failed as anticipated.Abstract
Freezegun is a implausible software for any Python developer who wants to check code involving dates and instances. It transforms probably flaky, hard-to-write exams into easy, strong, and deterministic ones. By permitting you to freeze, tick, and journey via time with ease — and by making it clear when time isn’t managed — it unlocks the flexibility to successfully and reliably take a look at beforehand difficult situations.
As an instance this, I offered a number of examples overlaying totally different situations involving date and time testing and confirmed how utilizing Freezegun eliminates lots of the obstacles {that a} conventional testing framework would possibly encounter.
Whereas we’ve lined the core functionalities, you are able to do extra with Freezegun, and I like to recommend testing its GitHub page.
Briefly, Freezegun is a library you must know and use in case your code offers with time and it’s good to take a look at it completely and reliably.
