Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
257 lines (212 sloc) 12.4 KB
//
// UMKTestUtilities.h
// URLMock
//
// Created by Prachi Gauriar on 5/29/2013.
// Copyright (c) 2015 Prachi Gauriar.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
//
/*!
@header UMKTestUtilities
@abstract Defines utility classes, functions, and macros for use when creating unit tests.
@discussion Most of the functionality is related to randomizing tests by creating random objects.
*/
#import <Foundation/Foundation.h>
NS_ASSUME_NONNULL_BEGIN
/*! @functiongroup Block-generated collections */
/*!
@abstract Returns a new NSArray instance containing elements generated by the specified element generator block.
@param count The number of elements in the newly created array.
@param elementGeneratorBlock A block that generates new elements to put into the array. May not be nil.
The block takes a single parameter, index, which is the index of the array that the generated element will occupy.
If the block returns nil, the NSNull will be placed in the generated array.
@result An array with elements generated by the element generator block.
*/
extern NSArray *UMKGeneratedArrayWithElementCount(NSUInteger count, id (^elementGeneratorBlock)(NSUInteger index));
/*!
@abstract Returns a new NSDictionary instance with entries generated using the specified key and value generator
blocks.
@discussion The key generator block will be invoked repeatedly until the generated dictionary contains count elements.
As such, care must be taken to ensure that the key generator can produce count unique values, otherwise this function
will not terminate. For example, the following invocation will never return, as (random() % 4) can only return
four values, but the requested element count is 5.
NSDictionary<NSNumber *, NSString *> *randomStrings = UMKGeneratedDictionaryWithElementCount(5, id^{
return @(random() % 4);
}, id^(id key) {
return UMKRandomUnicodeStringWithLength([key unsignedIntegerValue]);
});
@param count The number of elements in the newly created dictionary.
@param keyGeneratorBlock A block that generates keys to put into the dictionary. May not be nil. If the block returns nil,
the NSNull instance will be used as the key. However, nil will be passed to the value generator block.
@param valueGeneratorBlock A block that generates values to put into the dictionary. May not be nil.
The block takes a single parameter, key, which is the generated key for which the value will added to the dictionary.
If the key generator block returns nil, nil will be passed to the value generator block. Independent of that, if the
value generator block returns nil, the NSNull instance will be used as the value in the dictionary.
@result A dictionary with elements generated by the key and value generator blocks.
*/
extern NSDictionary *UMKGeneratedDictionaryWithElementCount(NSUInteger count, id (^keyGeneratorBlock)(void), id (^valueGeneratorBlock)(id key));
/*!
@abstract Returns a new NSSet instance containing elements generated by the specified element generator block.
@discussion The element generator block will be invoked repeatedly until the generated set contains count elements.
As such, care must be taken to ensure that the generator can produce count unique values, otherwise this function
will not terminate. For example, the following invocation will never return, as (random() % 4) can only return
four values, but the requested element count is 5.
NSSet<NSNumber *> *randomNumbers = UMKGeneratedSetWithElementCount(5, id^{
return @(random() % 4);
});
@param count The number of elements in the newly created set.
@param elementGeneratorBlock A block that generates new elements to put into the set. May not be nil. If the block
returns nil, the NSNull instance will be placed in the generated array.
@result An array with elements generated by the element generator block.
*/
extern NSSet *UMKGeneratedSetWithElementCount(NSUInteger count, id (^elementGeneratorBlock)(void));
/*! @functiongroup Random strings */
/*!
@abstract Returns a random string of alphanumeric characters.
@discussion The length of the string is (randomly) between 1 and 128.
@result A random string of alphanumeric characters.
*/
extern NSString *UMKRandomAlphanumericString(void);
/*!
@abstract Returns a random string of alphanumeric characters of the specified length.
@param length The length of the random string. Must be non-zero.
@result A random string of alphanumeric characters of the specified length.
*/
extern NSString *UMKRandomAlphanumericStringWithLength(NSUInteger length);
/*!
@abstract Returns a random string of Unicode characters.
@discussion The length of the returned string is (randomly) between 1 and 128. It may contain characters
from the Basic Latin, Latin-1 Supplement, Greek and Coptic, Cyrillic, Hebrew, Arabic, Devanagari,
Hiragana, and Katakana character sets.
@result A random string of Unicode characters.
*/
extern NSString *UMKRandomUnicodeString(void);
/*!
@abstract Returns a random string of Unicode characters of the specified length.
@discussion The returned string may contain characters from the Basic Latin, Latin-1 Supplement, Greek and
Coptic, Cyrillic, Hebrew, Arabic, Devanagari, Hiragana, and Katakana character sets.
@param length The length of the random string. Must be non-zero.
@result A random string of Unicode characters of the specified length.
*/
extern NSString *UMKRandomUnicodeStringWithLength(NSUInteger length);
/*!
@abstract Returns a random string suitable for use as a C identifier.
@discussion The length of the string is (randomly) between 1 and 128.
@result A random string suitable for use as a C identifier.
*/
extern NSString *UMKRandomIdentifierString(void);
/*!
@abstract Returns a random string of the specified length suitable for use as a C identifier.
@discussion The returned string matches the regular expression '[A-Za-z_][A-Za-z0-9_]*'
@param length The length of the random string. Must be non-zero.
@result A random string of the specified length suitable for use as a C identifier.
*/
extern NSString *UMKRandomIdentifierStringWithLength(NSUInteger length);
/*! @functiongroup Random booleans and numbers */
/*!
@abstract Returns a random boolean value.
@result A random boolean.
*/
extern BOOL UMKRandomBoolean(void);
/*!
@abstract Returns a new NSNumber instance with a random unsigned integer value.
@result A new NSNumber instance with a random unsigned integer value.
*/
extern NSNumber *UMKRandomUnsignedNumber(void);
/*!
@abstract Returns a new NSNumber instance with a random unsigned integer value in the given range.
@param range The range within which the random number should fall. The range length must be positive.
@result A new NSNumber instance with a random unsigned integer value.
*/
extern NSNumber *UMKRandomUnsignedNumberInRange(NSRange range);
/*! @functiongroup Random dictionaries */
/*!
@abstract Returns a new NSDictionary instance with the specified number of random string key-value pairs.
@param count The number of entries in the newly created dictionary.
@result A dictionary of random string key-value pairs.
*/
extern NSDictionary<NSString *, NSString *> *UMKRandomDictionaryOfStringsWithElementCount(NSUInteger count);
/*!
@abstract Returns a new random dictionary that can be safely converted to and from a URL encoded parameter string.
@discussion Nested objects may be strings, arrays, sets, or dictionaries. All dictionary keys are strings. All
sets have at least two elements. All arrays and sets contain only strings.
@param maxNestingDepth The maximum nesting depth in the returned object. For example, a maximum nesting depth of 2
means that it would be impossible to return a number in an array in a dictionary. Must be positive.
@param maxElementCountPerCollection The maximum number of elements allowed in a given collection in the returned
object. Must be positive.
@result A new random dictionary that can be safely converted to and from a URL encoded parameter string.
*/
extern NSDictionary<NSString *, id> *UMKRandomURLEncodedParameterDictionary(NSUInteger maxNestingDepth, NSUInteger maxElementCountPerCollection);
/*! @functiongroup Random JSON objects */
/*!
@abstract Returns a new random JSON object.
@discussion The type of the object is randomly chosen.
@param maxNestingDepth The maximum nesting depth in the returned object. For example, a maximum nesting depth of 2
means that it would be impossible to return a number in an array in a dictionary. Must be positive.
@param maxElementCountPerCollection The maximum number of elements allowed in a given collection in the returned
object. Must be positive.
@result A new random JSON object.
*/
extern id UMKRandomJSONObject(NSUInteger maxNestingDepth, NSUInteger maxElementCountPerCollection);
/*! @functiongroup Random HTTP methods and URLs */
/*!
@abstract Randomly returns one of @"DELETE", @"GET", @"HEAD", @"PATCH", @"POST", and @"PUT".
@result A random HTTP method.
*/
extern NSString *UMKRandomHTTPMethod(void);
/*!
@abstract Returns a new random HTTP URL.
@discussion The returned URL will either use the HTTP or HTTPS scheme, have between 1 and 10 path components (excluding
'/'), and potentially a fragment. If the URL has a query string, it will be generated by converting the result of
UMKRandomURLEncodedParameterDictionary with a maxNestingDepth between 1–3, and a maxElementCountPerCollection between
1–5.
@result A new random HTTP URL.
*/
extern NSURL *UMKRandomHTTPURL(void);
/*! @functiongroup Random Errors */
/*!
@abstract Returns a random error object.
@discussion The error has a random ten-character Unicode string as its domain, a random unsigned integer
as its code, and a five-element dictionary with random string keys and values as its userInfo.
@result A random error object.
*/
extern NSError *UMKRandomError(void);
/*! @functiongroup Waiting for conditions */
/*!
@abstract Waits no longer than the specified timeout interval for the given condition block to evaluate to YES.
@discussion This method primarily exists as a helper for testing asynchronous operations. In this case, the condition
block should return YES when the operation has completed.
@param timeoutInterval The time interval to wait for the condition block to return true. May not be negative.
@param condition A block that returns true when a given condition has been fulfilled.
@result YES if the condition block returned YES before the timeout; NO otherwise.
*/
extern BOOL UMKWaitForCondition(NSTimeInterval timeoutInterval, BOOL (^condition)(void));
/*!
@abstract XCTAsserts that the given expression evaluates to YES before the given timeout interval elapses.
@discussion You must import XCTest before using this macro. Failure to do so will result in compiler errors.
@param timeoutInterval An NSTimeInterval containing the amount of time to wait for the expression to evaluate to YES.
@param expression The boolean expression to evaluate.
@param format An NSString object that contains a printf-style string containing an error message describing the failure
condition and placeholders for the arguments.
@param ... The arguments displayed in the format string.
*/
#define UMKAssertTrueBeforeTimeout(timeoutInterval, expression, format...) \
XCTAssertTrue(UMKWaitForCondition((timeoutInterval), ^BOOL{ return (expression); }), ## format)
NS_ASSUME_NONNULL_END