IntroductionThis is a quick tutorial on doing iPhone unit testing using the facilities in the Google Toolbox For Mac. Please send mail to the group if any clarification is required. Basic Project SetupHopefully your project already has an application target for building something for the iPhone. - Create a new iPhone Target of type "Cocoa Touch Application" via "Project Menu > New Target...". Choose a name that makes some sense such as "Unit Test". Be sure to use a "Cocoa Touch Application" target as opposed to a "Cocoa Application" target or a "Cocoa Touch Static Library" target.
- Add google-toolbox-for-mac/UnitTesting/GTMIPhoneUnitTestMain.m to your target
- Add google-toolbox-for-mac/UnitTesting/GTMIPhoneUnitTestDelegate.m to your target
- Add google-toolbox-for-mac/UnitTesting/GTMIPhoneUnitTestDelegate.h to your target
- Add google-toolbox-for-mac/UnitTesting/GTMSenTestCase.m to your target
- Add google-toolbox-for-mac/UnitTesting/GTMSenTestCase.h to your target
- Add google-toolbox-for-mac/GTMDefines.h to your target
- Add a new 'run script' build phase as the last step of your target build via "Project Menu > New Build Phase > New Run Script Build Phase", and dragging it to the end of the build steps if needed.
- Edit your Run Script Build Phase by double clicking it, and set the shell to "/bin/sh" and the script to "PATH_TO_GTM/UnitTesting/RunIPhoneUnitTest.sh", where PATH_TO_GTM is the path to your local version of google-toolbox-for-mac.
- Build! Note that if you choose build and go you will see your unit tests executed twice, once as part of the build script, and once being run
Your target should now build cleanly, and if you check the build log you should see something like: "Executed 0 tests, with 0 failures (0 unexpected) in 0.001 (0.001) seconds" at the end. Creating a unit test- Add the source you want to test to your target. For example if you want to test class Foo, make sure to add Foo.h and Foo.m to your target.
- Add a new unit test file to your target via "File > New File" and choose "Objective-C test case class" from the "Mac OS X" Cocoa category. Call it FooTest.m, or follow whatever convention your project has for naming test classes.
- In FooTest.h, change #import <SenTestingKit/SenTestingKit.h> to #import "GTMSenTestCase.h"
- Also set up your class so that it inherits from GTMTestCase (not GTMSenTestCase) instead of SenTestCase
@interface MyTestCase : GTMTestCase { ... } - Add test cases as you normally would. See Apple's Documentation for a good tutorial on how to test in Objective C. The key is that your test case methods are declared - (void)testBar. The name must start with "test" and they must return nothing and have no arguments.
Now when you build your target you should now see test cases executing. You can repeat this process creating additional source files for each class you want to write Unittests for. Notes- We find that having a .h for my tests to be mostly useless, and tend to just move my interface for my tests in with my implementation so I only have one file to worry about.
- Make sure to check out the extra ST macros that we have added in GTMSenTestCase.h that go above and beyond the set included with the default OCUnit.
- STAssertNoErr(a1, description, ...), STAssertErr(a1, a2, description, ...)
- STAssertNotNULL(a1, description, ...), STAssertNULL(a1, description, ...)
- STAssertNotEquals(a1, a2, description, ...), STAssertNotEqualObjects(a1, a2, desc, ...)
- STAssertEqualObjects(a1, a2, description, ...), STAssertEquals(a1, a2, description, ...), STAssertEqualsWithAccuracy(a1, a2, accuracy, description, ...)
- STAssertOperation(a1, a2, op, description, ...), STAssertGreaterThan(a1, a2, description, ...), STAssertLessThan(a1, a2, description, ...), STAssertLessThanOrEqual(a1, a2, description, ...)
- STAssertEqualStrings(a1, a2, description, ...), STAssertNotEqualStrings(a1, a2, description, ...), STAssertEqualCStrings(a1, a2, description, ...), STAssertNotEqualCStrings(a1, a2, description, ...)
- STAssertTrueNoThrow(expr, description, ...), STAssertFalseNoThrow(expr, description, ...), STAssertThrows(expr, description, ...), STAssertThrowsSpecific(expr, specificException, description, ...), STAssertThrowsSpecificNamed(expr, specificException, aName, description, ...), STAssertNoThrow(expr, description, ...), STAssertNoThrowSpecific(expr, specificException, description, ...), STAssertNoThrowSpecificNamed(expr, specificException, aName, description, ...)
- You can't run the build script while the iPhone simulator is running. The build script does attempt to kill it off before it runs, but if you see Couldn't register PurpleSystemEventPort with the bootstrap server. Error: unknown error code. This generally means that another instance of this process was already running or is hung in the debugger. or Abort trap "$TARGET_BUILD_DIR/$EXECUTABLE_PAT" -RegisterForSystemEvents you probably need to figure out why the simulator (or another iPhone process) is already running. The exact error has changed with different versions of the iPhone SDK.
Advanced StuffUnit test LoggingWhen Unittesting is done correctly, you often have a lot of log messages logging because you are testing edge cases that you may not expect to hit in the real world very often. It's nice to be able to verify that the log messages you are receiving as you run your tests are the ones that you expect to receive. You can do this in GTM by enabling unit test logging. - Assuming you are using _GTMDevLog to do your logging,#define _GTMDevLog _GTMUnittestDevLog somewhere, either in target settings, or in your prefix. If you are using NSLog you can just define it to be _GTMUnittestDevLog.
- Add google-toolbox-for-mac/DebugUtils/GTMDevLog.m to your target.
- Add google-toolbox-for-mac/UnitTesting/GTMUnitTestDevLog.m to your target.
- Add google-toolbox-for-mac/Foundation/GTMRegex.m to your target.
- You may also need to add some headers depending on your search paths
Now when you build all of the logging that you do via your unit tests will get checked to make sure that it conforms with your expectations. You set up these expectations before running your tests using [GTMUnitTestDevLog expect*] methods. See GTMUnitTestDevLog.h for more info. UI and State TestingGTM can also help you test your UI's representation and state. - Add google-toolbox-for-mac/UnitTesting/GTMNSObject+UnitTesting.m to your target.
- Add google-toolbox-for-mac/UnitTesting/GTMUIKit+UnitTesting.m to your target.
- Add google-toolbox-for-mac/UnitTesting/GTMCALayer+UnitTesting.m to your target.
- Add google-toolbox-for-mac/Foundation/GTMSystemVersion.m to your target.
- Add the CoreGraphics and QuartzCore frameworks to your target.
- You may also need to add some headers depending on your search paths
Check out UnitTesting/GTMUIKit+UnitTestingTest.m for examples of using UIUnitTesting on the iPhone. For more information on some of this, check out CodeVerificationAndUnitTesting. Hope this helps. Unit Test Environment VariablesTo encourage "bad behavior" by the code being tested, the RunIPhoneUnitTest.sh script sets a variety of environment variables. If you are wondering why the unit tests fail when you are building, but don't fail when you are running, it may be because of a side effect of one of these variables. Take a look at all the export commands within RunIPhoneUnitTest.sh to see what's actually going on. LeaksBy default the iPhone unit tests will run leaks after all the tests have completed. This can be turned off by setting the GTM_DISABLE_LEAKS environment variable before you execute the RunIPhoneUnitTest.sh script. Out of the box, NSZombies will also be enabled. This however interferes slightly with leaks and makes it difficult to get good backtraces and context. If you want the backtraces and context, set the GTM_DISABLE_ZOMBIES environment variable before you execute the RunIPhoneUnitTest.sh script. All leaks will appear as warnings on the build console. TerminationSome of Apple's tools (such as Instruments) don't want the app to terminate underneath them. By default the iPhone unit test app will terminate when it has finished it's run. Set the GTM_DISABLE_TERMINATION environment variable if you want to disable termination and just have the unit test "run" until you are done with it.
|
Sign in to add a comment
Does this work on the device as well? Whenever I try to run it I get an error "bad CPU type in exectuable"
Current script seems to run the test suites twice for some reason...
I followed the instructions above but was unable to see any messages in the console. I did not see the behavior described above as:
Your target should now build cleanly, and if you check the build log you should see something like: "Executed 0 tests, with 0 failures (0 unexpected) in 0.001 (0.001) seconds" at the end.
It turned out that I needed to set the base SDK in the inspector for my target to an iPhone simulator even though the Overview showed I was building for simulator debugging.
Does anyone know how to run these test cases in a GDB environment? I would love to break on exceptions if I could.
+1 on last remark, how to debug test cases ?
I'm guessing there isn't a way to debug the test cases because of the way the whole thing is built right now. We're building a target application and then running it as a build event. Debugging usually starts AFTER building...but our tests are being run during the build...
Wish that wasn't the case. May be someone would like to convert the shell script to an objective c function and then we can call that in the test application's appdelegate and thus be able to debug the tests.
You do not need to add any of the headers (.h) files (GTMIPhoneUnitTestDelegate.h, GTMSenTestCase.h or GTMDefines.h) to the new target. Targets don't normally contain .h files directly anyway, and the usual check-box isn't available for them. Adding them just makes XCode spit out a warning on compile, and taking them out doesn't hurt anything. Also, you can simplify adding files to target by right-clicking on the Groups & Files header (on the left) and selecting Target Membership. Remember that this changes when you switch targets.
For myself, building never kills the iPhone simulator, which I know is going to be a PITA. Where in the source code is this supposed to happen? It's not obvious.
I've got a couple more issues:
1. How do I use this when there's delegates at play? With callbacks? I have an object that does an async NSURLConnection and I want my unit test to wait for the callback and check if the value is correct.
2. When I try to test a code path that involves a .cpp file, it totally blows up.
I think I have a stupid question: I have two model objects I want to test, so I decided to create two separate test case classes (in two separate files). Am I supposed to lump all of my tests into one file? I see that the tests from my first class get loaded and executed, but my new ones don't.
Have you added the second test to the unittest target?
+1 On debug unit test cases, that would be wonderful!
I'm seeing two build errors for each test that fails. Has anyone else experienced this? Is this expected for some reason?
I'm being careful to just Build my unit tests not Build and Go but I still get duplicate failures.
NOTE Please don't use the comments for support questions, please use the Google Group, you're more likely to get responses that way. Thank you.
To those who wish to debug their applications under unit test: After the build finishes (just do build, not build and go), just click the "Run" menu and select Go (Debug). Voila, unit testing with breakpoints!
issues getting build to work: i needed to add another file from the google toolbox i.e. Foundation\GTMObjC2Runtime.h
-Shawn Arney
I also had to add GTMObjC2Runtime.