freezegun
Python library for mocking datetime in tests. freezegun patches Python's datetime module to return a fixed time, making time-dependent tests deterministic. Works as a decorator, context manager, or pytest fixture. Patches datetime.datetime, datetime.date, datetime.time, time.time(), time.localtime(), time.gmtime(), and time.strftime() consistently.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Testing library — no network access or credentials. Only manipulates Python's datetime module.
⚡ Reliability
Best When
You need to freeze or travel through time in Python tests to make time-dependent logic deterministic.
Avoid When
You need fine-grained async time control or testing real sleep durations — use time-machine or mock.patch for specific cases.
Use Cases
- • Test agent scheduling logic that depends on current time with deterministic fixed-time assertions
- • Verify agent expiration, TTL, and time-window logic by freezing time at specific moments
- • Test agent behavior at edge cases (end of month, leap year, DST transition) by controlling time
- • Make agent test suites deterministic by eliminating datetime.now() variability
- • Test agent retry backoff calculations that use time.time() for elapsed time measurement
Not For
- • Async tests requiring time manipulation — time-machine is better for async/trio tests
- • Performance testing — freezegun adds overhead to datetime calls
- • Testing actual clock-based functionality (sleep, actual timeouts) — freezegun doesn't speed up real time.sleep()
Interface
Authentication
Local testing library — no authentication.
Pricing
Completely free and open source.
Agent Metadata
Known Gotchas
- ⚠ freezegun doesn't freeze C extensions that call system time directly — some libraries (e.g., some DB drivers) use C-level time calls not patched by freezegun
- ⚠ Async tests require pytest-freezegun or explicit freezegun patching of asyncio event loop time — standard @freeze_time may not work with async code
- ⚠ time.sleep() still blocks real time when frozen — freezegun doesn't make sleep() instant; use unittest.mock.patch('time.sleep') for that
- ⚠ Timezone-aware datetime objects need timezone specified in freeze_time() — naive datetime freezing can produce unexpected UTC vs local time results
- ⚠ tick=True mode advances time in real-time from the frozen start — useful for testing time advancement but adds test complexity
- ⚠ Some third-party libraries import datetime directly (from datetime import datetime) — freezegun may not patch these; check with ignore_list parameter
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for freezegun.
Scores are editorial opinions as of 2026-03-06.