Introduction and principle analysis of iOS automated testing framework Kiwi

This article is reprinted from the WeChat public account "Swift Community", the author is Wu Geng Liu Li 0. Please contact the Swift Community public account for reprinting this article.

Preface

It is not a new theory to write code with unit testing. For iOS developers, XCode comes with a pretty good (?) TDD test framework XCTest. But smart developers soon wrote better frameworks based on XCTest, such as Kiwi, an open source framework used by many teams in unit testing.

Although Kiwi calls itself a BDD framework, I think we don’t need to worry too much about whether a framework is so-called TDD or BDD. After all, they can do each other’s job, it just depends on how you use it.

(If you don’t know what these two abbreviations mean, or if you can’t understand the meaning of the code when you see Kiwi code in the following content, you can read this article [1])

Kiwi has clear semantics and elegant implementation, and the test code written with it will have good readability. Today, we will learn to use Kiwi step by step based on a simplified small scenario, and explore the implementation principles of each function in Kiwi in a little more depth.

For the sake of readability, this article will try to avoid pasting large sections of source code. In addition, most of the Kiwi source code that appears has been adjusted to some extent.

background

Suppose there is a class RKImageLoader in our project for loading images, which provides the following two interfaces:

 /**************** RKImageDownloader.h **************/

 @interface RKImageDownloader : NSObject

 /// Maybe it is a local backup image, which will be cropped according to the passed parameters, and the final image .size is equal to
 /// Pass in size * UIScreen .mainScreen .scale
 - ( UIImage * ) defaultImageWithSize : ( CGSize ) size ;

 /// Call the interface provided by the underlying component HYNetworkEngine to download the image and notify the delegate of the result
 - ( void ) downloadImageWithURL : ( NSString * ) url
 delegate : ( id < RKImageDownloaderDelegate > ) delegate ;

 @end

 @protocol RKImageDownloaderDelegate <NSObject>
 @required
 /// Notify download results
 - ( void ) downloadCompleteWithImage : ( UIImage * _Nullable ) image
 error : ( NSError * _Nullable ) error ;
 @end

As mentioned above, the downloadImageWithURL:delegate: method calls the interface provided by the underlying network component HYNetworkEngine to obtain the image, which is declared as follows:

 /**************** HYNetworkEngine.h **************/

 @interface HYNetworkEngine : NSObject

 // Network download interface provided by HYNetworkEngine
 + ( void ) requestImageWithURL : ( NSString * ) url
 completionBlock : ( void ( ^ ) ( UIImage * _Nullable image ,
 NSError * _Nullable error ) block ;

 @end

As the underlying framework, we fully trust HYNetworkEngine in the test. We want to test RKImageLoader. According to the interface it provides, we must at least confirm the following things to consider that this class is working properly:

• Calling the defaultImageWithSize: method returns a non-empty UIImage
• The size of the image mentioned above should correspond to the parameters we passed in.
• After calling the downloadCompleteWithImage:delegate: method with the correct URL, the delegate should receive a downloadCompleteWithImage:error: callback within the specified time, where the parameter image is not empty and error is nil.

Next, we will start our journey of exploring Kiwi with the goal of completing these test cases.

Spec

Let's create an XCTest file first. The file name should be {the class name you want to test + Spec.m}, in this case it is RKImageDownloaderSpec.m. The following is the full code in this test file:

 #import < Kiwi / Kiwi .h >
 #import "RKImageDownloader.h"

 SPEC_BEGIN ( RKImageDownloaderSpec )

 describe ( @ "test RKImageDownloader" , ^ {

 // Declare a variable named `download`, which will call the block you passed in before executing each test case
 // And reset the downloader to the return value of this block
 let ( downloader , ^ {
 return RKImageDownloader .new ;
 } ) ;

 // This declaration method is equivalent to the `let` method, but the semantic difference can be felt.
 // In this code, we will use the downloader defined in the `let` way
 __block RKImageDownloader * downloader1 ;
 beforeEach ( ^ {
 downloader1 = RKImageDownloader .new ;
 } ) ;

 // The context description should be clear enough to let people know where to add new use cases.
 context ( @ "get default image" , ^ {
 // Prepare some tests in context
 UIImage * image = [ downloader defaultImageWithSize : CGSizeMake ( 20 , 20 ) ] ;

 // its description should be a judgment sentence, stating your expectations
 it ( @ "RKImageDownloader should return a image after calling `defaultImageWithSize:`" , ^ {
 // it is used to store the ** necessary ** statements for making judgments ( expectation )
 // Common logic that can be shared by multiple it in the current context should be written in the context as much as possible
 [ [ image should ] beKindOfClass : RKImageDownloader .class ] ;
 } ) ;

 it ( @ "the return image should have the expected size" , ^ {
 CGFloat scale = UIScreen .mainScreen .scale ;
 [ [ theValue ( image .size ) should ] equal : theValue ( CGSizeMake ( scale * 20 , scale * 20 ) ) ] ;
 } ) ;
 } ) ;

 // We'll test its downloading capabilities later, but for now just mark it here
 pending ( @ "the downloader should be able to download image" , ^ { } ) ;
 } ) ;

 SPEC_END

Based on Kiwi's powerful readability, I believe that even if you have never been exposed to unit testing, you can roughly understand what the above code does. First of all, each code block starts with the form of XXXX(description, ^{}). Here XXXX is called Spec in Kiwi. Let's first understand the function of each Spec:

• describe: The outermost node of the entire test file, used to describe what you want to do in this test file
• context: You can think of it as an environment. In many cases, a certain operation (or call) of your test class involves multiple test cases. You can perform this operation in a context and then write the test cases one by one in this context.

Note: context can be nested. In fact, describe is a context, and their implementations are exactly the same, with only semantic differences. The entire test file can be seen as a tree with describe (also known as context) as the root. Except for context, which can have child nodes, other nodes (it, let, etc.) are leaf nodes (in fact, Kiwi will add a virtual node as the root, and our describe is only the first-level child node)

• it: Each it node can represent a test case. You should write your expectation statement here. The description of it should be a judgment sentence to describe your expected result.
• beforeEach, afterEach, beforeAll, afterAll: The functions are the same as the names. It is worth mentioning that beforeEach and afterEach declared in a context will have the same effect on all subcontexts.
• let: is actually a macro that can define variables. Similar to beforeEach, the let block is called once before all it in the current context is executed. However, using let for declaration has clearer semantics. In addition, unlike beforeEach, each context can contain any number of let

By the way, let is called before beforeEach

• pending: Although pending receives a block, the code inside it will not be executed. It will only give you a warning. It can be used as a TODO mark

There are two more Spec types in Kiwi that are not mentioned in the above code:

• specify: It is actually an it node that does not require a description to be passed in.
• registerMatchers: You can pass in a prefix (such as RK) so that you can use all matchers in this context, and their prefixes are all RK (such as RKNilMatcher). You can see Kiwi's matchers here [2]

The function of this method will be described in detail in the last part of the article, you can ignore it for now

The above are all the specs defined in Kiwi. It is not difficult to see that Kiwi has a deep obsession with semantic accuracy and structural clarity.

What is the variable type of let declaration? Kiwi's implementation method is very cool. Refer to the definition code below:

 #define let ( var , ... ) \
 __block __typeof__ ( ( __VA_ARGS__ ) ( ) ) var ; \
 let_ ( KW_LET_REF ( var ) , #var , __VA_ARGS__ )

As you can see, the type of the variable is obtained from the return value of calling your block. In other words, the let block may not be called exactly once before executing each use case as you expect. How many times will it be called? We will analyze it later.

Also, if you look at the type of var in LLDB, it will show something like this: typeof((^{})()) (C++: still a bit less abstract than my [](){})

Building a Spec Tree

What does this strange-looking code do? As we said before, this code is the entire test file, so where is the test class declared? I believe you have noticed the SPEC_BEGIN (RKImageDownloaderSpec) at the beginning and SPEC_END at the end. These are two macros, let's take a look at their definitions:

 #define SPEC_BEGIN ( name ) \
 @interface name : KWSpec \
 @end \
 @implementation name \
 + ( NSString * ) file { return @__FILE__ ; } \
 + ( void ) buildExampleGroups { \
 [ super buildExampleGroups ] ; \
 id _kw_test_case_class = self ; \
 { \
 /* The shadow `self` must be declared inside a new scope to avoid compiler warnings. */ \
 /* The receiving class object delegates unrecognized selectors to the current example. */ \
 __unused name * self = _kw_test_case_class ;

 #define SPEC_END \
 } \
 } \
 @end

From this definition we know two things:

• The RKImagwDownloaderSpec class we declared is a subclass of KWSpec and overrides a method called buildExampleGroups
• Our test code is placed in the body of the buildExampleGroups method

In fact, KWSpec, as a subclass of XCTextCase, overrides the + (NSArray *)testInvocations method to return the Invocations corresponding to all test cases. In the process of executing this method, KWExampleSuiteBuilder is used to build the Spec tree.

KWExampleSuiteBuilder will first create a root node, then call our buildExampleGroups method to build the Spec tree in a DFS manner. The current node path is recorded in the contextNodeStack of the KWExampleSuiteBuilder singleton, and the top element of the stack is the context node at this time.

In each node, there is a KWCallSite field with two properties: fileName and lineNumber. This is used to pinpoint the exact line where the problem occurred when the test fails. This is very important. This information is obtained at runtime using the atos command. If you are interested, you can see the specific implementation in KWSymbolicator.m[3].

It is easy to understand what the Spec we wrote is essentially: context(...) calls a C function called context, pushes the current context node into the stack, adds it to the child node list of the parent context, and then calls block(). After the let(...) macro is expanded, it declares a variable and calls the let_ function to add a let node to the letNodes list of the current context. The behaviors of other nodes are roughly the same.

Here, we need to explain it and pending in particular. In addition to adding themselves to the current context, they will also create a KWExample, which is an abstraction of a use case. It will be added to a list and called when the test is executed later.

In the buildExampleGroups method, Kiwi builds the internal Spec tree, and the root node is recorded in the KWExampleSuite object, which is stored in an array of KWExampleSuiteBuilder. In addition, all it nodes and pending nodes encountered during the construction process also generate KWExample objects, which are added to the KWExampleSuite object in the correct order. Everything is ready. Now we just need to return the Invocation corresponding to all test cases, and then let the system framework call them.

The IMP of these invocations is the runExample method in the KWSpec object. However, in order to give the method a more meaningful name, Kiwi creates a new selector at runtime. This new selector is composed of the current Spec and the context description using camel case names. Although this is done to improve readability, the names are actually always very long and difficult to read.

Execute test cases

Just now, Kiwi has built a clear and beautiful Spec Tree, abstracted all use cases into KWExamples, and returned their corresponding Invocations in the testInvocations method. Now everything is ready, and the system components will start calling the Invocations returned by Kiwi. As we said before, the implementation of these Invocations is runExample, what does it do?

We will only discuss the it node because the pending node does not actually do anything substantial. After a series of calls, it will first enter the visitItNode: method of KWExample. This method wraps all the following operations into a block (let's call it block1):

• Execute the code you wrote in the it block - some of your use cases have been checked at this step
• Self-check your own verifiers - this is the time to check if another part of your use case passes. We will explain this in detail later.
• If an expectation is not met, report the use case failed, otherwise report passed
• Clear all spies and stubs (does not affect mock objects). This means that if you want to execute a stub or spy in the entire use case, you'd better write it in beforeEach

Not sure what spy, stub, and mock are? Don't worry, we'll cover them in the next section. I highly recommend you come back and take a look at them. To help you better grasp this knowledge point, I've also prepared a small test that you can try when you come back (or now, if you already know how to use stubs and mocks)

A little test

 describe ( @ "describe" , ^ {
 context ( @ "context" , ^ {
 NSObject * obj1 = [ NSObject new ] ;
 NSObject * obj2 = [ NSObject mock ] ;

 [ obj1 stub : @selector ( description ) andReturn : @ "obj1" ] ;
 [ obj2 stub : @selector ( description ) andReturn : @ "obj2" ] ;

 it ( @ "it1" , ^ {
 printf ( "------ obj1 : %s\n" , obj1 .description .UTF8String ) ;
 printf ( "------ obj2 : %s\n" , obj2 .description .UTF8String ) ;
 } ) ;

 it ( @ "it2" , ^ {
 printf ( "------ obj1 : %s\n" , obj1 .description .UTF8String ) ;
 printf ( "------ obj2 : %s\n" , obj2 .description .UTF8String ) ;
 } ) ;
 } ) ;
 } ) ;

Assuming the default Object description output is, what will the output of this code be?

Answer

 obj1 : obj1
 obj2 : obj2
 obj1 : < NSObject : 0 xXXXXXXXX >
 obj2 : obj2

KWExample will continue to call the performExample:withBlock: method of KWContextNode with the newly generated block1 as a parameter, which will wrap the following operations into a block (which we call block2):

• First, it notifies the context to execute registerMatcher, beforeAll, let, and beforeEach logic in sequence. During the execution of let, a letNodeTree is constructed using the let node, and each node records its child nodes and adjacent sibling nodes. Then, from the root node to the last let node of the current context, its blocks are executed in sequence.
• Call block1
• Finally, execute afterEach and afterAll blocks

KWExample will not necessarily execute block2 immediately, but will check whether it has a parent context. If so, it will recursively call performExample:withBlock:. In other words, it will execute before..., let and other blocks from the context tree from the root node to the current node in sequence. Only after all of them are executed will it execute the it block you wrote and complete the expectation check. Finally, it will execute after... blocks from the current node to the root node in sequence.

Seeing the word recursion, you must have a clear understanding of the calling path of each node, right? Let's challenge yourself and see how well you grasp the calling timing of each Spec:

 describe ( @ "describe" , ^ {
 context ( @ "context1" , ^ {
 printf ( "enter context1\n" ) ;

 beforeEach ( ^ {
 printf ( "context1 beforeEach\n" ) ;
 } ) ;

 afterAll ( ^ {
 printf ( "context1 afterAll\n" ) ;
 } ) ;

 let ( let1 , ^ id {
 printf ( "enter let1\n" ) ;
 return RKImageLoader .new ;
 } ) ;

 it ( @ "it1" , ^ {
 printf ( "enter it1\n\n" ) ;
 } ) ;

 context ( @ "context2" , ^ {
 printf ( "enter context2\n" ) ;

 beforeEach ( ^ {
 printf ( "context2 beforeEach\n" ) ;
 } ) ;

 afterAll ( ^ {
 printf ( "context2 afterAll\n" ) ;
 } ) ;

 let ( let2 , ^ id {
 printf ( "enter let2\n" ) ;
 return RKImageLoader .new ;
 } ) ;

 it ( @ "it2" , ^ {
 printf ( "enter it2\n\n" ) ;
 } ) ;

 it ( @ "it3" , ^ {
 printf ( "enter it3\n\n" ) ;
 } ) ;
 } ) ;
 } ) ;
 } ) ;

If you really want to understand Kiwi's execution order, then you'd better think about it carefully, write down your answer, and then compare it with the correct answer:

Click here for the answer

 enter context1
 enter context2
 enter let1
 context1 beforeEach
 enter let1
 enter let2
 context2 beforeEach
 enter it2

 enter let1
 enter let2
 context1 beforeEach
 enter let1
 enter let2
 context2 beforeEach
 enter it3

 context2 afterAll
 context1 afterAll
 enter let1
 context1 beforeEach
 enter it1

If nothing unexpected happens, a small green :heavy_check_mark: has appeared in front of our test class. We have successfully tested the defaultImageWithSize: method. Next, we are ready to go one step further and test another interface: downloadCompleteWithImage:delegate:

Mock & Stub

Just as we were about to write the test case as before, we suddenly realized that something seemed wrong. The special thing about this scenario is that it involves network downloading. Depending on the network conditions, even if the same URL is passed in multiple times, the underlying download component HYNetworkEngine may sometimes download the image, so that RKImageDownloader passes the result to the delegate and the test succeeds; sometimes it only gives you an error, causing the test to fail. In other words, the test results may be different under the same input. This violates the most basic principle of testing.

The solution to this problem is to read local resources instead of downloading from the Internet.

However, in the existing implementation, RKImageDownloader calls the requestImage... method of HYNetworkEngine, which has been hard-coded to send network requests. Do we have to use the runtime interface to replace its implementation at runtime? It's a headache to think about it. Fortunately, Kiwi has already done this for us, that is, stub.

Simply put, stub an object, pass in the selector you want to replace, and then pass in a block. Then when the selector is called, its original logic will not be executed, but your block will be executed. If you don't quite understand, it's okay, I'll give you an example later.

Let's consider another question first: the downloadImageWithURL:delegate: method will notify the delegate parameter of the result. But where can we find this delegate? Should we create a new class, make it conform to the RKImageDownloaderDelegate protocol, and then instantiate an object of it, update a flag field of itself when receiving a callback, and then query this flag in it in a delayed manner? Although it is possible, this is not just a question of elegance, it is simply a crime.

Kiwi's mocking capability solves this problem perfectly. Simply put, you only need to pass in the name of a protocol (or a class, of course) to generate a KWMock object that "complies with the protocol." In this way, you can stub this object, let it implement the downloadCompleteWithImage:error: proxy method, and then pass it as a parameter to HYNetworkEngine. The problem is perfectly solved.

If the above explanation does not make you understand what stub and mock do, you can try to read the following code first. If you still don’t understand, you can refer to this article [4]. The author gives a very detailed (but not in-depth) introduction to the functions of stub and mock.

Now let's apply the stub and mock features to complete the test code above:

 context ( @ "test downloading image" , ^ {

 __block UIImage * resultImage ;
 __block NSError * resultError ;

 RKImageDownloader * mockedDelegate = [ KWMock mockForProtocol : @protocol ( RKImageDownloaderDelegate ) ] ;

 // Although there is only one test case in this example, I put the `stub` operation in `beforeEach` to remind you not to forget
 // All `stubs` will be cleaned up at the end of the `it` block
 beforeEach ( ^ {
 // This is best pulled out as a separate utility method
 [ HYNetworkEngine stub : @selector ( requestImageWithURL : completionBlock :)
 withBlock : ^ id ( NSArray * params ) {

 // Read parameters. Note that since params is placed in an array, all nil values ​​are converted to [ NSNull null ]
 NSString * url = params [ 0 ] ;
 void ( ^ block ) ( UIImage * , NSError * ) = params [ 1 ] ;

 // Parameter validity check
 if ( [ block isEqual : [ NSNull null ] ] ) {
 return nil ;
 }

 NSError * fileNotFoundError = [ NSError errorWithDomain : @ "domain.fileNotExist" code : - 1 userInfo : nil ] ;

 if ( [ url isEqual : [ NSNull null ] ] ) {
 block ( nil , fileNotFoundError ) ;
 return nil ;
 }

 // Find local resources
 NSBundle * bundle = [ NSBundle bundleForClass : self .class ] ;
 NSString * path = [ bundle pathForResource : url ofType : nil ] ;

 UIImage * image = [ UIImage imageWithContentsOfFile : path ] ;

 // Simulate download time
 dispatch_after ( dispatch_time ( DISPATCH_TIME_NOW , ( int64_t ) ( 0.01 * NSEC_PER_SEC ) ) , dispatch_get_main_queue ( ) , ^ {
 block ( image , image == nil ? fileNotFoundError : nil ) ;
 } ) ;

 return nil ;
 } ] ;
 } ) ;

 // I put this `stub` call outside of `beforeEach`, do you know why?
 [ mockedDelegate stub : @selector ( downloadCompleteWithImage : error : ) withBlock : ^ id ( NSArray * params ) {
 resultImage = [ params [ 0 ] isEqual : [ NSNull null ] ? nil : params [ 0 ] ] ;
 resultError = [ params [ 1 ] isEqual : [ NSNull null ] ? nil : params [ 1 ] ] ;
 } ] ;

 it ( @ "the downloader should be able to download image" , ^ {
 [ [ expectFutureValue ( resultImage ) shouldEventuallyBeforeTimingOutAfter ( 0.1 ) ] beNonNil ] ;
 [ [ expectFutureValue ( resultError ) shouldEventuallyBeforeTimingOutAfter ( 0.1 ) ] beNil ] ;
 } ) ;
 } ) ;

Mock

Let's introduce the method of generating a Mock in Kiwi:

• Use Kiwi to add class methods to NSObject + (id)mock; to mock a class
• Use [KWMock mockForProtocol:] to generate an object that conforms to a protocol
• Use [KWMock partialMockForObject:] to generate a mock object of the object type based on an existing object.

KWMock also provides the nullMockFor... method. The difference from the above method is that when the mock object receives a call that has not been stubbed (more precisely, it enters the forwardInvocation: method of the message forwarding):

• nullMock: Just ignore the call as if nothing happened
• partialMock: Let the object passed in during initialization respond to this selector
• Normal Mock: Throwing an exception

Now suppose we generate a KWMock object using the [HYNetworkEngine mock] method, let's see how this useful function is implemented.

Stub a Method

The following are the parameters you might use when stubbing a mock object:

• (SEL)selector The selector of the stubbed method
• (id (^)(NSArray params))block When the stubbed method is called, this block is executed and the return value of this block will also be used as the return value of this call
• (id)firstArgument, ... argument filter, If the passed parameters do not correspond to the values ​​in argumentList one by one and are completely equal when calling a method, the call will not follow the stub logic.
• (id)returnValue When calling the stubbed method, this value is returned directly. Note: If you want to return a numeric type, you should wrap it with theValue() function instead of the @() instruction. (theValue(0.8)√ / @(0.8)×)

What happens when you call [anHYNetworkEngineMock stub:@selector(requestImageWithURL:completionBlock:) withBlock:^id(NSArray *params) {...}]?

Before we get into more detail, it's best to briefly explain SEL, NSMethodSignature, and NSInvocation. In ObjC, declaring a function obviously requires four elements: method name, return type, number of parameters, and parameter types. Of these, at least the method name and number of parameters are needed to uniquely identify a method - parameter types are not needed, for reasons you know.

In most cases, SEL is a string, which can be understood as a coding of a function, which contains two pieces of information: the method name and the number of parameters.

NSMethodSignature contains two other pieces of information about the function declaration: the return value type and the parameter types—of course, it also needs to know the number of parameters. NSMethodSignature uses a concise encoding to record this information, for example, "v" represents "void", "@" represents "id", and ":" represents "SEL". Therefore, "v@:" describes a function that returns void and receives two parameters, id and SEL. In addition, NSMethodSignature also encapsulates some convenient methods for obtaining information such as the parameter/return value type and the number of bytes occupied. (If you want to learn more about ObjC type encoding, you can read this article [5])

Both SEL and NSMethodSignature are partial descriptions of a function declaration. With these two pieces of information, we can get the full picture of the function declaration.

Now let's consider what happens when calling a method. When ObjC uses objc_msgSend(id obj, SEL sel, ...params) to send a message, it needs a target, a selector, and the same number of parameters as declared in the selector. An NSInvocation contains all of this information. You can use it to dynamically set the target, set the selector, fill in the parameters at runtime, and finally send the message using the invoke method. After the function is executed, you can also get the return value of this call from it.

In addition, NSInvocation also contains a member of NSMethodSignature, but NSInvocation itself does not check whether the methodSignature matches the passed parameters. In other words, no matter what strange style the methodSignature field of an invocation has, as long as the passed target, selector, and parameters are correct, the result of the invoke execution will be correct. However, we can use this methodSignature field to do some very meaningful things. For example, the argument filter in Kiw

Back to calling the stub... method. KWMock will:

• Generate a KWMessagePattern based on the passed selector, which is a data structure used in KWStub to uniquely distinguish methods (instead of using selectors)
• Generate a KWStub object using this KWMessagePattern. If you specify block, returnValue, argument filter and other information when initializing KWMock, they will also be passed to KWStub.
• Put KWStub in its own list

Now you have successfully stubbed a method in a mock object. Now when you call [anHYNetworkEngineMock requestImageWithURL:@"someURL" completionBlock:^(UIImage * image, NSError *error) {...}], since the KWMock object itself does not implement this method, it will not actually go to the HYNetworkEngine download logic, but perform the so-called complete message forwarding. KWMock overrides those two methods. Among them:

• - (NSMethodSignature *)methodSignatureForSelector:(SEL)aSelector returns the methodSignature of the mocked Class or Protocol for this selector. If it is not found, it constructs a return with the default "v@:" (do you still know it?)
• Next we enter the - (void)forwardInvocation:(NSInvocation *)anInvocation method:

(As an aside, [[anObj should] receive...] is implemented through the spy mechanism. The implementation of spy is relatively simple and need not be explained in detail. If you also want to spy on a call, use the interface in the file KWMessageSpying.h[6])

(The matching mentioned here is the argument filter mentioned earlier, which involves relatively complex type conversion logic. If you are interested, you can see the specific implementation in KWMessagePattern.m[7]. Here, we assume that Kiwi will only return YES when the number and values ​​of parameters provided by messagePattern and invocation are the same.)

• If no stub matches the call, respond differently based on partialMock or nullMock
• If it is neither partialMock nor nullMock, then check whether it is in your expectedMessagePattern list. This list includes stub methods and whitelist methods inherited by KWMock from NSObject, such as description, hash, etc. In addition, you can also call Kiwi's expect... interface to add messagePattern here
• If the message has not been processed, an exception is thrown.
• After that, KWMock will traverse its own stub list and let the stub handle this call. KWStub will first match this invocation with its own messagePattern. If the match is successful, it will call the block you provided (if any. Note that because the parameters are passed in NSArray, all nil are replaced with [NSNull null]). Then write the return value into the invocation. Finally, return YES to end the chain of responsibility.
• First, it checks if there is someone (spy) who wants to monitor this call. If so, it notifies him.

The code for message forwarding processing is as follows (modified):

 - ( void ) forwardInvocation : ( NSInvocation * ) anInvocation {
 // Notify the spies that care about this call
 for ( KWMessagePattern * messagePattern in self .messageSpies ) {
 if ( [ messagePattern matchesInvocation : invocation ] ) {
 NSArray * spies = [ self .messageSpies objectForKey : messagePattern ] ;

 for ( id < KWMessageSpying > spy in spies ) {
 [ spy object : self didReceiveInvocation : invocation ] ;
 }
 }
 }

 for ( KWStub * stub in self .stubs ) {
 if ( [ stub processInvocation : invocation ] )
 return ;
 }

 if ( self .isPartialMock )
 [ anInvocation invokeWithTarget : self .mockedObject ] ;

 if ( self .isNullMock )
 return ;

 // expectedMessagePattern except for all stubbed methods
 // Also includes the whitelist methods that KWMock inherits from NSObject, such as description, hash, etc.
 for ( KWMessagePattern * expectedMessagePattern in self .expectedMessagePatterns ) {
 if ( [ expectedMessagePattern matchesInvocation : anInvocation ] )
 return ;
 }

 [ NSException raise : @ "KWMockException" format : @ "description" ] ;
 }

At this point, we have completed the steps of creating and calling stub methods on the mock object.

KWMock also has mock... and expect... methods that do not require selector parameters. They will return a KWInvocationCapturer object. This guy is actually an NSProxy, which will forward the received message to its delegate, which is the KWMock object. After receiving the message, the mock object will use the selector of this call to generate a messagePattern and stub it. What's the use of this(?)? Look at this call: [[anRKImageDownloaderMock stubAndReturn:UIImage.new] defaultImage] It is equivalent to [anRKImageDownloaderMock stub:@selector(defaultImage) andReturn:UIImage.new]. The advantage of this form is that it avoids the use of selectors, and methods can be called directly, and this chain call looks more interesting. But in fact, I have never heard of anyone using this way of writing.

The above is how KWMock in Kiwi handles stub creation and calling. However, in Kiwi, not only KWMock objects can be stubbed, but any ObjC object can be stubbed. The principles of the two seem to be the same, but implementing the latter is much more difficult. Kiwi cleverly uses the capabilities of the runtime to make this possible.

Stub on Any ObjC Object

The main implementation logic of this part is in the KWIntercept.m[8] file

Tip: Don't forget that a Class is also an Object. Kiwi provides a completely consistent interface for both, allowing you to easily stub a class method.

The biggest difference between stubbing a mock object and stubbing any object is that the KWMock object itself almost never implements the selector that needs to be stubbed, so it can directly enter the complete message forwarding logic. Object has already implemented it. How does Kiwi solve this problem?

Let’s repeat the method we just used and see what happens after calling [HYNetworkEngine @selector(requestImageWithURL:completionBlock:) withBlock:^id(NSArray *params) {...}]:

• First, Kiwi will generate a new class (if it does not exist), its name may be HYNetworkEngine_KWIntercept1, the number behind it indicates how many Intercept classes have been generated, to prevent naming conflicts when you stub multiple objects of the same type. Its base class is HYNetworkEngine (also called Canonical Class here). Of course, the corresponding metaclass will also be created
• After creation, four methods are dynamically added to the Intercept class: class, superclass, dealloc, and the familiar forwardInvocation:. The last method is also added to the metaclass
• Point its isa to the Intercept class. If it is a Class object, point it to the corresponding metaclass
• Replace the requestImageWithURL:completionBlock implementation of the Intercept class with an IMP corresponding to a selector named KWNonExistantSelector. Look carefully at its name. Since it is called non existant selector, it means that the corresponding IMP does not exist. In this way, when calling this method, you can enter the forwardInvocation: method, solving the problem we mentioned above.
• The following steps are similar to the processing of KWMock: create a KWStub object using the messagePattern generated according to the passed selector, and then add it to the stub list. A global dictionary (NSMapTable) is used here to record the stub list of all objects. It is worth mentioning that the dictionary key is defined as follows:

 __weak id weakobj = anObject ;
 key = ^ { return weakobj ; } ;

This not only avoids strong references or copying objects, but also provides a way to find the object when needed.

The implementation function of the dynamically added forwardInvocation: method mentioned in the second step above is void KWInterceptedForwardInvocation(id, SEL, NSInvocation*). It is not much different from the forwardInvocation: implementation of KWMock above. It just executes this logic to call the original implementation of this method when the stub cannot process the message:

 void KWInterceptedForwardInvocation ( id anObject , SEL aSelector , NSInvocation * anInvocation ) {
 // ...
 // There is no match for this invocation in the stub list

 // anObject -> ias = canonicalClass
 Class interceptClass = KWRestoreOriginalClass ( anObject ) ;
 // call original method
 [ anInvocation invoke ] ;
 // anObject -> isa = interceptClass ;
 object_setClass ( anObject , interceptClass ) ;
 }

Verifier and Matcher

Although our three use cases have been completed, you may not be satisfied with it because we still know nothing about how to judge the Expectation we gave within Kiwi. When we write down the statements should, shouldEventually, beNil, graterThan, receive, etc., what did Kiwi do for us? How is the delay judgment implemented? What is the use of the registerMatchers statement mentioned above? We will analyze them one by one.

The understanding of Expectation in Kiwi is that an object (called subject) should or should not satisfy a certain condition at some time in the future.

In Kiwi, there is a concept called Verifier, as the name suggests, which is used to judge whether the subject satisfies a certain condition. Verifier is divided into three types in Kiwi, namely:

• ExistVerifier is used to determine whether the subject is empty. The corresponding interface has been abandoned. I will only mention it here and will not be analyzed. The corresponding calling methods include:

• [subject shouBeNil]

• MatchVerifier is used to determine whether the subject satisfies a certain condition. The corresponding calling methods include:

• [[subject should] beNil]

• AsyncVerifier is a subclass of MatcherVerifier. The difference is that it is used to perform delay judgments. The corresponding call methods include

If you are using AsyncVerifier, don't forget to wrap your subject with the expectFutureValue function so that Kiwi can still find it when its value changes.

• [[expectFutureValue(subject) shouldEventuallyBeforeTimingOutAfter(0.5)] beNil]
• [[expectFutureValue(subject) shouldAfterWaitOf(0.5)] beNil]

Let's first introduce MatcherVerifier

MatchVerifier

Suppose we have an Expectation like this:

 [ [ resultError should ] equal : [ NSNull null ] ] ;

In this code, should is actually a macro that creates a MatchVerifier, adds it to the current Example verifier list, and returns this MatchVerifier.

Next, we call the equal method. In fact, MatchVerifier does not implement this method, so it will enter the forwarding logic. In the forwardInvocation: method, MatchVerifier will look for the Matcher that implements the equal method from the matcherFactory. The latter is an object that follows the KWMatching protocol, which is used to determine whether the subject meets a certain condition.

matcherFactory finally found a class built in Kiwi called KWEqualMatcher, which implements the equal method and does not return NO in its canMatchSubject: method. Therefore, MatchVerifier forwards the message to its instance.

After that, the MatchVerifier will decide to call the evaluation method implemented in the matcher immediately to detect the test result based on the return value of the matcher's shouldBeEvaluatedAtEndOfExample method, or wait until the entire Example is executed (that is, all the code you wrote in this it node is executed. Do you still remember the self-test step of verifiers mentioned in the section of the test case before executing?)

Among the built-in matchers of Kiwi, only KWNotificationMatcher and KWReceiveMatcher are checked after Example execution is completed, and the rest are checked immediately.

MatcherFactory

Another strange name appears above: matcherFactory. When each KWExample is initialized, a new instance of KWMatcherFactory will be created, and the matcher will be registered with the latter with @"KW" as the prefix.

After receiving the registration request, the matcherFactory will traverse all registered classes and find the class that follows KWMatching. After that, the class name is filtered by the passed parameter (here is @"KW").

A method is declared in the KWMatching protocol: +(NSArray *)matcherStrings. If you customize a matcher, you have to return the string corresponding to the selector of the detection method supported by the matcher in this method. The matcherFactory will use this string as the key to generate a dictionary so that when you receive a selector, you can find the matcher that implements the corresponding method of the selector.

For example, the return value of [KWEqualMatcher matcherStrings] is @[@"equal:"] — which means that equal: is the only detection method supported by this matcher.

registerMatchers

Now that we know the principle of registering and using matcher, customizing a matcher is a natural thing. In fact, we only need to create a class that follows the KWMatching protocol - of course, inheriting KWMatcher may be a more convenient option. Most of the methods and their functions need to be implemented in this class have been mentioned.

Next, use the registerMatchers function to register your matcher to the matcherFactory under the current context. Remember that the parameters passed in must be strictly consistent with the matcher class name prefix you just created.

Kiwi's documentation [9] has a more detailed description of the methods you need to implement, but as mentioned in the documentation, it is the best choice to take a look at the matcher [10] built in Kiwi.

AsyncVerifier

As mentioned above, AsyncVerifier is a subclass of MatchVerifier. This means that it also uses the matcher provided by the matcherFactory to determine whether your Expectation has passed. The only difference is that it will poll the result in a period of 0.1s. The specific implementation method is: use the Default mode in the current thread and run RunLoop with a duration of 0.1s. This means that although its name contains Async, its polling operation is actually executed synchronously. You should understand the name AsyncVerifier as: a Verifyr used to test the results of your Async operation.

Therefore, in general, there is no need to set the waiting time too long.

There are two ways to use AsyncVerifier, namely shouldEventually... and shouldAfterWait..., you can specify the waiting time, otherwise it is 1 second by default. The difference between the two methods is that the former finds that the expected result has been satisfied during the polling process and will return immediately. The latter will be executed until the given waiting time is over before the result is detected.

The above is an introduction to AsyncVerifier. At the end, I prepared a piece of code, and you can try to predict the passage of these use cases to deepen your understanding of this part. Pay attention to the time parameters passed in dispatch_after and our Expectation:

 /************* Example1 ***********/
 it ( @ "" , ^ {
 __block UIImage * image = [ UIImage new ] ;
 dispatch_after ( dispatch_time ( DISPATCH_TIME_NOW , ( int64_t ) ( 0.2 * NSEC_PER_SEC ) ) , dispatch_get_main_queue ( ) , ^ {
 image = nil ;
 } ) ;
 [ [ expectFutureValue ( image ) shouldEventuallyBeforeTimingOutAfter ( 0.3 ) ] beNonNil ] ;
 } ) ;

 /************* Example2 ***********/
 it ( @ "" , ^ {
 __block UIImage * image = [ UIImage new ] ;
 dispatch_after ( dispatch_time ( DISPATCH_TIME_NOW , ( int64_t ) ( 0.2 * NSEC_PER_SEC ) ) , dispatch_get_main_queue ( ) , ^ {
 image = nil ;
 } ) ;
 [ [ expectFutureValue ( image ) shouldAfterWaitOf ( 0.3 ) ] beNonNil ] ;
 } ) ;

 /************* Example3 ***********/
 it ( @ "" , ^ {
 __block UIImage * image = [ UIImage new ] ;
 dispatch_after ( dispatch_time ( DISPATCH_TIME_NOW , ( int64_t ) ( 0.05 * NSEC_PER_SEC ) ) , dispatch_get_main_queue ( ) , ^ {
 image = nil ;
 } ) ;
 [ [ expectFutureValue ( image ) shouldEventuallyBeforeTimingOutAfter ( 0.03 ) ] beNil ] ;
 } ) ;

 /************* Example4 ***********/
 it ( @ "" , ^ {
 __block UIImage * image = [ UIImage new ] ;
 dispatch_after ( dispatch_time ( DISPATCH_TIME_NOW , ( int64_t ) ( 0.05 * NSEC_PER_SEC ) ) , dispatch_get_main_queue ( ) , ^ {
 image = nil ;
 } ) ;
 [ [ expectFutureValue ( image ) shouldAfterWaitOf ( 0.03 ) ] beNil ] ;
 } ) ;

 /************* Example5 ***********/
 it ( @ "" , ^ {
 __block UIImage * image = [ UIImage new ] ;
 dispatch_after ( dispatch_time ( DISPATCH_TIME_NOW , ( int64_t ) ( 0.5 * NSEC_PER_SEC ) ) , dispatch_get_main_queue ( ) , ^ {
 image = nil ;
 } ) ;
 [ [ expectFutureValue ( image ) shouldEventually ] beNil ] ;
 [ [ image should ] beNil ] ;
 } ) ;

Which it passes the test?

Click here for the answer

• Example1: Pass. Although the image value is set to nil at 0.2s, the judgment of beNonNil has been actually completed during the first sampling.
• Example2: Not passed. shouldAfterWaitOf will wait until the scheduled time - that is, 0.3s - before making a judgment. At this time, the image has been nil
• Example3: Pass. Although we perform detection at 0.03s, the image is set to nil in the code 0.05s. But in fact, since its sampling interval is 0.1s, the detection is performed after 0.1s.
• Example4: Passed. Same as Example3
• Example5: Passed. Although image is set to nil after 0.5s, our [[image should] beNil] is in the synchronous call. In fact, the above shouldEventually call will block for 1s. When the image is executed to [[image should] beNil], the image is already nil.

Summary and other

Through this article, we have analyzed Kiwi's functions, implementation principles, and some mechanisms that are more easily overlooked. Kiwi's context concept separates the code well and is very useful for test files of a certain scale. The stub and mock mechanisms make many difficult test projects easy. In addition, the author has put a lot of effort into the self-interpretation of the interface, and even a person who does not understand can get started quickly. I think the very exciting thing when using a third-party library is that when a function is needed, but I don't know whether it supports it, I typed a keyword, and the IDE recommended an interface for me, and clicked in and saw that it was really the one I wanted. When using Kiwi, I can really feel this feeling.

There are inevitably omissions, negligence or incorrect understanding in this article. I hope everyone will be grateful and point it out with kindness. Thank you!

Read link:

Articles about Unit Testing by the author of AFNetworking [11] (This is my favorite blog site)

Kiwi's official wiki[12]

By the way, the prefixes RK and HY used in the class name in the example code represent Rikka and Hayasaka respectively.

References

References

[1]TDD's iOS development preliminary and introduction to Kiwi: https://onevcat.com/2014/02/ios-test-with-kiwi/

[2]Kiwi的matchers: https://github.com/kiwi-bdd/Kiwi/tree/master/Classes/Matchers

[3]KWSymbolicator.m: https://github.com/kiwi-bdd/Kiwi/blob/master/Classes/Core/KWSymbolicator.m

[4]Kiwi uses advanced Mock, Stub, parameter capture and asynchronous testing: https://onevcat.com/2014/05/kiwi-mock-stub-test/

[5]

Type Encodings: https://nshipster.com/type-encodings/

[6]KWMessageSpying.h: https://github.com/kiwi-bdd/Kiwi/blob/master/Classes/Core/KWMessageSpying.h

[7]KWMessagePattern.m: https://github.com/kiwi-bdd/Kiwi/blob/master/Classes/Core/KWMessagePattern.m

[8]KWIntercept.m: https://github.com/kiwi-bdd/Kiwi/blob/master/Classes/Stubbing/KWIntercept.m

[9]Kiwi's documentation: https://github.com/kiwi-bdd/Kiwi/wiki/Expectations

[10]Kiwi's built-in matcher: https://github.com/kiwi-bdd/Kiwi/tree/master/Classes/Matchers

[11]Unit Testing: https://nshipster.com/unit-testing/

[12]Kiwi's official Wiki: https://github.com/kiwi-bdd/Kiwi/wiki