{"name":"Freezegun: Time Travel for Your Python Tests","description":"Freezegun is a powerful Python library designed to simplify testing by allowing your tests to travel through time. It achieves this by mocking the `datetime` module, enabling developers to freeze time at a specific point or even simulate its progression. This functionality is crucial for ensuring consistent and reliable test results when dealing with time-sensitive logic.","github":"https://github.com/spulec/freezegun","url":"https://osrepos.com/repo/spulec-freezegun","source":"osrepos.com","sourceDescription":"This repository profile is provided by osrepos.com, an open source repository discovery platform.","repositoryProfile":"https://osrepos.com/repo/spulec-freezegun","generatedFor":"open source discovery and AI-assisted research","markdown":"https://osrepos.com/repo/spulec-freezegun.md","json":"https://osrepos.com/repo/spulec-freezegun.json","topics":["Python","Testing","Mocking","Datetime","Time","Development","Library"],"keywords":["Python","Testing","Mocking","Datetime","Time","Development","Library"],"stars":null,"summary":"Freezegun is a powerful Python library designed to simplify testing by allowing your tests to travel through time. It achieves this by mocking the `datetime` module, enabling developers to freeze time at a specific point or even simulate its progression. This functionality is crucial for ensuring consistent and reliable test results when dealing with time-sensitive logic.","content":"## Introduction\n\nFreezegun is an indispensable Python library that empowers developers to manipulate time within their test suites. By effectively mocking the `datetime` module, `time.time()`, and related functions, Freezegun allows you to freeze the current time to a specific date and time, or even simulate the passage of time. This capability is vital for testing applications with time-dependent features, ensuring that your tests are deterministic and free from real-world time variations.\n\n## Installation\n\nInstalling Freezegun is straightforward using pip:\n\nbash\n$ pip install freezegun\n\n\nFor Debian systems, you can also use apt-get:\n\nbash\n$ sudo apt-get install python-freezegun\n\n\n## Examples\n\nFreezegun offers flexible ways to control time, whether through decorators, context managers, or direct API calls.\n\n### Decorator Usage\n\nApply `freeze_time` as a decorator to functions or classes to freeze time for their duration.\n\npython\nfrom freezegun import freeze_time\nimport datetime\nimport unittest\n\n# Freeze time for a pytest style test:\n@freeze_time(\"2012-01-14\")\ndef test_frozen_time_decorator():\n    assert datetime.datetime.now() == datetime.datetime(2012, 1, 14)\n\n# Or a unittest TestCase:\n@freeze_time(\"1955-11-12\")\nclass MyTests(unittest.TestCase):\n    def test_the_class(self):\n        assert datetime.datetime.now() == datetime.datetime(1955, 11, 12)\n\n\n### Context Manager Usage\n\nUse `freeze_time` as a context manager for precise control over time within a specific block of code.\n\npython\nfrom freezegun import freeze_time\nimport datetime\n\ndef test_time_context_manager():\n    assert datetime.datetime.now() != datetime.datetime(2012, 1, 14)\n    with freeze_time(\"2012-01-14\"):\n        assert datetime.datetime.now() == datetime.datetime(2012, 1, 14)\n    assert datetime.datetime.now() != datetime.datetime(2012, 1, 14)\n\n\n### Manual Ticks and Moving Time\n\nBeyond freezing, Freezegun allows you to manually advance time or jump to a specific date.\n\npython\nfrom freezegun import freeze_time\nimport datetime\n\ndef test_manual_tick_and_move():\n    initial_datetime = datetime.datetime(year=1, month=7, day=12,\n                                        hour=15, minute=6, second=3)\n    with freeze_time(initial_datetime) as frozen_datetime:\n        assert frozen_datetime() == initial_datetime\n\n        # Manually advance time by 1 second\n        frozen_datetime.tick()\n        initial_datetime += datetime.timedelta(seconds=1)\n        assert frozen_datetime() == initial_datetime\n\n        # Move to a completely different date\n        other_datetime = datetime.datetime(year=2, month=8, day=13,\n                                            hour=14, minute=5, second=0)\n        frozen_datetime.move_to(other_datetime)\n        assert frozen_datetime() == other_datetime\n\n\n### Ticking Time\n\nThe `tick=True` argument allows time to progress naturally from the frozen point.\n\npython\nfrom freezegun import freeze_time\nimport datetime\nimport time\n\n@freeze_time(\"Jan 14th, 2020\", tick=True)\ndef test_ticking_time():\n    # Time will progress naturally after the initial freeze point\n    initial_time = datetime.datetime.now()\n    time.sleep(0.01) # Simulate some time passing\n    assert datetime.datetime.now() > initial_time\n\n\n### Auto-Ticking Time\n\nThe `auto_tick_seconds` argument automatically increments time by a specified amount on each call.\n\npython\nfrom freezegun import freeze_time\nimport datetime\n\n@freeze_time(\"Jan 14th, 2020\", auto_tick_seconds=15)\ndef test_auto_ticking_time():\n    first_time = datetime.datetime.now()\n    # Subsequent call to datetime.datetime.now() will be 15 seconds later\n    auto_incremented_time = datetime.datetime.now()\n    assert first_time + datetime.timedelta(seconds=15) == auto_incremented_time\n\n\n### Real Asyncio\n\nFor `asyncio` applications, `real_asyncio=True` allows `asyncio` event loops to see real monotonic time while `datetime` remains frozen.\n\npython\nfrom freezegun import freeze_time\nimport datetime\nimport asyncio\n\n@freeze_time(\"2012-01-14\", real_asyncio=True)\nasync def test_asyncio_with_frozen_time():\n    start_time = datetime.datetime.now()\n    await asyncio.sleep(0.1) # This sleep will use real time\n    end_time = datetime.datetime.now()\n    assert start_time == end_time # datetime is still frozen\n\n\n## Why Use Freezegun?\n\nTesting applications that interact with dates and times can be notoriously difficult. Real-world time is constantly changing, making it hard to reproduce specific scenarios or ensure consistent test results. Freezegun solves this by providing a simple, elegant way to control time within your tests. This leads to more reliable, deterministic, and faster test suites, allowing you to focus on your application's logic rather than battling time-related inconsistencies. It's an essential tool for any Python developer working with `datetime` objects in their code.\n\n## Links\n\nExplore the Freezegun project further:\n\n*   [GitHub Repository](https://github.com/spulec/freezegun){:target=\"_blank\"}\n*   [PyPI Page](https://pypi.python.org/pypi/freezegun/){:target=\"_blank\"}","metrics":{"detailViews":0,"githubClicks":0},"dates":{"published":null,"modified":"2026-08-04T00:00:03.000Z"}}