Crash Course in using CppUnit

Introduction

This document can be considered a "port" of the JUnit Guide I wrote. In particular, this document talks about using CppUnit in Solaris e.g. in sun450 (although it should also work for other Unix variants such as Linux). As in the JUnit Guide, I have included only the bare minimum to get you started. I will first go through the installation of CppUnit in the next section, followed by a description of how to use CppUnit using a sample program. Next, I will suggest some ways of organizing your project and test codes before ending the document with pointers to some useful references.

Installing CppUnit

1. Download the solaris port of CppUnit and unpack the archive in a location of your choice. For the rest of this document, I will assume that you are saving and unpacking your archive at the directory /home/student/engpk:

   cd /home/student/engpk
   gunzip UnixCppUnit.tar.gz
   tar -xvf UnixCppUnit.tar
           

   The above three commands will create a new directory called UnixCppUnit in /home/student/engpk.
2. Compile the CppUnit source files:

   cd /home/student/engpk/UnixCppUnit
   make
           

   After the compilation, you should have the following in /home/student/engpk/UnixCppUnit/lib:

   -rwx------   1 engpk    compsc   1248528 libCppUnit.so*
   -rwx------   1 engpk    compsc   1200508 libCppUnitRunner.so*
   -rwx------   1 engpk    compsc   1215800 libCppUnitTest.so*
           

   Note: If you're compiling on Linux, the compilation will fail. What you need to do is to modify the file Make.rules in the config subdirectory before executing the make command. Look for the line starting with ARFLAGS in the file Make.rules and change the -G option to -shared on the same line and the compilation will be successful.
3. Copy the header files of CppUnit to the include directory:

   cd /home/student/engpk/UnixCppUnit/include
   cp ../test/framework/*.h .
   cp ../test/textui/*.h .
           

4. Test your installation by running one of the sample programs provided:

   cd /home/student/engpk/UnixCppUnit/samples
           

   You will see a file called test which is an executable program. Unfortunately, "test" is also a builtin command of the bash shell which most of you are running when you logon to our systems. Therefore, you need to rename this file before running it:

   mv test testprog
   ./testprog ExampleTestCase
           

   When you run the program testprog, you will see an error message:

   ld.so.1: testprog: fatal: libCppUnit.so: open failed: No such file or \ 
   directory
   Killed
           

   This is because the linker is unable to find the CppUnit shared library. What you should do now is to set the LD_LIBRARY_PATH environment variable (enter the following as a single line):

   export LD_LIBRARY_PATH=
   $LD_LIBRARY_PATH:/home/student/engpk/UnixCppUnit/lib
           

   You may want to put the above line in your .bash_profile or .profile so that the library path is always set when you logon to one of the main servers. Now, try running the sample program again:

   ./testprog ExampleTestCase
           

   You will see some failure messages - it's okie. This is because the sample program creates a few failed tests:

   ..F
   .F
   
   !!!FAILURES!!!
   Test Results:
   Run:  3   Failures: 2   Errors: 0
   There were 2 failures: 
   1) line: 28 ExampleTestCase.cpp "result == 6.0"
   2) line: 50 ExampleTestCase.cpp "expected: 12 but was: 13"
           

   If you got the above message, then CppUnit has been installed properly. You are now ready to use CppUnit for your development work.

Using CppUnit

Overview

Assuming that you want to test a class called Parser. The following are the general steps to use the CppUnit framework to test this class:

1. Write a class (let's call it TestParser) to test the Parser class. This class must inherit the class TestCase which is defined by the CppUnit framework.
2. Create a constructor for this class, passing a name that is representative of the set of tests for this class as the parameter.
3. Create a fixture. A test fixture is a set of sample objects that you want to (re)use during testing. For example, you might create a few sample source files for the Parser to parse. CppUnit provides a setUp and a tearDown method to manage the fixture. Therefore, you can eg. create file objects in setUp to open the source files and release these resources in the tearDown method. The important thing to note is that setUp and tearDown will be called for every 'test' that you run.
4. Each 'test' you perform is represented by the implementation of a method in the test class. For example, if you want to test whether the parser extracts the tokens correctly, you can implement a method called testGetToken. The collection of test methods you implement forms a test suite.
5. In each test method you create, use the assertion mechanism provided by CppUnit to compare the results of running the test and the results you expected. This will enable you to create repeatable tests as well as saving you lots of time from visually inspecting the results.
6. Finally, use the textual version of the TestRunner tool to run the tests and collect the results. There's also a graphical version but it hasn't been ported to solaris yet. So, you can't use it at the moment. As each test is run, CppUnit will provide feedback on whether the test ran successfully, or the test failed, or an exception has occurred.

Example

• Course.h

  #ifndef Course_h
  #define Course_h
  
  #include <string>
  
  class Course {
   public:
    // Default constructor
    Course();
  
    // Constructor
    Course(std::string nm, int gr);
  
    // method to get the name of the course
    std::string getCourseName();
  
    // method to get the grade of the course
    int getCourseGrade();
  
   private:
    std::string course_name;      // name of this course
    int grade;                    // grade of this course
  };
  #endif
      

• Course.cpp

  #include "Course.h"
  
  // default constructor
  Course::Course() {
    course_name = "";
    grade = -1;
  }
  
  // constructor
  Course::Course(std::string nm, int gr):course_name(nm) {
    grade = gr;
  }
  
  // method to get the name of the course
  std::string Course::getCourseName() { return course_name; }
  
  // method to get the grade of the course
  int Course::getCourseGrade() { return grade; }
      

• Student.h

  #ifndef Student_h
  #define Student_h
  
  #include <iostream>
  #include <string>
  #include "Course.h"
  
  const int MAXNUM = 20;     // Maximum number of courses allowed per student
  
  class Student {
  public :
    // Constructor
    Student(std::string nm, std::string no);  
    
    // Method to return student's name
    std::string getStuName();
    
    // Method to return student's number
    std::string getStuNumber();
    
    // Method to assign a grade to a course
    void assignGrade(std::string co, int gr);
    
    // Method to return the grade of a course
    int getGrade(std::string co);
  private:
    std::string name;                    // name of the student
    std::string number;                  // the student's number 
    Course course_grades[MAXNUM];        // courses taken by student
    int no_of_courses;                   // the current number of courses taken
  };
  #endif
      

• Student.cpp

  #include "Student.h"
  
  // Constructor
  Student::Student(std::string nm, std::string no):name(nm), number(no) {
    no_of_courses = 0;
  }
  
  // Method to return student's name
  std::string Student::getStuName() { return name; }
  
  // Method to return student's number
  std::string Student::getStuNumber() { return number; }
  
  // Method to assign a grade to course
  void Student::assignGrade(std::string co, int gr) {
    // check whether the maximum number of courses have been taken
    if (no_of_courses == MAXNUM) {
      std::cout << "You have exceeded the maximum number of courses !\n"; 
      return;
    }
    // create a new course
    Course c(co, gr);
    course_grades[no_of_courses++] = c;
  }
  
  // Method to return the grade of a course
  int Student::getGrade(std::string co) {
    int i = 0;
    
    while (i < no_of_courses) {
      //check if course name the same as co
      if (course_grades[i].getCourseName() == co)  
        return (course_grades[i].getCourseGrade());
      i++;
    }
    return(-1);
  }
      

cd /home/student/engpk
mkdir cs3214s

g++ -c Course.cpp
g++ -c Student.cpp

• TestStudent.h

  #ifndef TestStudent_h
  #define TestStudent_h
  
  #include <iostream>
  #include <string>
  
  // Note 1
  #include "TestCase.h"
  #include "TestSuite.h"
  #include "TestCaller.h"
  #include "TestRunner.h"
  
  #include "Student.h"
  
  class StudentTestCase : public TestCase { // Note 2 
  public:
    // constructor - Note 3
    StudentTestCase(std::string name) : TestCase(name) {}
  
    // method to test the constructor
    void testConstructor();
  
    // method to test the assigning and retrieval of grades
    void testAssignAndRetrieveGrades();
  
    // method to create a suite of tests
    static Test *suite ();
  };
  #endif
      

• TestStudent.cpp

  #include "TestStudent.h"
  
  // method to test the constructor
  void StudentTestCase::testConstructor() {  // Note 4
    // create a student object
    Student stu("Tan Meng Chee", "94-1111B-13");
  
    // check that the object is constructed correctly - Note 5
    std::string student_name = stu.getStuName();
    assert(student_name == "Tan Meng Chee");
    std::string student_number = stu.getStuNumber();
    assert(student_number == "94-1111B-13");
  }
  
  // method to test the assigning and retrieval of grades
  void StudentTestCase::testAssignAndRetrieveGrades() {
    // create a student
    Student stu("Jimmy", "946302B");
  
    // assign a few grades to this student
    stu.assignGrade("cs2102", 60);
    stu.assignGrade("cs2103", 70);
    stu.assignGrade("cs3214s", 80);
  
    // verify that the assignment is correct - Note 6
    assertEquals(60, stu.getGrade("cs2102"));
    assertEquals(70, stu.getGrade("cs2103"));
          
    // attempt to retrieve a course that does not exist
    assertEquals(-1, stu.getGrade("cs21002"));
  }
  
  // method to create a suite of tests - Note 7
  Test *StudentTestCase::suite () {
    TestSuite *testSuite = new TestSuite ("StudentTestCase");
    
    // add the tests
    testSuite->addTest (new TestCaller  
        ("testConstructor", &StudentTestCase::testConstructor));
    testSuite->addTest (new TestCaller  
        ("testAssignAndRetrieveGrades", 
         &StudentTestCase::testAssignAndRetrieveGrades));
    return testSuite;
  }
  
  // the main method - Note 8
  int main (int argc, char* argv[]) {
    if (argc != 2) {
      std::cout << "usage: tester name_of_class_being_test" << std::endl;
      exit(1);
    }
  
    TestRunner runner;
    runner.addTest(argv[1], StudentTestCase::suite());
    runner.run(argc, argv);
    
    return 0;
  }
      

• Note 1
  Remember to include these four header files: TestCase.h, TestSuite.h, TestCaller.h and TestRunner.h in all the header files (.h) of the test classes you are implementing.
• Note 2
  Every test class that you wrote must inherit the class TestCase.
• Note 3
  This constructor is quite standard. You can just cut and paste for every test class you create.
• Note 4
  This is an example of a method written to test one of the methods of the Student class. In this case, it's the constructor.
• Note 5
  The assert statement is one of the most common statements you will use. The argument is a boolean expression that must evaluate to either a true or false value.
• Note 6
  The assertEquals method can also be used to check whether a test passed or failed. It takes in two arguments and compare them. If they are not equal, an exception will be raised to indicate that the test has failed.
• Note 7
  This class method is used to assemble a suite of tests. It's also fairly standard. Just cut and paste and change accordingly to suit your needs. In particular, change StudentTestCase to the name of your test class and substitute those various test method names with your own.
• Note 8
  Again, this main method is fairly standard. So, you can just cut and paste for your test classes. Just change the class name accordingly.

g++ -c TestStudent.cpp

In file included from TestStudent.cpp:1:
TestStudent.h:7: TestCase.h: No such file or directory
TestStudent.h:8: TestSuite.h: No such file or directory
TestStudent.h:9: TestCaller.h: No such file or directory
TestStudent.h:10: TestRunner.h: No such file or directory

g++ -I/home/student/engpk/UnixCppUnit/include -c TestStudent.cpp

g++ -o tester Course.o Student.o TestStudent.o TestRunner.o \
-lCppUnit -lCppUnitRunner

g++ -L/home/student/engpk/UnixCppUnit/lib -o tester Course.o Student.o \
TestStudent.o TestRunner.o -lCppUnit -lCppUnitRunner

tester TestStudent

// In Student.h under public
// Method to return the average grade
float findAveGrade();

// In Student.cpp
// Method to return the average grade
float Student::findAveGrade() {
  float sum = 0.0, average;

  // sum up the marks in all the courses
  for (int i = 0; i < no_of_courses; i++)
    sum += course_grades[i].getCourseGrade();
  average = sum / no_of_courses;
  return(average);
}