RPG: Unit Testing with IBMiUnit Library

The IBMiUnit library is a unit testing framework for RPG that enables you to write and execute unit tests on the IBMi platform easily. In this tutorial, we’ll walk you through using the IBMiUnit library to create and run unit tests in RPG, enhancing the reliability and maintainability of your applications.

Prerequisites

Before you begin, ensure that you have the IBMiUnit library installed on your IBMi system. You can download the library from the official GitHub repository: https://github.com/WorksOfBarry/IBMiUnit

Step 1: Create the RPG Code to Be Tested

Write the RPG code you want to test, preferably as modular, reusable subprocedures. Here’s an example of a simple addition function:

**free
ctl-opt nomain;

dcl-proc Add;
  dcl-pi *n int(10);
    a int(10) value;
    b int(10) value;
  end-pi;

  return a + b;
end-proc;

Step 2: Write the Unit Test Procedures

Create a separate RPG module to hold your unit test procedures. First, include the IBMiUnit library using the `/COPY` directive:

**free
ctl-opt nomain;

/COPY IBMiUnit/QRPGLESRC,IBMiUnit

Then, write unit test procedures using the `AssertEquals` function from the IBMiUnit library. Here’s an example:

dcl-proc TestAddition;
  dcl-s result int(10);

  result = Add(3, 4);
  AssertEquals('TestAddition', 7, result);
end-proc;

Step 3: Create a Test Suite

A test suite is an RPG module that combines all your test procedures and runs them. In the test suite, include the IBMiUnit library and define the test procedures as external:

**free
ctl-opt main(MainProcedure);

/COPY IBMiUnit/QRPGLESRC,IBMiUnit

dcl-pr TestAddition;
end-pr;

Create a main procedure that runs the test procedures and reports the results:

dcl-proc MainProcedure;
  RunTest('TestAddition', %paddr(TestAddition));

  *INLR = *ON;
end-proc;

Step 4: Compile and Run the Test Suite

Compile your RPG code, test procedures, and test suite. Then, run the test suite to execute the unit tests and review the results:

CRTBNDRPG PGM(MYLIB/ADD_CODE) SRCFILE(MYLIB/QRPGLESRC) SRCMBR(ADD_CODE) DBGVIEW(*SOURCE)

CRTBNDRPG PGM(MYLIB/TEST_PROCEDURES) SRCFILE(MYLIB/QRPGL
ESRC) SRCMBR(TEST_PROCEDURES) DBGVIEW(*SOURCE)

CRTBNDRPG PGM(MYLIB/TEST_SUITE) SRCFILE(MYLIB/QRPGLESRC) SRCMBR(TEST_SUITE) DBGVIEW(*SOURCE)

CALL PGM(MYLIB/TEST_SUITE)

Step 5: Add More Unit Tests

As your application grows, add more unit tests to cover new functionality and edge cases. This helps to maintain the reliability and robustness of your code as it evolves.

For example, you could create another test procedure for the Add function:

dcl-proc TestAdditionNegativeNumbers;
  dcl-s result int(10);

  result = Add(-3, -4);
  AssertEquals('TestAdditionNegativeNumbers', -7, result);
end-proc;

Then, add the new test procedure to the test suite:

dcl-pr TestAdditionNegativeNumbers;
end-pr;

Update the MainProcedure in the test suite to run the new test:

dcl-proc MainProcedure;
  RunTest('TestAddition', %paddr(TestAddition));
  RunTest('TestAdditionNegativeNumbers', %paddr(TestAdditionNegativeNumbers));

  *INLR = *ON;
end-proc;

IBMiUnit Output

After running the test suite program (MYLIB/TEST_SUITE) with the test procedures we’ve created, you’ll see the output displayed on the console. The IBMiUnit library will provide information on the number of tests executed, passed, and failed, along with detailed error messages for any failed tests.

Here’s an example of what the output could look like:

IBMiUnit - RPG Unit Testing Framework
--------------------------------------

Test suite started...

Running test: TestAddition
TestAddition - Passed

Running test: TestAdditionNegativeNumbers
TestAdditionNegativeNumbers - Passed

Test suite completed.

--------------------------------------
Tests executed: 2
Tests passed: 2
Tests failed: 0

In this example, both tests (TestAddition and TestAdditionNegativeNumbers) have passed successfully, with no failed tests. If there were any failures, the output would provide more information about the specific failures, making it easier for you to identify and fix any issues in your RPG code.

Conclusion

In this tutorial, we’ve demonstrated how to use the IBMiUnit library to write and execute unit tests for RPG code on the IBMi platform. The IBMiUnit library simplifies the process of creating and running unit tests, helping you to maintain the reliability and maintainability of your RPG applications. As your application grows, continue to add more unit tests to cover new functionality and edge cases, ensuring that your code remains robust and maintainable.