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

  1//
  2//  GHTest.h
  3//  GHUnit
  4//
  5//  Created by Gabriel Handford on 1/18/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//! @cond DEV
 31
 32#import <Foundation/Foundation.h>
 33
 34
 35/*!
 36 Test status.
 37 */
 38typedef enum {
 39  GHTestStatusNone = 0,
 40  GHTestStatusRunning, // Test is running
 41  GHTestStatusCancelling, // Test is being cancelled
 42  GHTestStatusCancelled, // Test was cancelled
 43  GHTestStatusSucceeded, // Test finished and succeeded
 44  GHTestStatusErrored, // Test finished and errored
 45} GHTestStatus;
 46
 47enum {
 48  GHTestOptionReraiseExceptions = 1 << 0, // Allows exceptions to be raised (so you can trigger the debugger)
 49  GHTestOptionForceSetUpTearDownClass = 1 << 1, // Runs setUpClass/tearDownClass for this (each) test; Used when re-running a single test in a group
 50};
 51typedef NSInteger GHTestOptions;
 52
 53/*!
 54 Generate string from GHTestStatus
 55 @param status
 56 */
 57extern NSString* NSStringFromGHTestStatus(GHTestStatus status);
 58
 59/*!
 60 Check if test is running (or trying to cancel).
 61 */
 62extern BOOL GHTestStatusIsRunning(GHTestStatus status);
 63
 64/*!
 65 Check if test has succeeded, errored or cancelled.
 66 */
 67extern BOOL GHTestStatusEnded(GHTestStatus status);
 68
 69/*!
 70 Test stats.
 71 */
 72typedef struct {
 73  NSInteger succeedCount; // Number of succeeded tests
 74  NSInteger failureCount; // Number of failed tests
 75  NSInteger cancelCount; // Number of aborted tests
 76  NSInteger testCount; // Total number of tests 
 77} GHTestStats;
 78
 79/*!
 80 Create GHTestStats.
 81 */
 82extern GHTestStats GHTestStatsMake(NSInteger succeedCount, NSInteger failureCount, NSInteger cancelCount, NSInteger testCount);
 83
 84extern const GHTestStats GHTestStatsEmpty;
 85
 86extern NSString *NSStringFromGHTestStats(GHTestStats stats);
 87
 88@protocol GHTestDelegate;
 89
 90/*!
 91 The base interface for a runnable test.
 92 A runnable with a unique identifier, display name, stats, timer, delegate, log and error handling.
 93 */
 94@protocol GHTest <NSObject, NSCoding, NSCopying>
 95
 96- (void)run:(GHTestOptions)options;
 97
 98@property (readonly, nonatomic) NSString *identifier;  // Unique identifier for test
 99@property (readonly, nonatomic) NSString *name;
100@property (assign, nonatomic) NSTimeInterval interval;
101@property (assign, nonatomic) GHTestStatus status;
102@property (readonly, nonatomic) GHTestStats stats;
103@property (retain, nonatomic) NSException *exception;
104@property (assign, nonatomic, getter=isDisabled) BOOL disabled;
105@property (assign, nonatomic, getter=isHidden) BOOL hidden;
106@property (assign, nonatomic) id<GHTestDelegate> delegate; // weak
107
108- (NSArray *)log;
109
110- (void)reset;
111- (void)cancel;
112
113- (NSInteger)disabledCount;
114
115@end
116
117/*!
118 Test delegate for notification when a test starts and ends.
119 */
120@protocol GHTestDelegate <NSObject>
121- (void)testDidStart:(id<GHTest>)test source:(id<GHTest>)source;
122- (void)testDidUpdate:(id<GHTest>)test source:(id<GHTest>)source;
123- (void)testDidEnd:(id<GHTest>)test source:(id<GHTest>)source;
124- (void)test:(id<GHTest>)test didLog:(NSString *)message source:(id<GHTest>)source;
125@end
126
127/*!
128 Delegate which is notified of log messages from inside GHTestCase.
129 */
130@protocol GHTestCaseLogWriter <NSObject>
131- (void)log:(NSString *)message testCase:(id)testCase;
132@end
133
134/*!
135 Default test implementation with a target/selector pair.
136 - Tests a target and selector
137 - Notifies a test delegate
138 - Keeps track of status, running time and failures
139 - Stores any test specific logging
140 */
141@interface GHTest : NSObject <GHTest, GHTestCaseLogWriter> {
142  
143  NSObject<GHTestDelegate> *delegate_; // weak
144  
145  id target_;
146  SEL selector_;
147  
148  NSString *identifier_;
149  NSString *name_;  
150  GHTestStatus status_;
151  NSTimeInterval interval_;
152  BOOL disabled_;
153  BOOL hidden_;
154  NSException *exception_; // If failed
155    
156  NSMutableArray *log_;
157
158}
159
160@property (readonly, nonatomic) id target;
161@property (readonly, nonatomic) SEL selector;
162@property (readonly, nonatomic) NSArray *log;
163
164/*!
165 Create test with identifier, name.
166 @param identifier Unique identifier
167 @param name Name
168 */
169- (id)initWithIdentifier:(NSString *)identifier name:(NSString *)name;
170
171/*!
172 Create test with target/selector.
173 @param target Target (usually a test case)
174 @param selector Selector (usually a test method)
175 */
176- (id)initWithTarget:(id)target selector:(SEL)selector;
177
178/*!
179 Create autoreleased test with target/selector.
180 @param target Target (usually a test case)
181 @param selector Selector (usually a test method)
182 */
183+ (id)testWithTarget:(id)target selector:(SEL)selector;
184
185@end
186
187//! @endcond