Otter Unit Test Framework User Guide

Version 00.03

Index

Introduction

This document aims to explain how to use the Otter Unit Test Framework. You will notice that this tool is quite similar to the JUnit Framework. Therefore, whoever is accustomed with JUnit will have no problem adapting to this framework.

Big Picture

1. Acquire the compacted framework (zip) in the framework sourceforge link, unzip it and put the OtterUnitTestFramework.dll in a "safe place".
2. Open the solution you wish to use this framework. Then, create a Windows Application Project in it. This solution will hold all the tests to be executed. Add to this solution the OtterUnitTestFramework.dll you put in a "safe place", as a project reference.
3. Create a Test class and write the tests methods inside it. You may create as many Test classes as you wish.
4. In the main method, get an instance of the framework application, register the Test classes you created and run the application.

Setting Up a Basic Application

Now, a detailed explanation on how to use the framework will be given. In order to ease the learning process, the explanation will be based on an small example which you can get by clicking here.

Firstly, you need to go to the sourceforge project web site, download the framework zip file and extract the OtterUnitTestFramework.dll.

After that you need create a Windows Application Project in your solution. As stated before, a sample application will be used through the whole document, thus it is assumed that the application you are creating is called OtterUsageSample inside a solution called OtterUsageSample just as the sample application.

The next step is to add the OtterUnitTestFramework.dll as a reference to the application. In order to do so, right-click in the OtterUsageSample application and select Add Reference.... Then, select the Browse tab and fetch the OtterUnitTestFramework.dll. In the sample application you can find the OtterUnitTestFramework.dll in the lib directory.

Now that you have the reference to the framework, it is time to create a Test class. In the sample application, it was created in the directory test and was called TestCaseSample.cs. The implementation is shown in Figure 1.

See in Figure 1 that the method TestCaseExecuteMethod runs the method DoNothing of the class Sample. In case no exception is thrown, the test will pass, otherwise it will fail. Note that the method DoNothing was tested.

Again, in Figure 1 the method TestCasePassAssertions makes several assertions using Assert methods. In case all of them pass, the test will succeed, otherwise it will fail. In this case, all evaluated expressions are successful resulting in a tester-method which has passed. Again, observe that methods (and object values) called by the Assert methods were tested.

On the other hand, the method TestCaseFailAssertions executes only faulty assertions. This obviously will result in a test failure.

An interesting tester-method is the TestCaseExpectException. Its goal is to test a method which throws an exception, more specifically, SampleException. In case SampleException is thrown the method passes, otherwise it fails. Thus, in this case the test is successful.

You should have observed that the there are two methods which do not follow the tester-methods rules - they are the StartUp and TearDown methods. You must have also perceived that they are overridden methods. They have the following purpose.

• StartUp is always executed before each tester-method is run.
• TearDown is always executed after each tester-method is run.

Note that in the example of Figure 1 the Startup method always creates an instance of Sample whereas the TearDown set it to null. In real-life-testing-situations, these methods are useful for opening and closing resources which are used in every tester-method.

You can create as many Test classes as you wish. After that, you have to register all Test classes in the framework and then execute it. This is pretty straightforward as displayed in Figure 2.

In Figure 2 app instance was retrieved from a Factory (singleton element). Also, see that the Test class were registered simply by using the property TestRegistration which has the register method RegisterTest. Finally, the application was executed using the method ExecuteApplication. Note that these steps were taken in the Main method.

Now you need to run the application. In order to do so, right-click on the OtterUsageSample project, click Debug and Start new instance. This will launch the Otter Unit Test Framework. The explanation on how to interact with the application is given in the next topic.

Using the Framework

In this session it is described how to use the Otter Unit Test Framework. You will notice that the interface is quite intuitive and its usage is quite simple. Figure 3 shows the application.

As you can see in Figure 3, you have the option of selecting and unselecting the tests to be run by checking or unchecking the check boxes for each test, respectively. Also, note that you can check and uncheck all tests by clinking "Select All" or "Unselect All" respectively. In addition to that, you can see in each row of the shown table: the test class, class method and the test status. Note the list box which is open, displaying the Test class name. In case you wish to execute tests related only to one class, select it, if you want to run tests from all classes, choose the empty option (first one). Finally, in order to start the tests, click "Start Test" and should you want to quit the framework, click "Close".

After a executing the test, something resembling Figure 4 is displayed. Observe that the statistics of the tests execution are listed in the OK message. In Figure 5, you can see the results of the tests execution without the OK message. Note that are tests which have passed and others which have not. All of them represent the ones in the sample application mentioned before.

In Figure 5 you can also see a log in the middle-below part of the panel. This log shows all information regarding tests execution (i.e. tests which have passed, tests which have not passed and the reason for that).

Another way to see test messages is the following: double-click the row of a certain executed test and a screen like Figure 6 is displayed.

This covers framework functionalities. As you may have noticed, it is quite straightforward to use the Otter Unit Test Framework which is the main goal of this framework: to be simple. Next, will be covered all Assert methods and the possibilities for the ExpectedException tag.

Assert methods

Assert methods basically test methods and their results by applying a condition (e.g.: is true, is false, is null, etc.). Below are all Assert methods and their usage.

• public static void AreEqual(object firstElement, object secondElement): Returns true in case both objects (method's parameters) are equal, otherwise returns false;
• public static void AreNotEqual(object firstElement, object secondElement): Returns true in case the objects being compared (method's parameters) are different, otherwise returns false.
• public static void Fail(Exception exception): Fails the test and show information regarding the exception entered as the parameter.
• public static void Fail(string message): Fails the test and show the message entered as the method's parameter.
• public static void IsNotNull(object expression): Returns true in case the method's parameter is not null, false otherwise.
• public static void IsNull(object expression): Returns true in case the method's parameter is null, otherwise returns false.
• public static void IsTrue(bool expression): Returns true in case the method's expression is true, otherwise returns false.
• public static void ShowMessage(string message): This method does not evaluate any expression. It shows a dialog box displaying the message entered as the method's parameter.

Handling Exceptions expectations

A common situation of testing is to verify whether a method throws an exception. In this framework this can be verified with the aid of the method tag ExpectedException. Suppose you have the method ThrowSampleException and in order to successfully test this method, the SampleException must be thrown. Therefore, to program this test, call ThrowSampleException within the tester-method and mark it (the tester-method) with the tag ExpectedException(typeof(SampleException) as shown in Figure 1. By doing this, the test will pass in case an exception of type (typeof) SampleException is thrown and fail otherwise.

One important observation about the ExpectedException tag the following. Consider the example just given above. In case an exception which has inherited from SampleException was thrown, the test would still have succeeded because inheritance is considered when using the ExpectedException tag.

You should also be aware that you can enter several exceptions within the ExpectedException tag, For instance, if you make a tester-method with the following tag: ExpectedException(new Type[] { typeof(OtherException), typeof(SampleException) }), then if either OtherException, SampleException or any inherited exception were thrown, the test would be successful, otherwise it would fail.

Contact information

If you wish to send any comments, suggestions, etc., please feel free to do so by e-mail (link below).