# Ahven Tutorial

Copyright (c) 2007, 2008 Tero Koskinen <tero.koskinen@iki.fi>

Contents:

- Introduction
- First Test Case
- Running a Test Case

## Introduction

Ahven is a unit test library modeled after JUnit library for Java. So, for JUnit users the API should be familiar.

The heart of the library is an abstract class called `Test`. It has two subclasses, `Test_Case`, and `Test_Suite`. `Test_Case` is the base class for other unit tests and `Test_Suite` is a container, which can hold `Test` objects.

## First Test Case

For your first test case, you need to create a new package and a new class, which is derived from Ahven.Framework.Test_Case. Let's call the package `My_Tests` and the class `My_Tests.Test`.

``

       -- my_tests.ads
       with Ahven.Framework;
       package My_Tests is
          type Test is new Ahven.Framework.Test_Case with null record;
       end My_Tests;

After you have defined your class, you need to overload `Test_Case`'s `Initialize` procedure and create your own test procedure (`My_First_Test`).

``

       -- my_tests.ads
       with Ahven.Framework;
       package My_Tests is
          type Test is new Ahven.Framework.Test_Case with null record;

          procedure Initialize (T : in out Test);

          procedure My_First_Test;
       end My_Tests;

Next you need to create the body of the My_Tests package. In `Initialize` procedure you need to do two things:

- Set a name for the test case,
- and register the test procedures.

``

       -- my_tests.adb
       package body My_Tests is
          procedure Initialize (T : in out Test) is
          begin
             Set_Name (T, "My tests");

             Ahven.Framework.Add_Test_Routine
               (T, My_First_Test'Access, "My first test");
          end Initialize;

          ...
       end My_Tests;

In the test procedure `My_First_Test` you can do anything you want. The Ahven package defines two utility procedures for you: `Assert (Condition : Boolean; Message : String)` and `Fail (Message : String)`.

`Assert` will raise Assertion_Error if `Condition` is `False`. `Fail` does what its name implies and will raise `Assertion_Error` always. These `Assertion_Error`s will show as failures when you run the tests.

Here is an example:

``

       -- my_tests.adb
       with Ahven;
       use Ahven;

       package body My_Tests is
          procedure Initialize (T : in out Test) is
          begin
             Set_Name (T, "My tests");

             Framework.Add_Test_Routine
               (T, My_First_Test'Access, "My first test");
          end Initialize;

          procedure My_First_Test is
          begin
             Assert (1 /= 4, "1 /= 4 failed!");
          end My_First_Test;

       end My_Tests;

## Running a Test Case

To run your tests you need to feed them to a test runner. For example, `Ahven.Text_Runner.Run` runs the tests and prints the results to the standard output.

The best way to run the tests is to define a Test_Suite, add the tests there, and give the test suite to the runner.

``

    -- runner.adb
    with Ahven.Text_Runner;
    with Ahven.Framework;
    with My_Tests;

    procedure Runner is
       S : Ahven.Framework.Test_Suite_Access :=
         Ahven.Framework.Create_Suite ("All my tests");
    begin
       Ahven.Framework.Add_Test (S.all, new My_Tests.Test);
       Ahven.Text_Runner.Run (S);
       Ahven.Framework.Release_Suite (S);
       -- Release_Suite will release all its children also.
    end Runner;

Tero Koskinen, 2008-01-07