/core/externals/google-toolbox-for-mac/UnitTesting/GTMNSObject+BindingUnitTesting.h

  1//
  2//  GTMNSObject+BindingUnitTesting.h
  3//
  4//  Utilities for doing advanced unittesting with object bindings.
  5//
  6//  Copyright 2006-2008 Google Inc.
  7//
  8//  Licensed under the Apache License, Version 2.0 (the "License"); you may not
  9//  use this file except in compliance with the License.  You may obtain a copy
 10//  of the License at
 11// 
 12//  http://www.apache.org/licenses/LICENSE-2.0
 13// 
 14//  Unless required by applicable law or agreed to in writing, software
 15//  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 16//  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
 17//  License for the specific language governing permissions and limitations under
 18//  the License.
 19//
 20
 21#include <Foundation/Foundation.h>
 22
 23// Utility functions for GTMTestExposedBindings Macro. Don't use it directly
 24// but use the macro below instead
 25BOOL GTMDoExposedBindingsFunctionCorrectly(NSObject *object, 
 26                                           NSArray **errors);
 27
 28// Tests the setters and getters for exposed bindings
 29// For objects that expose bindings, this tests them for you, saving you from
 30// having to write a whole pile of set/get test code if you add binding support.
 31// You will need to implement valueClassForBinding: for your bindings,
 32// and you may possibly want to implement unitTestExposedBindingsToIgnore
 33// and unitTestExposedBindingsTestValues. See descriptions of those
 34// methods below for details.
 35//  Implemented as a macro to match the rest of the SenTest macros.
 36//
 37//  Args:
 38//    a1: The object to be checked.
 39//    description: A format string as in the printf() function. 
 40//        Can be nil or an empty string but must be present. 
 41//    ...: A variable number of arguments to the format string. Can be absent.
 42//
 43#define GTMTestExposedBindings(a1, description, ...) \
 44do { \
 45  NSObject *a1Object = (a1); \
 46  NSArray *errors = nil; \
 47  BOOL isGood = GTMDoExposedBindingsFunctionCorrectly(a1Object, &errors); \
 48  if (!isGood) { \
 49    NSString *failString; \
 50    GTM_FOREACH_OBJECT(failString, errors) { \
 51      if (description != nil) { \
 52        STFail(@"%@: %@", failString, STComposeString(description, ##__VA_ARGS__)); \
 53      } else { \
 54        STFail(@"%@", failString); \
 55      } \
 56    } \
 57  } \
 58} while(0)
 59
 60// Utility class for setting up Binding Tests. Basically a pair of a value to
 61// set a binding to, followed by the expected return value.
 62// See description of gtm_unitTestExposedBindingsTestValues: below
 63// for example of usage.
 64@interface GTMBindingUnitTestData : NSObject {
 65 @private
 66  id valueToSet_;
 67  id expectedValue_;
 68}
 69
 70+ (id)testWithIdentityValue:(id)value;
 71+ (id)testWithValue:(id)value expecting:(id)expecting;
 72- (id)initWithValue:(id)value expecting:(id)expecting;
 73- (id)valueToSet;
 74- (id)expectedValue;
 75@end
 76
 77@interface NSObject (GTMBindingUnitTestingAdditions)
 78// Allows you to ignore certain bindings when running GTMTestExposedBindings
 79// If you have bindings you want to ignore, add them to the array returned
 80// by this method. The standard way to implement this would be:
 81// - (NSMutableArray*)unitTestExposedBindingsToIgnore {
 82//    NSMutableArray *array = [super unitTestExposedBindingsToIgnore];
 83//    [array addObject:@"bindingToIgnore1"];
 84//    ...
 85//    return array;
 86//  }
 87// The NSObject implementation by default will ignore NSFontBoldBinding,
 88// NSFontFamilyNameBinding, NSFontItalicBinding, NSFontNameBinding and 
 89// NSFontSizeBinding if your exposed bindings contains NSFontBinding because
 90// the NSFont*Bindings are NOT KVC/KVO compliant.
 91- (NSMutableArray*)gtm_unitTestExposedBindingsToIgnore;
 92
 93// Allows you to set up test values for your different bindings.
 94// if you have certain values you want to test against your bindings, add
 95// them to the array returned by this method. The array is an array of
 96// GTMBindingUnitTestData.
 97//  The standard way to implement this would be:
 98// - (NSMutableArray*)gtm_unitTestExposedBindingsTestValues:(NSString*)binding {
 99//    NSMutableArray *dict = [super unitTestExposedBindingsTestValues:binding];
100//    if ([binding isEqualToString:@"myBinding"]) {
101//      MySpecialBindingValueSet *value 
102//        = [[[MySpecialBindingValueSet alloc] init] autorelease];
103//      [array addObject:[GTMBindingUnitTestData testWithIdentityValue:value]];
104//      ...
105//    else if ([binding isEqualToString:@"myBinding2"]) {
106//      ...
107//    }
108//    return array;
109//  }
110// The NSObject implementation handles many of the default bindings, and
111// gives you a reasonable set of test values to start.
112// See the implementation for the current list of bindings, and values that we
113// set for those bindings.
114- (NSMutableArray*)gtm_unitTestExposedBindingsTestValues:(NSString*)binding;
115
116// A special version of isEqualTo to test whether two binding values are equal
117// by default it calls directly to isEqualTo: but can be overridden for special
118// cases (like NSImages) where the standard isEqualTo: isn't sufficient.
119- (BOOL)gtm_unitTestIsEqualTo:(id)value;
120@end