The db2unit architecture is based on the xUnit architecture which is described in the Wikipedia article about that topic.

Test runner

In order to run the tests, it is necessary to call the RUN_SUITE procedure with the name of the tests suite, and eventually with the name of the test you want to execute.

CALL DB2UNIT.RUN_SUITE('MY_SUITE');
CALL DB2UNIT.RUN_SUITE('MY_SUITE', 'TEST_MY_TEST');

More information about how to run this procedure: Run_Suite description.

Test case

A test case is a single test of the code, where the code is executed and then the assertions are called to check the results of the execution. Each test case has the following characteristics:

  • It is a stored procedure.
  • The name of the stored procedure starts with TEST_ followed by a descriptive name.
  • The stored procedure does not have any IN/OUT/INOUT arguments.

Test fixtures

The test fixtures are routines that prepares or clean the environment. The four fixtures are stored procedures and are called:

  • ONE_TIME_SETUP.
  • SETUP.
  • TEAR_DOWN.
  • ONE_TIME_TEAR_DOWN.

Not all tests suites need to define the four fixtures; They should be defined only if the environment has to be modified in the following conditions:

  • Modification of the environment before the execution of all tests.
  • Modification of the environment before the execution of each test.
  • Modification of the environment after the execution of each test.
  • Modification of the environment after the execution of all tests.

Tests suite

A tests suite is defined in db2unit as a schema in Db2. The test cases (stored procedures) are defined in it. A database can have many Tests Suite as schemas can have.

Test execution

The execution of each test has the following steps: setup > test > tearDown. For more information, check the source code.

As part of the setup step, the test fixture SETUP is executed. And in a similar way, as part the tearDown step, the test fixture TEAR_DOWN is executed.

Test result formatter

The results are stored in a table called REPORT_TESTS under the schema of the Tests Suite name. At the end of the execution, the report is presented to the user; however, the report can be accessed later by querying the table. All executions are appended to this table, and the ExecutionID groups the results by execution.

Assertions

The framework has a set of assertion for (almost) all data types. These assertions check if the predicates are true or false.

For more information about the assertions, please check the API section.

Also, db2unit can be extended by writing its own assertions. For more information, please visit: Custom assert.

Execution ID

Each time an execution is done, an unique ID is assigned to that execution. This execution ID will have the order in which the test cases were executed. This helps to reproduce the execution, if there are errors in a particular tests order when using random test.

Internal test suite status and lock

In addition to the xUnit architecture, this framework has an internal tests suite status that allows to identify which component is executing. These status could appear in the reports.

  1. Initialization.
  2. Prepare report.
  3. Generate list.
  4. Sort list.
  5. Executing (a. BeforeSuite. b. Before. c. Test. d. After. e. AfterSuite).
  6. Calculating time.
  7. Generating reports.
  8. Clean environment.

db2unit-sequence-diagram

Also, in order to prevent concurrent executions of the same suite and generate invalid errors, a lock for each suite is activate at the suite execution, and released once it has finished.

Sequence diagram

This diagram shows the interactions of this framework. You, as user of this framework, should develop the suite in order to test your testedRoutine:

db2unit-sequence-diagram

Diagram developed at https://www.websequencediagrams.com/#

(v2) Test case states

When a test suite is executing, each test case passes across different status that describe what is happening. This is different to the test suite status.

db2unit-test-states

As you can see, the environment is set to Unstarted when the test has not been selected not started. When the execution starts, the status is changed to Executing. Depending on the execution result, it could have any of the final states: Passed, Failed or Error.

If there is an internal error, the status passes to Unknown and this should be notified here as an issue.

Test case return status

After executing an assertion, it returns an error code (error level in Windows) that describes the type of error in the assertion. This is useful when executing the assertion outside a test suite. The list of return codes in the source code.

ER diagram

All objects are defined in the database. The following diagram explains how the objects are distributed:

db2unit-ER-diagram

First line: Table's name
# Primary key (mandatory.)
* Mandatory field.
o Optional field.

+--------------+
| SUITE        |            +--------------+
| # Suite_Name |=====- - -|<| SUITE_LOCK   |
| o Properties |            | # Suite_Name |
+--------------+            +--------------+
      ||
      ||                +----------------+
      ''  ++====- - - -<| SORT           |
      ''  ||            | # Suite_Name   |
      ''  ||            | # Execution_ID |
      -A- ||            | # Position     |     +----------------+
+-----------------+     | * Test_Name    |     | RESULT_TEST    |
| SUITE_EXECUTION |     +----------------+     | # Suite_Name   |
| # Suite_Name    |                            | # Execution_ID |
| # Execution_ID  |================= - - - - |<| # Test_Name    |
| o Total_Tests   |                            | * Final_State  |
| o Passed_Tests  |                            | * Date         |
| o Failed_Tests  |     +----------------+     | * Duration     |
| o Error_Tests   |     | REPORT_TEST    |     +----------------+
| o Unexec_Tests  |     | * Date         |
| o Duration      |     | * Suite_Name   |
+-----------------+     | * Execution_ID |
      -V- ||            | o Test_Name    |
      ''  ||            | o Final_State  |
      ''  ||            | o Time         |
      ''  ++======- - -<| * Message      |
      ||                +----------------+
      ||
      ||
      ||                     +------------------+
+----------------+           | EXECUTION_REPORT |
| EXECUTION      |           | * Date           |
| # Execution_ID |====- - - <| * Execution_ID   |
| * Date         |           | * Status         |
+----------------+           | * Message_Report |
                             +------------------+

(v2) The columns associated with tests and duration in the Execution table are part of version 2.

There are other tables that are just to anchor the limits of the variables (Max_Values, Max_String and Max_Signal) and for the license.

The Report_Test table exists in the schema of each suite. It means that there are as much as Report_Test tables as executed suites. There is also one of these in the installation schema, but it is just the skeleton for the others.

Description

This is the description for each table:

  • EXECUTION
  • This table contains the generated IDs for each execution. Each time RUN_SUITE is called, a new GENERATED_ID will be written in this table. If the execution fails, the GENERATED_ID will be saved in the table
  • EXECUTION_REPORT
  • This table contains the messages generated during an execution. This table is not in 3rd normal form, there is data redundancy. This table has this structure because it is considered as a log, and provide an easy way to see the reports.
  • SUITE
  • Contains the names of the registered suites. This does not ensure the associated schema exist in the database, just that a test suite was registered or it has been already executed.
  • SUITE_LOCK
  • This table contains the locks of the test suites currently being executed. During the execution of a test suite, a lock is put in this table. When the execution finishes, the lock is release (the row is deleted). If the execution is aborted (Ctrl+c) the lock should be removed manually.
  • SUITE_EXECUTION
  • This table contains the execution of test suites. (v2) This table contains the results of the execution, with the quantity of tests executed and the quantity in each state.
  • SORT
  • Order of the test for each execution. This is generated at then beginning of each execution, and this help to reproduce a random execution.
  • REPORT_TEST
  • Output of the executed tests. This table is not in 3rd normal form, and it has redundancy; however, its objective is to provide an easy way to see the messages from an execution.
  • (v2) RESULT_TEST
  • Contains the result of the execution of each test.