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

  1//
  2//  GTMAppKit+UnitTesting.m
  3//
  4//  Categories for making unit testing of graphics/UI easier.
  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#import <AppKit/AppKit.h>
 22#import "GTMNSObject+UnitTesting.h"
 23
 24//  Categories for making unit testing of graphics/UI easier.
 25//  Allows you to take a state/images of instances of AppKit classes.
 26//  See GTMNSObject+UnitTesting.h for details.
 27
 28@interface NSApplication (GTMUnitTestingAdditions)
 29@end
 30
 31@interface NSWindow (GTMUnitTestingAdditions) <GTMUnitTestingImaging>
 32@end
 33
 34@interface NSControl (GTMUnitTestingAdditions)
 35@end
 36
 37@interface NSButton (GTMUnitTestingAdditions)
 38@end
 39
 40@interface NSTextField (GTMUnitTestingAdditions)
 41@end
 42
 43@interface NSCell (GTMUnitTestingAdditions)
 44@end
 45
 46@interface NSImage (GTMUnitTestingAdditions) <GTMUnitTestingImaging>
 47@end
 48
 49@interface NSMenu (GTMUnitTestingAdditions)
 50@end
 51
 52@interface NSMenuItem (GTMUnitTestingAdditions)
 53@end
 54
 55@interface NSTabView (GTMUnitTestingAdditions)
 56@end
 57
 58@interface NSTabViewItem (GTMUnitTestingAdditions)
 59@end
 60
 61@interface NSToolbar (GTMUnitTestingAdditions)
 62@end
 63
 64@interface NSToolbarItem (GTMUnitTestingAdditions)
 65@end
 66
 67@interface NSMatrix (GTMUnitTestingAdditions)
 68@end
 69
 70@interface NSBox (GTMUnitTestingAdditions)
 71@end
 72
 73@interface NSSegmentedControl (GTMUnitTestingAdditions)
 74@end
 75
 76@interface NSComboBox (GTMUnitTestingAdditions)
 77@end
 78
 79@protocol GTMUnitTestViewDrawer;
 80
 81//  Fails when the |a1|'s drawing in an area |a2| does not equal the image file named |a3|.
 82//  See the description of the -gtm_pathForImageNamed method
 83//  to understand how |a3| is found and written out.
 84//  See the description of the GTMUnitTestView for a better idea
 85//  how the view works.
 86//  Implemented as a macro to match the rest of the SenTest macros.
 87//
 88//  Args:
 89//    a1: The object that implements the GTMUnitTestViewDrawer protocol
 90//        that is doing the drawing.
 91//    a2: The size of the drawing
 92//    a3: The name of the image file to check against.
 93//        Do not include the extension
 94//    a4: contextInfo to pass to drawer
 95//    description: A format string as in the printf() function.
 96//        Can be nil or an empty string but must be present.
 97//    ...: A variable number of arguments to the format string. Can be absent.
 98//
 99
100#define GTMAssertDrawingEqualToImageNamed(a1, a2, a3, a4, description, ...) \
101  do { \
102    id<GTMUnitTestViewDrawer> a1Drawer = (a1); \
103    NSSize a2Size = (a2); \
104    NSString* a3String = (a3); \
105    void *a4ContextInfo = (a4); \
106    NSRect frame = NSMakeRect(0, 0, a2Size.width, a2Size.height); \
107    GTMUnitTestView *view = [[[GTMUnitTestView alloc] initWithFrame:frame drawer:a1Drawer contextInfo:a4ContextInfo] autorelease]; \
108    GTMAssertObjectImageEqualToImageNamed(view, a3String, STComposeString(description, ##__VA_ARGS__)); \
109  } while(0)
110
111//  Category for making unit testing of graphics/UI easier.
112
113//  Allows you to take a state of a view. Supports both image and state.
114//  See NSObject+UnitTesting.h for details.
115@interface NSView (GTMUnitTestingAdditions) <GTMUnitTestingImaging>
116//  Returns whether unitTestEncodeState should recurse into subviews
117//
118//  If you have "Full keyboard access" in the
119//  Keyboard & Mouse > Keyboard Shortcuts preferences pane set to "Text boxes
120//  and Lists only" that Apple adds a set of subviews to NSTextFields. So in the
121//  case of NSTextFields we don't want to recurse into their subviews. There may
122//  be other cases like this, so instead of specializing unitTestEncodeState: to
123//  look for NSTextFields, NSTextFields will just not allow us to recurse into
124//  their subviews.
125//
126//  Returns:
127//    should unitTestEncodeState pick up subview state.
128- (BOOL)gtm_shouldEncodeStateForSubviews;
129
130@end
131
132//  A view that allows you to delegate out drawing using the formal
133//  GTMUnitTestViewDelegate protocol
134//  This is useful when writing up unit tests for visual elements.
135//  Your test will often end up looking like this:
136//  - (void)testFoo {
137//   GTMAssertDrawingEqualToFile(self, NSMakeSize(200, 200), @"Foo", nil, nil);
138//  }
139//  and your testSuite will also implement the unitTestViewDrawRect method to do
140//  it's actual drawing. The above creates a view of size 200x200 that draws
141//  it's content using |self|'s unitTestViewDrawRect method and compares it to
142//  the contents of the file Foo.tif to make sure it's valid
143@interface GTMUnitTestView : NSView {
144 @private
145  id<GTMUnitTestViewDrawer> drawer_; // delegate for doing drawing (STRONG)
146  void* contextInfo_; // info passed in by user for them to use when drawing
147}
148
149//  Create a GTMUnitTestView.
150//
151//  Args:
152//    rect: the area to draw.
153//    drawer: the object that will do the drawing via the GTMUnitTestViewDrawer
154//            protocol
155//    contextInfo:
156- (id)initWithFrame:(NSRect)frame drawer:(id<GTMUnitTestViewDrawer>)drawer contextInfo:(void*)contextInfo;
157@end
158
159/// \cond Protocols
160
161// Formal protocol for doing unit testing of views. See description of
162// GTMUnitTestView for details.
163@protocol GTMUnitTestViewDrawer <NSObject>
164
165//  Draw the view. Equivalent to drawRect on a standard NSView.
166//
167//  Args:
168//    rect: the area to draw.
169- (void)gtm_unitTestViewDrawRect:(NSRect)rect contextInfo:(void*)contextInfo;
170@end
171