Helpful Python Libraries You Would possibly Not Have Heard Of:  Freezegun

that testing our code is an important and important a part of the software program growth life cycle. That is maybe much more necessary once 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 common testing framework, testing code that behaves otherwise based mostly on the present date or time is usually a actual headache. How do you reliably examine 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 will be cumbersome and error-prone.

When you’ve ever wrestled with this, you’re not alone. However what should you may merely … cease time? And even journey by way of it inside your exams?

That’s exactly what the Freezegun library enables you to do. It’s a chic resolution to a typical testing downside, 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?

1. Determinism. That is Freezegun’s major profit. Exams involving time grow to be 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.
2. 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.
3. Time Journey. Simply simulate particular dates and instances — previous, current, or future. That is essential for testing edge circumstances, reminiscent of year-end processing, leap seconds, daylight saving time transitions, or just verifying logic tied to particular occasions.
4. Relative Time Testing. Check features that calculate relative instances (e.g., “expires in 3 days”) by freezing time and creating timestamps relative to that frozen second.
5. 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 precious addition to your Python toolbox. Let’s see it in motion by wanting by way of some pattern code snippets.

Establishing a dev atmosphere

However earlier than that, let’s arrange a growth atmosphere to experiment with. I exploit Miniconda for this, however you should use any device with which you’re acquainted.

I’m a Home windows consumer, however I usually 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 nicely beneath Home windows or Unix-like working programs.

# Create and activate a brand new dev atmosphere
#
(base) $ conda create -n freezegun python=3.12 -y
(base) $ conda activate freezegun

Now, we will set up the remaining needed libraries.

(freezegun) $ pip set up freezegun jupyter

I’ll be utilizing Jupyter Pocket book to run my code. To comply with alongside, sort jupyter pocket book into your command immediate. You need to see a jupyter pocket book open in your browser. If that doesn’t occur routinely, you’ll seemingly see a screenful of knowledge after the jupyter pocket book command. Close to the underside, you can find a URL to repeat and paste into your browser to launch the Jupyter Pocket book.

Your URL can be totally different to mine, however it ought to look one thing like this:-

http://127.0.0.1:8888/tree?token=3b9f7bd07b6966b41b68e2350721b2d0b6f388d248cc69da

A fast apart: The code I’m exhibiting in my examples beneath makes heavy use of the Python assert command. When you haven’t come throughout this operate earlier than or haven’t completed 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 growth and is usually used for debugging and validating assumptions within the code.

Instance 1: Fundamental Time Freezing utilizing a Decorator

The most typical means to make use of Freezegun is by way of its decorator, @freeze_time, which lets you “set” a specific time of day to check varied time-related features.

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!"

# Check 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"  -> Obtained greeting: '{greeting}'")
    assert greeting == "Good morning!"

# Check 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"  -> Obtained 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"  -> Obtained greeting: '{greeting}'")
    # This assertion is now unreliable! It will depend on while 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
  -> Obtained greeting: 'Good morning!'

Operating test_evening_greeting:
  Inside get_greeting(), now = 2023-10-27 21:30:00
  -> Obtained 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
  -> Obtained 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 move
    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"  Coming 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} (must be actual time)")
    # This assertion simply exhibits time is unfrozen, worth will depend on 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:
 Coming 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 (must 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 handbook 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 can 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 state of affairs 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 state of affairs completed.

Instance 4: Testing Relative Dates

Freezegun ensures secure “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}")
    # It will examine towards 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 can be a lot bigger!
        print(f"  AssertionError: Anticipated '2 days in the past', however received '{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)

Check edge circumstances, reminiscent of 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 yr
def test_end_of_february_non_leap():
    immediately = datetime.date.immediately()
    assert is_last_day_of_month(immediately) is True

@freeze_time("2024-02-28") # Bissextile year
def test_end_of_february_leap_not_yet():
     immediately = datetime.date.immediately()
     assert is_last_day_of_month(immediately) is False # Feb twenty ninth exists

@freeze_time("2024-02-29") # Bissextile year - final day
def test_end_of_february_leap_actual():
    immediately = datetime.date.immediately()
    assert is_last_day_of_month(immediately) is True

@freeze_time("2023-12-31")
def test_end_of_year():
    immediately = datetime.date.immediately()
    assert is_last_day_of_month(immediately) 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

Check timezone-aware code accurately, 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 season (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: Specific Time Journey with the move_to operate

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.knowledge = {"standing": "pending", "generated_at": None}
        print(f"  Report created at {self.creation_time}")

    def generate(self):
        self.knowledge["status"] = "generated"
        self.knowledge["generated_at"] = datetime.datetime.now()
        print(f"  Report generated at {self.knowledge['generated_at']}")

    def get_status_update(self):
        now = datetime.datetime.now()
        if self.knowledge["status"] == "generated":
            time_since_generation = now - self.knowledge["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.knowledge["status"] == "pending"
        
        # Verify 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.knowledge["status"] == "generated"
        assert report.get_status_update() == "Generated 0 seconds in the past."

        # Verify standing 30 seconds after era
        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.knowledge["status"] == "pending"
        
        # We INTEND to examine standing after 5 seconds, however FORGET to maneuver time
        print(f"  Checking standing (time continues 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 continues 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 incredible device 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 by way of 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 eventualities.

As an example this, I supplied a number of examples overlaying totally different cases 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 trying out its GitHub web page.

Briefly, Freezegun is a library it’s best to know and use in case your code offers with time and it’s essential take a look at it totally and reliably.