]> git.wincent.com - WOTest.git/blob - WOMock.h
Use international-friendly dates in source files
[WOTest.git] / WOMock.h
1 //
2 //  WOMock.h
3 //  WOTest
4 //
5 //  Created by Wincent Colaiuta on 14 June 2005.
6 //
7 //  Copyright 2005-2007 Wincent Colaiuta.
8 //  This program is free software: you can redistribute it and/or modify
9 //  it under the terms of the GNU General Public License as published by
10 //  the Free Software Foundation, either version 3 of the License, or
11 //  (at your option) any later version.
12 //
13 //  This program is distributed in the hope that it will be useful,
14 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
15 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 //  GNU General Public License for more details.
17 //
18 //  You should have received a copy of the GNU General Public License
19 //  along with this program.  If not, see <http://www.gnu.org/licenses/>.
20 //
21
22 #import <Foundation/Foundation.h>
23
24 /*! 
25
26 There are a small number of methods defined in the WOMock class that you can use to create a mock object and then tell it how to behave. The accept, acceptOnce, reject, expect, expectOnce methods tell the mock object which selectors to accept, reject and expect. 
27
28 Each of these methods returns an object of type id which allows you to chain selectors together using the standard Objective-C pattern:
29
30 \code
31 [[mock accept] anotherMethod];
32 \endcode
33
34 The mocked class must at least implement the NSObject method, instanceMethodSignatureForSelector:.
35
36 */
37 @interface WOMock : NSProxy {
38
39     /*! Selectors that should be accepted. */
40     NSMutableSet            *accepted;
41     
42     /*! Selectors that should be accepted once only. */
43     NSMutableSet            *acceptedOnce;
44     
45     /*! Selectors that should be expected. */
46     NSMutableSet            *expected;
47     
48     /*! Selectors that should be expected once only. */
49     NSMutableSet            *expectedOnce;
50     
51     /*! Selectors that should be expected in a specific order. */
52     NSMutableArray          *expectedInOrder;
53
54     /*! Selectors that should be rejected. */
55     NSMutableSet            *rejected; 
56     
57     NSMutableDictionary     *methodSignatures;
58     
59     BOOL                    acceptsByDefault;
60 }
61
62 #pragma mark -
63 #pragma mark Creation
64
65 /*! Convenience initializer that returns the appropriate subclass. This message should only be sent to the WOMock class, never to one of its subclasses; sending it to a subclass raises an exception. */
66 + (id)mockForObjectClass:(Class)aClass;
67
68 /*! Convenience initializer that returns the appropriate subclass. This message should only be sent to the WOMock class, never to one of its subclasses; sending it to a subclass raises an exception. */
69 + (id)mockForClass:(Class)aClass;
70
71 /*! Convenience initializer that returns the appropriate subclass. This message should only be sent to the WOMock class, never to one of its subclasses; sending it to a subclass raises an exception. */
72 + (id)mockForProtocol:(Protocol *)aProtocol;
73
74 /*! Convenience initializer that returns the appropriate subclass. This message should only be sent to the WOMock class, never to one of its subclasses; sending it to a subclass raises an exception. */
75 - (id)initWithObjectClass:(Class)aClass;
76
77 /*! Convenience initializer that returns the appropriate subclass. This message should only be sent to the WOMock class, never to one of its subclasses; sending it to a subclass raises an exception. */
78 - (id)initWithClass:(Class)aClass;
79
80 /*! Convenience initializer that returns the appropriate subclass. This message should only be sent to the WOMock class, never to one of its subclasses; sending it to a subclass raises an exception. */
81 - (id)initWithProtocol:(Protocol *)aProtocol;
82
83 /*! Basic initizialer available for use by subclasses. Do not call directly. */
84 - (id)init;
85
86 #pragma mark -
87 #pragma mark Recording expectations
88
89 /*!
90 \name Recording
91
92  These are recording methods used for setting up expectations about which selectors should be rejected, accepted, accepted once, expected, expected once, or expected in order.
93
94  When the mock receives a message it checks its internal lists in the following order (in order of decreasing specificity):
95  
96  -# rejected
97  -# expected in order
98  -# expected once
99  -# expected
100  -# accepted once
101  -# accepted
102
103  Rejected selectors cause an exception to be raised.
104  
105  By default, if a selector does not appear in any of the internal lists an exception is raised. This latter behaviour requires you to be explicit about <em>all</em> selectors which a mock object may receive. For example, you may have a mock object that stands in for an NSString instance and expect that it be sent a "lowercaseString" selector. If during your test you also send an "uppercaseString" selector then an exception will be raised (because the selector does not appear in the internal lists, even though it is a valid NSString selector). A small number of methods will be accepted even without being explicitly added the the lists; these include methods like retain and release and other NSObject protocol methods. These are accepted because they are inherited from the parent class of WOMock (NSProxy).
106  
107  If you wish to override this behaviour you may send the setAcceptsByDefault message passing a flag of YES, but be aware that selectors which fall through to the "accepts by default" cannot return any defined value. For control over return values the selector in question must be explicitly set up with the expectInOrder, expectOnce, expect, acceptOnce or accept methods.
108  
109  If a selector does appear in the lists but has been set to throw an exception an exception will be raised. It is the responsibility of the caller to avoid ambiguous list membership; for example, it does not make any sense to add a selector to both the "expected once" and the "accepted" lists.
110  
111  \startgroup
112 */
113
114 /*! Instructs the receiver to accept a selector. The following example shows how to instruct the WOMock instance mock to accept the connect selector:
115     
116 \code
117 [[mock accept] connect];
118 \endcode
119
120 If the selector takes arguments then the arguments passed to the mock must match those used when registering the selector with the accept method, otherwise an exception is raised. To override this behaviour and force the mock object to accept any arguments you can send an anyArguments selector as shown in the following example:
121
122 \code
123 [[mock accept] connectTo:server] anyArguments];
124 \endcode
125     
126 You can explicitly instruct a mock to reject selectors by using the reject method. Selectors added with the accept method will be accepted by the receiver at any time, in any order, until removed with the reject method.
127
128 See the WOMockTests class in WOTestSelfTests for usage examples.
129     
130 \see WOStub::anyArguments */
131 - (id)accept;
132
133 /*! Instructs the receiver to accept the selector once and only once. If the selector is performed twice then the second invocation will cause an exception to be raised.
134
135 \see accept */
136 - (id)acceptOnce;
137
138 /*! Instructs the receiver to reject a selector that may or may not have been previously added using the accept, acceptOnce, expect or expectOnce methods. Subsequent attempts to send the rejected selector will cause an exception to be raised. The following example shows how to instruct the WOMock instance mock to reject the connect selector:
139
140 \code
141 [[mock reject] connect];
142 \endcode
143
144  */
145 - (id)reject;
146
147 /*! Instructs the receiver to expect a selector; the receiver not only accepts the selector but it actually requires that it be sent. If the expected selector has not been received when the verify method is called (or at dealloc time) then an exception will be raised. The following example shows how to instruct the WOMock instance mock to expect the disconnect selector:
148
149 \code
150 [[mock expect] disconnect];
151 \endcode
152
153 If the selector takes arguments then the arguments passed to the mock must match those used when registering the selector with the expect method, otherwise an exception is raised. */
154 - (id)expect;
155
156 /*! Instructs the receiver to expect the selector once and only once. If the selector is performed twice then the second invocation will cause an exception to be raised. 
157
158 \see accept */
159 - (id)expectOnce;
160
161 /*! Instructs the receiver to expect the selector as part of an ordered sequence. You can build a list of expected selectors by repeatedly calling expectInOrder with the selectors that should appear in the sequence as illustrated in this example:
162     
163 \code
164 [[mock expectInOrder] connect];
165 [[mock expectInOrder] logStats];
166 [[mock expectInOrder] refreshServerList];
167 [[mock expectInOrder] logStats];
168 [[mock expectInOrder] disconnect];
169 \endcode
170
171  */
172 - (id)expectInOrder;
173
174 /*! Instructs the receive to immediately remove all selectors previously registered with expect, expectOnce, expectInOrder, acceptOnce, accept or reject. */
175 - (void)clear;
176
177 /*! \endgroup */
178
179 /*! Verifies that all selectors registered with the expect method have been performed. If any have not then an exception is raised. The verify method is automatically called at dealloc time, although you may still wish to invoke it manually. */
180 - (void)verify;
181
182 #pragma mark -
183 #pragma mark Utility methods
184
185 - (void)storeReturnValue:(NSValue *)aValue forInvocation:(NSInvocation *)invocation;
186
187 //! Example type strings:
188 //! - NSMethodSignature: types=@@:@ nargs=3 sizeOfParams=12 returnValueLength=4; (NSString -initWithString)
189 //! - NSMethodSignature: types=@@::@@ nargs=5 sizeOfParams=20 returnValueLength=4; (NSObject -performSelector:withObject:withObject:)
190 //! - NSMethodSignature: types=d@: nargs=2 sizeOfParams=8 returnValueLength=8;  (NSNumber -doubleValue)
191 //! - NSMethodSignature: types=@@:@ nargs=3 sizeOfParams=12 returnValueLength=4; (NSString -initWIthFormat)
192 //! - NSMethodSignature: types=@@:@@@ nargs=5 sizeOfParams=20 returnValueLength=4; (NSException -initWithName:reason:userInfo:)
193 - (void)setObjCTypes:(NSString *)types forSelector:(SEL)aSelector;
194
195 #pragma mark -
196 #pragma mark Accessors
197
198 //! \name  Accessor methods 
199 //! Note that the majority of instance variables in this class do not have accessors so as to avoid namespace pollution.
200 //! \startgroup 
201
202 - (BOOL)acceptsByDefault;
203 - (void)setAcceptsByDefault:(BOOL)flag;
204
205 //! Provided so that stubs can query their delegates (mocks) for information about unimplemented selectors.
206 - (NSMutableDictionary *)methodSignatures;
207
208 //! \endgroup
209
210 @end