## Using Tests

### Note for Tiger users:

The OCUnit testing framework is now included with the DeveloperTools (starting with Xcode 2.1), so there is no more need to install the framework.

### Installing the SenTestingKit framework

To be able to compile and run the existing tests written for the BioCocoa project, you will first need to install the SenTestingKit framework, a.k.a. OCUnit.

Download the latest version from the Sente web site. Currently there are two versions of the installer, one to install in your home directory, one to install at the root level. Because of path issues, the BioCocoa Xcode project expects the OCUnit framework and the accomanying tools to be installed at the root level. So be sure to download the right installer. For all tests to work, make sure you download v40 or higher.

Files will be installed in these locations, so it is easy to remove if not needed anymore:

- /Developer/Examples/
- /Developer/Tools/
- /Developer/Source/
- /Library/Application Support/Apple/Developer Tools/File Templates/
- /Library/Application Support/Apple/Developer Tools/Project Templates/
- /Library/Application Support/Apple/Developer Tools/Target Templates/
- /Library/Frameworks/
- /usr/local/man/man1/

### Adding test classes to an existing Test target

As of May 2005, there is only one 'Test' target in the BioCocoa project, the 'Test-BCFoundation' target. Because the BCFoundation is the only framework to date, there is so far no need to add a new 'Test' target. But read the next section on how to add a target when that becomes necessary.

On the existing target (s), more tests are always welcome. To add more tests, you can either add more methods to an existing test class (a.k.a. 'test case'), or create a new class. The difference is quite subjective. A test class is supposed to group together methods that all deal with one of the BioCocoa class to be tested, or to deal with one aspect of it. For instance, the test class 'TestBCSequenceDNAInit' tests the initializers of the class BCSequenceDNA, using various parameters for the 'initWithString:' methods. Alternatively, and according to the 'test units' terminology, a class can be a 'test case', a test of a real life example. For the BioCocoa framework, a 'test case' could be a sequence file loaded from disk, and a series of tests would be performed to check that it loads and behaves properly. The bottom line is: there is no rules on how to decide when to start a new test class, it depends on what you test. Also, it is NOT critical to have clean code, or well-commented code. Typical test methods are short and self-explanatory. As long as they don't fail, nobody has to read the code. The day a test start failing because of some changes in the code in the BioCocoa code, it should be fairly easy to find the problem (it could be the test itself that does not make sense anymore!).

Practically, a test is a method with a name starting with 'test', is 5-20 lines of code and includes a 'STAssert...' statement that will fail if the behavior differs from what is expected from the BioCocoa framework. As explained above, the test methods are grouped in classes. One class will typically implement 5-50 test methods. If you create a new test class, make sure you add it to the target of interest, e.g. 'Test-BCFoundation'. Also, a test class should always be a subclass of SenTestCase and should #import the SenTestingKit header. Read the code of existing tests to have examples of test classes and class methods, and read the OCUnit documentation (link to your local documentation, only accessible after installation) to get a complete list of the macros used for assertions.

Remember to put any new file (.h and .m class files) in the right location, inside the group 'Tests/Test-BCFoundation' in the Xcode project, and in the right place in the project folder as well, 'BioCocoa/Tests/Test-BCFoundation'. By default, Xcode will not put new files in the right place on the filesystem, so check everything before you commit new files.

### Compiling and running tests

To compile the test framework, be sure to select the test target, e.g. 'Test-BCFoundation'. After you hit the 'Build' button, Xcode will compile a bundle named 'Test-BCFoundation.framework', and after compilation, will run a one-line shell script '/Developer/Tools/RunTargetUnitTests'. This tool will scan the test framework, go through all the classes, and automatically run all the methods that start with 'test...' in their names. Thus, the tests themselves are run as part of the build, after the compilation. If a test fails, it will show as a build error in the build window, and the corresponding line will link to the faulty code in the test method.

As an alternative, after the build, the tests can also be run using the 'Run' button, which will start the executable '/Developer/Tools/otest' with the appropriate arguments. The tests are executed exactly the same way as above, but the result will now be displayed in the 'Run' window, with a log of the failed tests and the successful tests, with no link to go to the code, like you found on the build window. However, you will also have information about the timing, the total number of tests, any message included in the tests, ...

### Creating a new Test target

A new 'Test' target should only be created if a new framework is ever added to the BioCocoa project, other than BCFoundation (probably BCAppKit one day...). When this becomes necessary, create a new framework target. Change the build settings based on the Test-BCFoundation target. Add an executable '/Developer/Tools/otest' and set it as the executable for the new test framework. Set the arguments of this executable taking as example the 'otest for Test-BCFoundation' executable. Finally, add a shell script phase at the end of the build of the new test target, which should be set to simply use '/bin/sh' as the shell and run the one-liner '/Developer/Tools/RunTargetUnitTests'.

It is also probably a good idea to read the OCUnit documentation to fully understand the details of the whole process.

Back to index