Mocking dates and times

Testing code that involves dates and times or which has behaviour dependent on the date or time it is executed at has historically been tricky. Mocking lets you perform tests on this type of code and TestFixtures provides three specialised mock objects to help with this.

Dates

TestFixtures provides the test_date() function that returns a subclass of datetime.date with a today() method that will return a consistent sequence of dates each time it is called.

This enables you to write tests for code such as the following, from the testfixtures.tests.sample1 package:

from datetime import datetime, date


def str_today_1():
    return str(date.today())

Replace can be used to apply the mock as shown in the following example, which could appear in either a unit test or a doc test:

>>> from testfixtures import Replace, test_date
>>> from testfixtures.tests.sample1 import str_today_1
>>> with Replace('testfixtures.tests.sample1.date', test_date()):
...    str_today_1()
...    str_today_1()
'2001-01-01'
'2001-01-02'

If you need a specific date to be returned, you can specify it:

>>> with Replace('testfixtures.tests.sample1.date', test_date(1978,6,13)):
...    str_today_1()
'1978-06-13'

If you need to test with a whole sequence of specific dates, this can be done as follows:

>>> with Replace('testfixtures.tests.sample1.date', test_date(None)) as d:
...    d.add(1978,6,13)
...    d.add(2009,11,12)
...    str_today_1()
...    str_today_1()
'1978-06-13'
'2009-11-12'

Another way to test with a specific sequence of dates is to use the delta_type and delta parameters to test_date(). These parameters control the type and size, respectively, of the difference between each date returned.

For example, where 2 days elapse between each returned value:

>>> with Replace('testfixtures.tests.sample1.date',
...              test_date(1978, 6, 13, delta=2, delta_type='days')) as d:
...    str_today_1()
...    str_today_1()
...    str_today_1()
'1978-06-13'
'1978-06-15'
'1978-06-17'

The delta_type can be any keyword parameter accepted by the timedelta constructor. Specifying a delta of zero can be an effective way of ensuring that all calls to the today() method return the same value:

>>> with Replace('testfixtures.tests.sample1.date',
...              test_date(1978, 6, 13, delta=0)) as d:
...    str_today_1()
...    str_today_1()
...    str_today_1()
'1978-06-13'
'1978-06-13'
'1978-06-13'

When using test_date(), you can, at any time, set the next date to be returned using the set() method. The date returned after this will be the set date plus the delta in effect:

>>> with Replace('testfixtures.tests.sample1.date', test_date(delta=2)) as d:
...    str_today_1()
...    d.set(1978,8,1)
...    str_today_1()
...    str_today_1()
'2001-01-01'
'1978-08-01'
'1978-08-03'

Datetimes

TextFixtures provides the test_datetime() function that returns a subclass of datetime.datetime with a now() method that will return a consistent sequence of datetime objects each time it is called.

This enables you to write tests for code such as the following, from the testfixtures.tests.sample1 package:

from datetime import datetime, date


def str_now_1():
    return str(datetime.now())

We use the a Replacer as follows, which could appear in either a unit test or a doc test:

>>> from testfixtures import Replacer, test_datetime
>>> from testfixtures.tests.sample1 import str_now_1
>>> with Replace('testfixtures.tests.sample1.datetime', test_datetime()):
...    str_now_1()
...    str_now_1()
'2001-01-01 00:00:00'
'2001-01-01 00:00:10'

If you need a specific datetime to be returned, you can specify it:

>>> with Replace('testfixtures.tests.sample1.datetime',
...              test_datetime(1978,6,13,1,2,3)):
...    str_now_1()
'1978-06-13 01:02:03'

If you need to test with a whole sequence of specific datetimes, this can be done as follows:

>>> with Replace('testfixtures.tests.sample1.datetime',
...              test_datetime(None)) as d:
...    d.add(1978,6,13,16,0,1)
...    d.add(2009,11,12,11,41,20)
...    str_now_1()
...    str_now_1()
'1978-06-13 16:00:01'
'2009-11-12 11:41:20'

Another way to test with a specific sequence of datetimes is to use the delta_type and delta parameters to test_datetime(). These parameters control the type and size, respectively, of the difference between each datetime returned.

For example, where 2 hours elapse between each returned value:

>>> with Replace(
...    'testfixtures.tests.sample1.datetime',
...    test_datetime(1978, 6, 13, 16, 0, 1, delta=2, delta_type='hours')
... ) as d:
...    str_now_1()
...    str_now_1()
...    str_now_1()
'1978-06-13 16:00:01'
'1978-06-13 18:00:01'
'1978-06-13 20:00:01'

The delta_type can be any keyword parameter accepted by the timedelta constructor. Specifying a delta of zero can be an effective way of ensuring that all calls to the now() method return the same value:

>>> with Replace('testfixtures.tests.sample1.datetime',
...              test_datetime(1978, 6, 13, 16, 0, 1, delta=0)) as d:
...    str_now_1()
...    str_now_1()
...    str_now_1()
'1978-06-13 16:00:01'
'1978-06-13 16:00:01'
'1978-06-13 16:00:01'

When using test_datetime(), you can, at any time, set the next datetime to be returned using the set() method. The value returned after this will be the set value plus the delta in effect:

>>> with Replace('testfixtures.tests.sample1.datetime',
...              test_datetime(delta=2)) as d:
...    str_now_1()
...    d.set(1978,8,1)
...    str_now_1()
...    str_now_1()
'2001-01-01 00:00:00'
'1978-08-01 00:00:00'
'1978-08-01 00:00:02'

Timezones

In many situations where you’re mocking out now() or utcnow() you’re not concerned about timezones, especially given that both methods will usually return datetime objects that have a tzinfo of None. However, in some applications it is important that now() and utcnow() return different times, as they would normally if the application is run anywhere other than the UTC timezone.

The best way to understand how to use test_datetime() in these situations is to think of the internal queue as being a queue of datetime objects at the current local time with a tzinfo of None, much as would be returned by now(). If you pass in a tz parameter to now() it will be applied to the value before it is returned in the same way as it would by datetime.datetime.now().

If you pass in a tzinfo to test_datetime(), this will be taken to indicate the timezone you intend for the local times that now() simulates. As such, that timezone will be used to compute values returned from utcnow() such that they would be test_datetime objects in the UTC timezone with the tzinfo set to None, as would be the case for a normal call to datetime.datetime.utcnow().

For example, lets take a timezone as defined by the following class:

from datetime import tzinfo, timedelta

class ATZInfo(tzinfo):

   def tzname(self, dt):
        return 'A TimeZone'

   def utcoffset(self, dt):
        # In general, this timezone is 5 hours behind UTC
        offset  = timedelta(hours=-5)
        return offset+self.dst(dt)

   def dst(self, dt):
        # However, between March and September, it is only
        # 4 hours behind UTC
        if 3 < dt.month < 9:
            return timedelta(hours=1)
        return timedelta()

If we create a test_datetime with this timezone and a delta of zero, so we can see affect of the timezone over multiple calls, the values returned by now() will be affected:

>>> datetime = test_datetime(2001, 1, 1, delta=0, tzinfo=ATZInfo())

A normal call to now() will return the values passed to the constructor:

>>> print(datetime.now())
2001-01-01 00:00:00

If we now ask for this time but in the timezone we passed to test_datetime, we will get the same hours, minutes and seconds but with a tzinfo attribute set:

>>> print(datetime.now(ATZInfo()))
2001-01-01 00:00:00-05:00

If we call utcnow(), we will get the time equivalent to the values passed to the constructor, but in the UTC timezone:

>>> print(datetime.utcnow())
2001-01-01 05:00:00

The timezone passed in when the test_datetime is created has a similar effect on any items set:

>>> datetime.set(2011,5,1,10)
>>> print(datetime.now())
2011-05-01 10:00:00
>>> print(datetime.utcnow())
2011-05-01 14:00:00

Likewise, add() behaves the same way:

>>> datetime = test_datetime(None, delta=0, tzinfo=ATZInfo())
>>> datetime.add(2011,1,1,10)
>>> datetime.add(2011,5,1,10)
>>> datetime.add(2011,10,1,10)
>>> print(datetime.now())
2011-01-01 10:00:00
>>> print(datetime.utcnow())
2011-05-01 14:00:00
>>> print(datetime.now())
2011-10-01 10:00:00

Times

TextFixtures provides the test_time() function that, when called, returns a replacement for the time.time() function.

This enables you to write tests for code such as the following, from the testfixtures.tests.sample1 package:

from time import time


def str_time():
    return str(time())

We use the a Replacer as follows, which could appear in either a unit test or a doc test:

>>> from testfixtures import Replacer, test_time
>>> from testfixtures.tests.sample1 import str_time
>>> with Replace('testfixtures.tests.sample1.time', test_time()):
...    str_time()
...    str_time()
'978307200.0'
'978307201.0'

If you need an integer representing a specific time to be returned, you can specify it:

>>> with Replace('testfixtures.tests.sample1.time',
...              test_time(1978, 6, 13, 1, 2, 3)):
...    str_time()
'266547723.0'

If you need to test with a whole sequence of specific timestamps, this can be done as follows:

>>> with Replace('testfixtures.tests.sample1.time', test_time(None)) as t:
...    t.add(1978,6,13,16,0,1)
...    t.add(2009,11,12,11,41,20)
...    str_time()
...    str_time()
'266601601.0'
'1258026080.0'

Another way to test with a specific sequence of timestamps is to use the delta_type and delta parameters to test_time(). These parameters control the type and size, respectively, of the difference between each timestamp returned.

For example, where 2 hours elapse between each returned value:

>>> with Replace(
...     'testfixtures.tests.sample1.time',
...     test_time(1978, 6, 13, 16, 0, 1, delta=2, delta_type='hours')
... ) as d:
...    str_time()
...    str_time()
...    str_time()
'266601601.0'
'266608801.0'
'266616001.0'

The delta_type can be any keyword parameter accepted by the timedelta constructor. Specifying a delta of zero can be an effective way of ensuring that all calls to the time() function return the same value:

>>> with Replace('testfixtures.tests.sample1.time',
...              test_time(1978, 6, 13, 16, 0, 1, delta=0)) as d:
...    str_time()
...    str_time()
...    str_time()
'266601601.0'
'266601601.0'
'266601601.0'

When using test_time(), you can, at any time, set the next timestamp to be returned using the set() method. The value returned after this will be the set value plus the delta in effect:

>>> with Replace('testfixtures.tests.sample1.time', test_time(delta=2)) as d:
...    str_time()
...    d.set(1978,8,1)
...    str_time()
...    str_time()
'978307200.0'
'270777600.0'
'270777602.0'

Gotchas with dates and times

Using these specialised mock objects can have some intricacies as described below:

Local references to functions

There are situations where people may have obtained a local reference to the today() or now() methods, such as the following code from the testfixtures.tests.sample1 package:

from datetime import datetime, date


now = datetime.now


def str_now_2():
    return str(now())
today = date.today


def str_today_2():
    return str(today())

In these cases, you need to be careful with the replacement:

>>> from testfixtures import Replacer, test_datetime
>>> from testfixtures.tests.sample1 import str_now_2, str_today_2
>>> with Replacer() as replace:
...    today = replace('testfixtures.tests.sample1.today', test_date().today)
...    now = replace('testfixtures.tests.sample1.now', test_datetime().now)
...    str_today_2()
...    str_now_2()
'2001-01-01'
'2001-01-01 00:00:00'

Use with code that checks class types

When using the above specialist mocks, you may find code that checks the type of parameters passed may get confused. This is because, by default, test_datetime and test_date return instances of the real datetime and date classes:

>>> from testfixtures import test_datetime
>>> from datetime import datetime
>>> tdatetime = test_datetime()
>>> issubclass(tdatetime, datetime)
True
>>> tdatetime.now().__class__
<...'datetime.datetime'>

The above behaviour, however, is generally what you want as other code in your application and, more importantly, in other code such as database adapters, may handle instances of the real datetime and date classes, but not instances of the test_datetime and test_date mocks.

That said, this behaviour can cause problems if you check the type of an instance against one of the mock classes. Most people might expect the following to return True:

>>> isinstance(tdatetime(2011, 1, 1), tdatetime)
False
>>> isinstance(tdatetime.now(), tdatetime)
False

If this causes a problem for you, then both datetime and date take a strict keyword parameter that can be used as follows:

>>> tdatetime = test_datetime(strict=True)
>>> tdatetime.now().__class__
<class 'testfixtures.tdatetime.tdatetime'>
>>> isinstance(tdatetime.now(), tdatetime)
True

You will need to take care that you have replaced occurrences of the class where type checking is done with the correct test_datetime or test_date. Also, be aware that the date() method of test_datetime instances will still return a normal date instance. If type checking related to this is causing problems, the type the date() method returns can be controlled as shown in the following example:

from testfixtures import test_date, test_datetime

date_type = test_date(strict=True)
datetime_type = test_datetime(strict=True, date_type=date_type)

With things set up like this, the date() method will return an instance of the date_type mock:

>>> somewhen = datetime_type.now()
>>> somewhen.date()
tdate(2001, 1, 1)
>>> _.__class__ is date_type
True