spulec/freezegun

★ 4,506PythonAudience · developerComplexity · 1/5Setup · easy

Mindmap

mindmap
  root((freezegun))
    What It Does
      Freeze clock in tests
      Control time in code
    Usage Modes
      Decorator on test
      Context manager block
      Manual tick
    Features
      Human-friendly dates
      Timezone support
      Auto-tick seconds
    Use Cases
      Deadline testing
      Retry logic tests
      Timezone behavior

mindmap root((freezegun)) What It Does Freeze clock in tests Control time in code Usage Modes Decorator on test Context manager block Manual tick Features Human-friendly dates Timezone support Auto-tick seconds Use Cases Deadline testing Retry logic tests Timezone behavior

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Freeze the clock to a specific date so code that checks whether a subscription or deadline has expired behaves predictably in tests.

USE CASE 2

Test retry logic by manually advancing the clock to simulate waiting periods without actually sleeping in the test suite.

USE CASE 3

Verify timezone-sensitive behavior by pinning the clock to a specific UTC offset and running your time-aware code.

Tech stack

Python

Getting it running

Difficulty · easy Time to first run · 5min

In plain English

FreezeGun is a Python library that solves a common testing problem: code that checks the current date or time behaves differently depending on when you run it, which makes tests unpredictable. FreezeGun lets you pin the clock to a specific moment for the duration of a test, so the code under test always sees the same date and time no matter when the test actually runs. You use it by adding a decorator above a test function or by wrapping a block of code in a context manager. In both cases, you specify a date and time, and for the duration of that block every standard Python time call returns the frozen value. This includes the usual suspects like getting the current datetime, the current date, the Unix timestamp, and local or UTC time. Once the frozen block exits, the real clock resumes. Beyond simple freezing, the library offers a few variations. You can pass a tick=True argument to start time at the frozen moment but let it move forward normally from there, which is useful when you care about relative time differences rather than absolute values. An auto_tick_seconds argument advances the time by a fixed number of seconds each time you ask for it. Manual ticking lets you advance the clock forward by an explicit amount mid-test, and move_to lets you jump to a completely different date without exiting the frozen context. These variations cover scenarios where you need to test that something happens before or after a deadline, or that a retry waits the right amount of time. FreezeGun accepts a human-friendly date format in addition to the standard ISO format, so writing "Jan 14th, 2012" works the same as "2012-01-14". It also supports timezone offsets when you need to test timezone-sensitive behavior. The library integrates with both pytest-style tests and the older unittest style. Installation is through pip.

Copy-paste prompts

Prompt 1

Using freezegun, write a pytest test that pins the current date to January 15, 2024, and verifies that my is_subscription_expired function returns True for a plan that expired on January 10, 2024.

Prompt 2

Show me how to use freezegun's tick=True mode to test that my retry function waits at least 5 seconds between attempts without the test actually sleeping.

Prompt 3

Using freezegun's move_to, write a test that starts at a given date, checks some behavior, then jumps forward 30 days and asserts that an expiry notification is triggered.

Prompt 4

How do I use freezegun as a context manager to freeze time only inside a specific block inside a unittest.TestCase method?

Prompt 5

Show me how freezegun's auto_tick_seconds argument works, write a test where each call to datetime.now returns a time 10 seconds later than the previous call.

Open on GitHub → Explain another repo

← spulec on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.