/GHUnitIOS.framework/Versions/A/Headers/GHAsyncTestCase.h

  1//
  2//  GHAsyncTestCase.h
  3//  GHUnit
  4//
  5//  Created by Gabriel Handford on 4/8/09.
  6//  Copyright 2009. All rights reserved.
  7//
  8//  Permission is hereby granted, free of charge, to any person
  9//  obtaining a copy of this software and associated documentation
 10//  files (the "Software"), to deal in the Software without
 11//  restriction, including without limitation the rights to use,
 12//  copy, modify, merge, publish, distribute, sublicense, and/or sell
 13//  copies of the Software, and to permit persons to whom the
 14//  Software is furnished to do so, subject to the following
 15//  conditions:
 16//
 17//  The above copyright notice and this permission notice shall be
 18//  included in all copies or substantial portions of the Software.
 19//
 20//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 21//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 22//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 23//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 24//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 25//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 26//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 27//  OTHER DEALINGS IN THE SOFTWARE.
 28//
 29
 30#import "GHTestCase.h"
 31
 32// Some default statuses to use; Or define and use your own
 33enum {
 34  kGHUnitWaitStatusUnknown = 0, //!< Unknown wait status
 35  kGHUnitWaitStatusSuccess, //!< Wait status success
 36  kGHUnitWaitStatusFailure, //!< Wait status failure
 37  kGHUnitWaitStatusCancelled //!< Wait status cancelled
 38};
 39
 40/*!
 41 Asynchronous test case with wait and notify.
 42 
 43 If notify occurs before wait has started (if it was a synchronous call), this test
 44 case will still work.
 45
 46 Be sure to call prepare before the asynchronous method (otherwise an exception will raise).
 47 
 48 @code
 49 
 50 @interface MyAsyncTest : GHAsyncTestCase { }
 51 @end
 52 
 53 @implementation MyAsyncTest
 54 
 55 - (void)testSuccess {
 56   [self prepare];
 57   
 58   // Do asynchronous task here
 59   [self performSelector:@selector(_succeed) withObject:nil afterDelay:0.1];
 60   
 61   [self waitForStatus:kGHUnitWaitStatusSuccess timeout:1.0];
 62 }
 63 
 64 - (void)_succeed {
 65   // Notice the forSelector points to the test above. This is so that
 66   // stray notifies don't error or falsely succeed other tests.
 67   // To ignore the check, forSelector can be NULL.
 68   [self notify:kGHUnitWaitStatusSuccess forSelector:@selector(testSuccess)];
 69 }
 70 
 71 @end
 72 @endcode
 73 */
 74@interface GHAsyncTestCase : GHTestCase {
 75
 76  NSInteger waitForStatus_;
 77  NSInteger notifiedStatus_;
 78  
 79  BOOL prepared_; // Whether prepared was called before waitForStatus:timeout:
 80  NSRecursiveLock *lock_; // Lock to synchronize on
 81  SEL waitSelector_; // The selector we are waiting on
 82    
 83  NSArray *_runLoopModes;
 84}
 85
 86/*!
 87 Run loop modes to run while waiting; 
 88 Defaults to NSDefaultRunLoopMode, NSRunLoopCommonModes, NSConnectionReplyMode
 89 */
 90@property (retain, nonatomic) NSArray *runLoopModes; 
 91
 92/*!
 93 Prepare before calling the asynchronous method. 
 94 */
 95- (void)prepare;
 96
 97/*!
 98 Prepare and specify the selector we will use in notify.
 99 @param selector
100 */
101- (void)prepare:(SEL)selector;
102
103/*!
104 Wait for notification of status or timeout.
105 
106 Be sure to prepare before calling your asynchronous method.
107 For example, 
108 
109 @code
110  - (void)testFoo {
111    [self prepare];
112    // Do asynchronous task here
113    [self waitForStatus:kGHUnitWaitStatusSuccess timeout:1.0];
114  }
115 @endcode
116 
117 @param status kGHUnitWaitStatusSuccess, kGHUnitWaitStatusFailure or custom status 
118 @param timeout Timeout in seconds
119 */
120- (void)waitForStatus:(NSInteger)status timeout:(NSTimeInterval)timeout;
121
122/*! 
123 @deprecated
124 */
125- (void)waitFor:(NSInteger)status timeout:(NSTimeInterval)timeout;
126
127/*!
128 Wait for timeout to occur.
129 Fails if we did _NOT_ timeout.
130 @param timeout
131 */
132- (void)waitForTimeout:(NSTimeInterval)timeout;
133
134/*!
135 Notify waiting of status for test selector.
136 @param status Status, for example, kGHUnitWaitStatusSuccess
137 @param selector If not NULL, then will verify this selector is where we are waiting.
138          This prevents stray asynchronous callbacks to fail a later test
139 */
140- (void)notify:(NSInteger)status forSelector:(SEL)selector;
141
142/*!
143 Notify waiting of status for any selector.
144 @param status Status, for example, kGHUnitWaitStatusSuccess
145 */
146- (void)notify:(NSInteger)status;
147
148/*!
149 Run the run loops for the specified interval. 
150 @param interval
151 @author Adapted from Robert Palmer, pauseForTimeout
152 */
153- (void)runForInterval:(NSTimeInterval)interval;
154
155@end