UKRunner class documentation
UKRunner : NSObjectOverview
Usually you are not expected to use UKRunner directly to run a test suite, but to use ukrun that will ask UKRunner to do it with +runTests .
Test Bundle Loading and Argument Parsing
UKRunner will parse arguments from the command-line bound to -[UKTestHandler isQuiet] and -[UKRunner classRegex] , and can load one or multiple test bundles, either passed among the arguments or to -runTestsInBundle:principalClass: (if you use the API directly instead of ukrun ).
Collecting Test Classes
For each test bundle, UKRunner collects test classes marked with UKTest. If you don't use a test bundle, test classes can be passed explicitly with -runTestsWithClassNames:principalClass:.
If -classRegex is set, not all the test classes passed to UKRunner API will be run, but just the subset whose name matches the regex.
Executing Test Methods
A test method is a method prefixed with test e.g. -testSometing .
For each class marked with UKTest and each test method in this class (this also includes all the inherited test methods up to the superclass that conforms to UKTest), UKRunner will create an instance and invoke the test method, then release the instance, then create a new instance for the next test method, and so on. For details, see -runTests:onInstance:ofClass: .
UKRunner also supports test class methods e.g. +testSomething .
The test methods are executed in their alphabetical order.
Notifications
Each time methods -runTestsWithClassNames:principalClass: and -runTestsInBundle:principalClass: are invoked, the runner calls +willRunTestSuite and +didRunTestSuite on the principal class, and runs the test suite between them.
For common use cases, see +[NSObject willRunTestSuite] .
Settings
- - (NSString *) classRegex
Returns the regex string used to match classes to be tested (among the classes that conforms to UKTest).
This is useful to run a test suite subset. For example, just a single class TestB, a class list TestA|TestB|TestN or a pattern-based list Test*Persistency.
-classRegex is initialized to the value of the argument -c present in the ukrun arguments.
See also -setClassRegex: .
- - (void) setClassRegex: (NSString *)aRegex
Sets the regex string used to match classes to be tested (among the classes that conforms to UKTest).
See also -classRegex .
Tool Support
- + (int) runTests
Creates a new runner and uses it to run the tests based on the command-line arguments.
For all the test bundles collected (or provided as arguments), this method uses -runTestsInBundleAtPath:currrentDirectory: to run the tests contained in each one. When all test bundles have been run, -reportTestResults is called to output the combined results.
ukrun main() creates an autorelease pool, and uses this method to run the tests.
- - (void) runTestsInBundleAtPath: (NSString *)bundlePath currentDirectory: (NSString *)cwd
Loads the given test bundle, and runs all its tests.
If the bundle path is not an absolute path, the method searches the test bundles to load in the given directory (the current directory, when +runTests is used).
Running Tests
- - (void) runTestsInBundle: (NSBundle *)bundle
Runs all the tests in the given test bundle.
This method behaves the same than -runTestsWithClassNames:principalClass:, with the test bundle principal class as the test suite principal class.
- - (void) runTestsWithClassNames: (NSArray *)testClasses principalClass: (Class)principalClass
Runs all the tests in the tested classes.
For test related configuration, +willRunTestSuite and +didRunTestSuite are sent to the principal class, see NSObject(UKPrincipalClassNotifications).
If testedClasses is nil, then it is the same than passing all the test classes present in the main bundle.
This method and -runTestsInBundle: represents a test suite invocation.
- - (void) runTests: (NSArray *)testMethods onInstance: (BOOL)instance ofClass: (Class)testClass
Runs the test methods against a test instance or class object.
testMethods contains the method names to execute on the test object or class object. If instance is YES, testMethods must contain instance methods, otherwise it must contain class methods (to be called directly on the test class). For each method in the list, the test object will be initialized with -init , and the test method called on it, then the test object will be released (and usually deallocated).
If there is a problem with the test object initialization or release (once the test method returns the control), an uncaught exception will be reported and the test execution on this test object will end (other test methods are skipped).
If there is an exception while running a test method, an uncaught exception will be reported and execution will move on to the next test method.
Test Reporting
- - (int) reportTestResults
Logs a summary that reports the current run results:
- how many test classes and test methods were executed
- how many tests failed and passed
- how many uncaught exceptions occurred
If no tests failed and no uncaught exceptions occured, returns 0 to indicate success, otherwise returns -1.