/core/externals/google-toolbox-for-mac/UnitTesting/GTMFoundationUnitTestingUtilities.h

  1//
  2//  GTMFoundationUnitTestingUtilities.h
  3//
  4//  Copyright 2006-2010 Google Inc.
  5//
  6//  Licensed under the Apache License, Version 2.0 (the "License"); you may not
  7//  use this file except in compliance with the License.  You may obtain a copy
  8//  of the License at
  9//
 10//  http://www.apache.org/licenses/LICENSE-2.0
 11//
 12//  Unless required by applicable law or agreed to in writing, software
 13//  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 14//  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
 15//  License for the specific language governing permissions and limitations under
 16//  the License.
 17//
 18
 19#import <Foundation/Foundation.h>
 20#import <objc/objc.h>
 21
 22// Many tests need to spin the runloop and wait for an event to happen. This is
 23// often done by calling:
 24// NSDate* next = [NSDate dateWithTimeIntervalSinceNow:resolution];
 25// [[NSRunLoop currentRunLoop] runMode:NSDefaultRunLoopMode
 26//                          beforeDate:next];
 27// where |resolution| is a guess at how long it will take for the event to
 28// happen. There are two major problems with this approach:
 29// a) By guessing we force the test to take at least |resolution| time.
 30// b) It makes for flaky tests in that sometimes this guess isn't good, and the
 31//    test takes slightly longer than |resolution| time causing the test to post
 32//    a possibly false-negative failure.
 33// To make timing callback tests easier use this class and the
 34// GTMUnitTestingAdditions additions to NSRunLoop and NSApplication.
 35// Your call would look something like this:
 36// id<GTMUnitTestingRunLoopContext> context = [self getMeAContext];
 37// [[NSRunLoop currentRunLoop] gtm_runUpToSixtySecondsWithContext:context];
 38// Then in some callback method within your test you would call
 39// [context setShouldStop:YES];
 40// Internally gtm_runUpToSixtySecondsWithContext will poll the runloop really
 41// quickly to keep test times down to a minimum, but will stop after a good time
 42// interval (in this case 60 seconds) for failures.
 43@protocol GTMUnitTestingRunLoopContext
 44// Return YES if the NSRunLoop (or equivalent) that this context applies to
 45// should stop as soon as possible.
 46- (BOOL)shouldStop;
 47@end
 48
 49// Collection of utilities for unit testing
 50@interface GTMFoundationUnitTestingUtilities : NSObject
 51
 52// Returns YES if we are currently being unittested.
 53+ (BOOL)areWeBeingUnitTested;
 54
 55
 56// Installs a timer to quit the process after the given time, as a catch all for
 57// something not working.  There is a problem that of the testing bundle fails
 58// to load when is is being hosted in a custom app, the app will remain running
 59// until the user quits it.  This provides a way out of that.  When the timer
 60// fires, a message is logged, and the process is directly exited, no clean
 61// shutdown.  This requires a runloop be running.
 62+ (void)installTestingTimeout:(NSTimeInterval)maxRunInterval;
 63
 64@end
 65
 66// An implementation of the GTMUnitTestingRunLoopContext that is a simple
 67// BOOL flag. See GTMUnitTestingRunLoopContext documentation.
 68@interface GTMUnitTestingBooleanRunLoopContext : NSObject <GTMUnitTestingRunLoopContext> {
 69 @private
 70  BOOL shouldStop_;
 71}
 72+ (id)context;
 73- (BOOL)shouldStop;
 74- (void)setShouldStop:(BOOL)stop;
 75- (void)reset;
 76@end
 77
 78// Some category methods to simplify spinning the runloops in such a way as
 79// to make tests less flaky, but have them complete as fast as possible.
 80@interface NSRunLoop (GTMUnitTestingAdditions)
 81// Will spin the runloop in mode until date in mode until the runloop returns
 82// because all sources have been removed or the current date is greater than
 83// |date| or [context shouldStop] returns YES.
 84// Return YES if the runloop was stopped because [context shouldStop] returned
 85// YES.
 86- (BOOL)gtm_runUntilDate:(NSDate *)date
 87                    mode:(NSString *)mode
 88                 context:(id<GTMUnitTestingRunLoopContext>)context;
 89
 90// Calls -gtm_runUntilDate:mode:context: with mode set to NSDefaultRunLoopMode.
 91- (BOOL)gtm_runUntilDate:(NSDate *)date
 92                 context:(id<GTMUnitTestingRunLoopContext>)context;
 93
 94// Calls -gtm_runUntilDate:mode:context: with mode set to NSDefaultRunLoopMode,
 95// and the timeout date set to |seconds| seconds.
 96- (BOOL)gtm_runUpToNSeconds:(NSTimeInterval)seconds
 97                    context:(id<GTMUnitTestingRunLoopContext>)context;
 98
 99// Calls -gtm_runUntilDate:mode:context: with mode set to NSDefaultRunLoopMode,
100// and the timeout date set to 60 seconds.
101// This is a good time to use for AppleEvent calls (which default to 60 seconds)
102// but may be a bit long for standard unit tests, and could cause a long unit
103// testing run if you have multiple failures.
104// Calling -[gtm_runUpToNSeconds:context:] is preferred.
105- (BOOL)gtm_runUpToSixtySecondsWithContext:(id<GTMUnitTestingRunLoopContext>)context;
106
107@end