time-machine
Fast time mocking library for Python — freezes or moves datetime.datetime.now(), datetime.date.today(), time.time(), and time.localtime() to controlled values during tests. time-machine features: @time_machine.travel() decorator, time_machine.travel() context manager, dest parameter (datetime, string, Unix timestamp), tick=True for advancing time naturally, tz_offset for timezone, pytest fixture support via travel_to(), and C-extension implementation (10-100x faster than freezegun). Used for testing agent time-dependent logic like scheduling, token expiry, rate limit windows, and cron jobs.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Test-only library — no security concerns. Ensure time-machine is not imported in production agent code (should be in test-only dev dependencies).
⚡ Reliability
Best When
Testing Python agent logic that depends on current time — scheduled tasks, token expiry, cache TTL, rate limit windows — where freezegun's speed is insufficient or you need faster test execution.
Avoid When
You need to mock third-party datetime libraries or need production time control.
Use Cases
- • Agent scheduled task testing — @time_machine.travel('2026-01-15 09:00:00'); def test_monday_report(): agent.run_scheduled_tasks(); assert report_sent() — test agent Monday 9am report without waiting; deterministic scheduled task tests
- • Agent token expiry testing — with time_machine.travel(datetime.now() + timedelta(hours=2)): assert agent.token.is_expired() — advance time to after token expiry; test agent token refresh logic without sleeping 2 hours
- • Agent rate limit window testing — with time_machine.travel('2026-01-01 00:00:01'): agent.make_api_calls(100); with time_machine.travel('2026-01-01 01:00:01'): assert agent.api_quota.reset == True — test agent rate limit window reset at hour boundary
- • Agent audit log timestamp testing — with time_machine.travel('2026-03-15 14:30:00 UTC'): agent.complete_task(task); log = AuditLog.last(); assert log.timestamp == datetime(2026, 3, 15, 14, 30, tzinfo=UTC) — verify agent audit logs exact timestamps
- • Agent cache expiry testing — with time_machine.travel(datetime.now() + timedelta(minutes=61)): assert not agent.cache.has('result') — test agent cache TTL expiry after 60 minutes; time-machine advances clock without Thread.sleep(3600)
Not For
- • Non-datetime mocking — time-machine only mocks time; for general object mocking use unittest.mock or pytest-mock
- • Production time control — time-machine is test-only; never use in production agent code
- • Third-party datetime libraries — time-machine mocks stdlib datetime; Arrow, Pendulum, dateutil may not be fully intercepted depending on version
Interface
Authentication
No auth — local test library.
Pricing
time-machine is MIT licensed, maintained by Adam Johnson. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ time-machine doesn't mock Arrow or Pendulum by default — time_machine.travel freezes datetime.datetime.now() and time.time(); Arrow.now() reads system time differently and may not be frozen; agent code using Arrow for time must use datetime.datetime.now() internally for time-machine to intercept, or patch Arrow explicitly
- ⚠ tick=True advances time from destination — time_machine.travel('2026-01-01', tick=True) starts clock at 2026-01-01 and advances; tick=False (default) freezes at exactly that moment; agent tests checking elapsed time need tick=True; tests checking absolute time need tick=False
- ⚠ Thread safety for async tests — time-machine uses C-level time interception which is global; async agent tests with concurrent coroutines all see the same frozen time; works correctly for asyncio tests; for agent tests needing different times in concurrent coroutines use separate test cases
- ⚠ Timezone-naive vs timezone-aware destination — time_machine.travel('2026-01-01') freezes as UTC naive; datetime.now(tz=timezone.utc) in agent code returns wrong type if expecting aware datetime; use time_machine.travel(datetime(2026, 1, 1, tzinfo=timezone.utc)) for timezone-aware freezing in agent tests
- ⚠ Windows not supported without wheel — time-machine requires C extension; Windows builds need pre-built wheel; agent CI on Windows installs time-machine but may get ImportError if wheel not available for Python version; use freezegun for cross-platform compatibility if targeting Windows CI
- ⚠ time.sleep() not intercepted — time_machine.travel doesn't make time.sleep() return instantly; agent code with time.sleep(3600) in test still blocks 1 hour; mock time.sleep separately with unittest.mock.patch('time.sleep') alongside time-machine for complete time control in agent tests
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for time-machine.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-06.