Marty: “Wait a minute. Wait a minute. Doc, uh.… Are you telling me that you built a time machine.… out of a DeLorean?”
Doc: “Yes, the way I see it, if you’re gonna build a time machine into a car, why not do it with some style?”
A DeLorean helps you test your time-dependent code allowing you travel anywhere in time.
This simple class provides several class methods to perform diferent time
mannipulations that will modify the behaviour of NSDate
instances
and how time advances during the span the manipulation effects are enabled.
The intention of this class is to be used during testing, so reproducible scenarios can be designed and tested. This class should not be used in production code.
- Include the following line in your
Podfile
:pod 'TUDelorean', :git => 'https://github.com/tuenti/TUDelorean'
- Run
pod install
- Clone, add as a submodule or download TUDelorean.
- Add all the files under
Classes/common
to your project. - Look at the Requirements section if you are not using ARC.
TUDelorean only provides one header that you must import in order to use the
library. Simply add #import "TUDelorean.h"
at the top of your testing files
where you want to use TUDelorean.
One thing that you must remember is that in any test case you decide to use
TUDelorean you must call backToThePresent
in its tearDown
(or equivalent)
method. Otherwise the effects of changing the current time will “leak” to other
tests and also the testing rig.
- (void)tearDown
{
[TUDelorean backToThePresent];
}
TUDelorean offers three primitives to change the current time. Each of them has two variants: in one of them the effects of the time manipulation are permanent, while in the other one the effects of the time manipulation only affects the block passed as parameter. You are encouraged to use the block-based versions, to improve the readability of your tests.
The first primitive is “time travelling”. You provide a destination date, and the current time will be reported from that point as in the past or in the future.
NSDate *destination = [NSDate dateWithNaturalLanguageString:@"November 12, 1955"];
[TUDelorean timeTravelTo:destination block:^(NSDate *date) {
// Inside the block its November 12, 1955
[marty playGuitar:@"Johnny B. Goode"];
}];
The second primitive is a relative “time jump”. You provide an offset from the current time, and from that point the current time will be displaced the number of seconds you wanted.
[timeMachine addOccupant:einstein];
[TUDelorean jump:60 block:^(NSDate *date) {
// Inside the block its already 60 seconds into the future
[einstein woof];
}];
[marty say:@"Jesus Christ, Doc. You disintegrated Einstein!"]
The final primitive is another time jump, but instead of allowing the time to keep flowing as normal, the time is frozen in the same moment. This is particurlaly useful if you need to do time distance calculations, and you want to test the edge cases.
NSDate *destination = [NSDate dateWithNaturalLanguageString:@"18pm September 5, 1885"];
[TUDelorean freeze:destination block:^(NSDate *date) {
// Inside the block is 18pm September 5, 1885.
[NSThread sleepForTimeInterval:3600.0];
// Yes, still 18pm September 5, 1885.
}];
You can reset the changes done to the current time using backToThePresent
at
any moment.
TUDelorean should work in any relatively recent iOS/Mac version, but we have only tested it iOS 6.0 and OS X 10.8. We have only tested TUDelorean with OCUnit, but it should work in any other testing framework unchanged.
TUDelorean uses ARC, so if you use it in a non-ARC project, and you are not
using CocoaPods, you will need to use -fobjc-arc
compiler flag on every
TUDelorean source file.
To set a compiler flag in Xcode, go to your desidered target and select the
“Build Phases” tab. Select all TUDelorean source files, press Enter,
add -fobjc-arc
and then “Done” to enable ARC for TUDelorean.
TUDelorean was created by iOS team at Tuenti Technologies S.L.. You can follow Tuenti engineering team on Twitter @tuentieng.
TUDelorean was inspired by the similarly named Rubygem delorean. Thanks for the inspiration, and for finding this awesome name.
TUDelorean is available under the Apache License, Version 2.0. See LICENSE file for more info.