For the Runtime Assertion Model

Basic Principles

The Runtime Assertion Model is based on assertions for testing expected results similar to JUnit. A test case requires no special meta data to be provided for its processing which leads to differentiating two specific parts of the test case code: descriptive structure and testing code. The descriptive structure represents the meta data for the test case while the testing code contains an arbitrary set of classes that provide the test case logic, i.e. verifications that certain conditions are preserved within a certain environment.

Writing a Test Case

To write a test case for the Runtime Assertion Model, you should:

1. Extend the com.prosyst.tee.tfw.asrt.TestSuite class to describe the list of tests and the order in which they are executed.
2. Provide the testing code by extending either the com.prosyst.tee.tfw.asrt.TestTemplate or the com.prosyst.tee.tfw.asrt.ExceptionTestTemplate classes.
3. Create the test case manifest file.
4. Pack the test case and execute it using the console commands provided with the tee group.

Though the test cases following the Runtime Assertion Model are OSGi-aware, it is not recommended to provide an implementation of the BundleActivator interface in your test case.

Refer to the source files of the Assertion demo for simple source examples of how to use the Assertion TFW API for developing test cases.

Descriptive Structure

The descriptive structure of a test case is usually depicted in one class that extends the com.prosyst.tee.tfw.asrt.TestSuite class which implements the com.prosyst.tee.tfw.asrt.Test interface. This class represents the root element of the test case tree. It holds information about the name and the description of the test case. It also contains a list of tests that are logically connected and should be executed in the same order as they appear in this class.

Test case nodes can be directly instantiated in the constructor of the root class. Use the add method of the TestSuite class to add them in the way you want to be executed. There are three options for adding the desired tests:

• If you want to add a single test method provided from a class which is part of the testing code, you should instantiate the TestMethod class.

  String className = TESTED_PACKAGE_NAME + "MyFirstTestCaseClass";
  add(new TestMethod("myMethod()", className + "#testMyMethod", TEST_METHOD_DESCRIPTION));
  add(new TestMethod("mySecondMethod(int)", className + "#testMySecondMethod",
                      ANOTHER_TEST_METHOD_DESCRIPTION));

• If you want to add a single class holding several test methods from the testing code, you should instantiate the TestClass class providing the desired arguments. Note that Only test methods with names starting with "test" will be called when the TestClass is executed.

    add(new TestClass(TESTED_PACKAGE_NAME + "MySecondTestCaseClass"));  

• If you want to add some of the methods of a class and logically combine them, you should use the TestSuite class as shown in the following example:

  TestSuite ts = new TestSuite("MyTestSuite", "Provides some simple test methods");
    {
      String className = TESTED_PACKAGE_NAME + "MyThirdTestCaseClass";
      ts.add(new TestMethod(className + "#firstmethod"));
      ts.add(new TestMethod(className + "#secondmethod"));
     }
     //
          Adding the test suite to the test case tree
    add(ts);

This way of grouping test methods allows you to add methods which names does not begin with test.

TEE uses reflection to create instances of the test case class(es) listed in the descriptor structure and to invoke the declared test methods.

• If you want to add internal bundles to the test case use:

  tcjar://<entry-name>

• For example:

  <bundle tree:value="tcjar://res/tb1.jar">
      <action>install</action>
  </bundle>

Testing Code

The testing code represents the test case logic and consists of one or more classes. The testing code is loaded when the descriptive structure is executed.

The OSGi-aware test cases are written to evaluate some conditions in a specific environment. The TEE allows you to define these environments through the constructors of the class that contains testing code. For example, to use the OSGi functionality provided by the OSGi framework you can pass to the constructor of your class the BundleContext interface. During the execution of the testing code, the TEE examines the constructors of the class using reflection to make a list of the constructors with arguments satisfied by the environment. Then it creates an instance of the class using the constructor with the most arguments satisfied by the environment.

Each class part of the testing code should extend either the com.prosyst.tee.tfw.asrt.TestTemplate or the com.prosyst.tee.tfw.asrt.ExceptionTestTemplate class.

The TestTemplate class extends the com.prosyst.tee.tfw.asrt.Assert class thus providing direct calls to all assertion methods defined for this test model. These methods are used to validate that certain tested functionality works as expected. During the execution of the testing code some assertions might fail. Then the AssertionFailedError is thrown allowing you to precisely define the reason for the failure in the testing code. If you want to assert that the expected and the actual results of a tested functionality are the same, use one of the assertEquals methods of the Assert class. To assert whether a reference to an object is null or not, use one of the assertNull or the assertNotNull assertion methods. In case you want to check whether a specific condition is marked with true or false flag, use one of the assertTrue methods or one of the assertFalse methods of the Assert class. To assert that two objects are equal or not, use one of the assertSame methods or one of the assertNotSame methods. The fail method is used to mark the places in the testing code where an AssertionFailedError should be immediately thrown.

All assertions should be made only in the main execution thread of the test case.

The example that follows demonstrates the use of the assertEquals method:

Using assertion methods:

      public void testFailed() {
        assertEquals("Demonstrates how to fail a test case.", -1, +1);
      }      

There are four levels that a test case can achieve when it is executed.

The TestTemplate class also extends the com.prosyst.tee.tfw.asrt.Fixture class thus providing empty implementations of the setUp and tearDown methods. When only a single test method from the test class is executed, these methods are called before and after the test method. When a whole test class is processed these methods are called at the beginning and at the end of the class.

The ExceptionTestTemplate abstract class extends the TestTemplate class to provide a template for writing test cases that verify that a single exception is thrown. You should simply extend this class and pass to the constructor the exception that must be verified. Use the performTestabstract method to provide your testing code.

To use this class simply extend it and place your testing code in the abstract performTest method. The exception which must be verified is passed to the constructor of this class. Usually extending classes must provide a constructor that passes an exact exception class up to the constructor of this class.

Manifest File

The Runtime Assertion Model defines some additional manifest headers that can be used by developers to supply some descriptive information about the test case. Following is a list of all test case manifest headers that can be used:

• Mandatory manifest headers with specified constant values:
  • TFW-Name – Contains the name of the test case model that is used to develop this test case. Its value is Assertion.
  • TFW-Version – Holds the version of the testing framework. The value it takes is 1.0.0.
  • Target-Name – Defines the name of the target framework. Use Bosch IoT Gateway Software as a value for this header.
  • Target-Version – Specifies the version of the target framework. The header value is 5.2.0.
• Required manifest headers:
  • TestCase-Class – Holds the full path to the class representing the root element of the test case which is part of the descriptive structure.
  • TestCase-Name – Describes the human-readable name of the test case.
  • TestCase-Version – Holds the version of the test case.
  • Export-Package – Holds a list of all test case packages.

  All packages of the test case must be exported through the Export-Package manifest header.

• Optional manifest headers:
  • TestCase-Vendor – Contains the test case vendor.
  • TestCase-Description – Holds a short description of the test case.
  • TestCase-Data – Specifies the full path to the OSGi configuration XML file.

The following is an example of test case manifest file:

TestCase-Name: My Assertion Test Case
TestCase-Version: 0.9.1
TestCase-Vendor: Vendor_Name GmbH
TestCase-Description: Simple test case following the Runtime Assertion Model.
TestCase-Class: com.mypackage.test.MyTestCase
TestCase-Data: /com/mypackage/test/config_tee.osgi.assert.demo.test.xml
TFW-Name: Assertion
TFW-Version: 1.0.0
Target-Name: mBedded Server
Target-Version: 5.2.0
Export-Package: com.mypackage.test, com.mypackage.test.code