/
RKMappingTest.h
242 lines (191 loc) · 9.88 KB
/
RKMappingTest.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
//
// RKMappingTest.h
// RestKit
//
// Created by Blake Watters on 2/17/12.
// Copyright (c) 2009-2012 RestKit. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
#import <Foundation/Foundation.h>
#import "RKMappingOperation.h"
#import "RKPropertyMappingTestExpectation.h"
@protocol RKMappingOperationDataSource, RKManagedObjectCaching;
///----------------
/// @name Constants
///----------------
/**
The domain for all errors constructed by the `RKMappingTest` class.
*/
extern NSString * const RKMappingTestErrorDomain;
/**
Name of an exception that occurs when an `RKMappingTest` object fails verification. Raised by `verifyExpectation`.
*/
extern NSString * const RKMappingTestVerificationFailureException;
/**
Mapping Test Errors
*/
enum {
RKMappingTestUnsatisfiedExpectationError, // An expected mapping event did not occur
RKMappingTestEvaluationBlockError, // An evaluation block returned `NO` when evaluating a mapping event
RKMappingTestValueInequalityError, // A value was not equal to the expected value
RKMappingTestMappingMismatchError, // A mapping occurred using an unexpected `RKObjectMapping` object
};
/**
@define RKMappingTestExpectationTestCondition
@abstract Tests a condition and returns `NO` and error if it is not true.
@discussion This is a useful macro when constructing mapping test evaluation blocks. It will test a condition and return `NO` as well as construct an error. This is meant to be used **only** within the body of a `RKMappingTestExpectationEvaluationBlock` object.
@param condition The condition to test.
@param errorCode An error code in the RKMappingTestErrorDomain indicating the nature of the failure.
@param error The NSError object to put the error string into. May be nil, but should usually be the error parameter from the expectation evaluation block.
@param ... A string describing the error.
*/
#define RKMappingTestCondition(condition, errorCode, error, ...) ({ \
if (!(condition)) { \
if (error) { \
*error = [NSError errorWithDomain:RKMappingTestErrorDomain code:errorCode userInfo:[NSDictionary dictionaryWithObjectsAndKeys:[NSString stringWithFormat:__VA_ARGS__], NSLocalizedDescriptionKey, nil]]; \
} \
return NO; \
} \
})
/**
The `RKMappingTestEvent` object for the mapping event which failed to satify the expectation.
*/
extern NSString * const RKMappingTestEventErrorKey;
/**
The `RKMappingTestExpectation` object which was not satisfied by a mapping event.
*/
extern NSString * const RKMappingTestExpectationErrorKey;
/**
An `RKMappingTest` object provides support for unit testing a RestKit object mapping operation by evaluation expectations against events recorded during an object mapping operation.
*/
@interface RKMappingTest : NSObject
///---------------------
/// @name Creating Tests
///---------------------
/**
Creates and returns a new test for a given object mapping, source object and destination
object.
@param mapping The mapping being tested.
@param sourceObject The source object being mapped from.
@param destinationObject The destionation object being to.
@return A new mapping test object for a mapping, a source object and a destination object.
*/
+ (instancetype)testForMapping:(RKMapping *)mapping sourceObject:(id)sourceObject destinationObject:(id)destinationObject;
/**
Creates and returns a new test for a given object mapping, source object, destination
object and metadata list.
@param mapping The mapping being tested.
@param sourceObject The source object being mapped from.
@param destinationObject The destionation object being to.
@param metadataList The additional metadata list to map from.
@return A new mapping test object for a mapping, a source object and a destination object.
*/
+ (instancetype)testForMapping:(RKMapping *)mapping sourceObject:(id)sourceObject destinationObject:(id)destinationObject metadataList:(NSArray *)metadataList;
/**
Initializes the receiver with a given object mapping, source object, and destination object.
@param mapping The mapping being tested.
@param sourceObject The source object being mapped from.
@param destinationObject The destionation object being to.
@return The receiver, initialized with mapping, sourceObject and destinationObject.
*/
- (instancetype)initWithMapping:(RKMapping *)mapping sourceObject:(id)sourceObject destinationObject:(id)destinationObject;
/**
Initializes the receiver with a given object mapping, source object, and destination object.
@param mapping The mapping being tested.
@param sourceObject The source object being mapped from.
@param destinationObject The destionation object being to.
@param metadataList The additional metadata list to map from.
@return The receiver, initialized with mapping, sourceObject and destinationObject.
*/
- (instancetype)initWithMapping:(RKMapping *)mapping sourceObject:(id)sourceObject destinationObject:(id)destinationObject metadataList:(NSArray *)metadataList NS_DESIGNATED_INITIALIZER;
///----------------------------
/// @name Managing Expectations
///----------------------------
/**
Adds an expectation to the receiver to be evaluated during verification.
@param expectation An expectation object to evaluate during test verification. Must be an instance of `RKPropertyMappingTestExpectation` or `RKConnectionTestExpectation`.
@see `RKMappingTestExpectation`
@see `verifiesOnExpect`
*/
- (void)addExpectation:(id)expectation;
/**
Evaluates the given expectation against the mapping test and returns a Boolean value indicating if the expectation is met by the receiver.
Invocation of this method will implicitly invoke `performMapping` if the mapping has not yet been performed.
@param expectation The expectation to evaluate against the receiver. Must be an intance of either `RKPropertyMappingTestExpectation` or `RKConnectionTestExpectation`.
@param error A pointer to an `NSError` object to be set describing the failure in the event that the expectation is not met.
@return `YES` if the expectation is met, else `NO`.
*/
- (BOOL)evaluateExpectation:(id)expectation error:(NSError **)error;
///------------------------
/// @name Verifying Results
///------------------------
/**
Performs the object mapping operation and records any mapping events that occur. The mapping events can be verified against expectation through a subsequent call to verify.
@exception NSInternalInconsistencyException Raises an `NSInternalInconsistencyException` if mapping fails.
*/
- (void)performMapping;
/**
Verifies that the mapping is configured correctly by performing an object mapping operation and ensuring that all expectations are met.
@exception RKMappingTestVerificationFailureException Raises an `RKMappingTestVerificationFailureException` exception if mapping fails or any expectation is not satisfied.
*/
- (void)verify;
/**
Evaluates the expectations and returns a Boolean value indicating if all expectations are satisfied.
Invocation of this method will implicitly invoke `performMapping` if the mapping has not yet been performed.
@return `YES` if all expectations were met, else `NO`.
*/
@property (nonatomic, readonly) BOOL evaluate;
///-------------------------
/// @name Test Configuration
///-------------------------
/**
The mapping under test. Can be either an `RKObjectMapping` or `RKDynamicMapping` object.
*/
@property (nonatomic, strong, readonly) RKMapping *mapping;
/**
A data source for the mapping operation.
If `nil`, an appropriate data source will be constructed for you using the available configuration of the receiver.
*/
@property (nonatomic, strong) id<RKMappingOperationDataSource> mappingOperationDataSource;
/**
A key path to apply to the source object to specify the location of the root of the data under test. Useful when testing subsets of a larger payload or object graph.
**Default**: `nil`
*/
@property (nonatomic, copy) NSString *rootKeyPath;
/**
The source object being mapped from.
*/
@property (nonatomic, strong, readonly) id sourceObject;
/**
The destionation object being mapped to.
If `nil`, the mapping test will instantiate a destination object to perform the mapping by invoking `[self.mappingOperationDataSource objectForMappableContent:self.sourceObject mapping:self.mapping]` to obtain a new object from the data source and then assign the object as the value for the destinationObject property.
@see `mappingOperationDataSource`
*/
@property (nonatomic, strong, readonly) id destinationObject;
#if __has_include("CoreData.h")
///----------------------------
/// @name Core Data Integration
///----------------------------
/**
The managed object context within which to perform the mapping test. Required if testing an `RKEntityMapping` object and an appropriate `mappingOperationDataSource` has not been configured.
When the `mappingOperationDataSource` property is `nil` and the test targets an entity mapping, this context is used to configure an `RKManagedObjectMappingOperationDataSource` object for the purpose of executing the test.
*/
@property (nonatomic, strong) NSManagedObjectContext *managedObjectContext;
/**
The managed object cache to use when performing a mapping test.
If the value of this property is `nil` and the test targets an entity mapping, an instance of `RKFetchRequestManagedObjectCache` will be constructed and used as the cache for the purposes of testing.
*/
@property (nonatomic, strong) id<RKManagedObjectCaching> managedObjectCache;
#endif // #if __has_include("CoreData.h")
@end