IBMiUnit

An RPGLE unit testing framework

Installation

Clone Git Repository

This is the easiest way to obtain IBMiUnit; everyone has a Git client, right?

Well, this may not currently be the easiest way because the source still has a dependency on the OSSILE product. This will be removed in a future version of IBMiUnit but for now we assume and require the OSSILE library.

1. Navigate to the directory where you want to place the new IBMiUnit folder on the i Series
2. git clone https://github.com/MarinaSchwenk/IBMiUnit.git
3. Open QShell in the IBMiUnit folder
4. Run the build script; there are 6 optional parameters:

• -l <obj-lib> (that's a letter "L") install IBMiUnit to the specified library; default is IBMIUNIT
• -s <src-lib> copy source to the given library; default is to leave the source on the IFS and compile from there
• -o <obj-owner> the user profile that will own the new objects; default is QPGMR
• -f copy the obj-lib back into the repository as a save file; this is only useful to the repository contributors
• -t compile the test suite over IBMiUnit
• -v verbose output; this may be helpful or necessary when errors are encountered

You can keep up-to-date with IBMiUnit by pulling from the repository and re-building.

From Save File (part 1)

1. Create a save file on the IBM i, i.e. CRTSAVF FILE(xxx/IBMIUNIT)
2. Download IBMIUNIT.SAVF from the IBMiUnit repository
3. Choose one of the transfer options, then continue to part 2

Transfer Using CPYFRMSTMF

1. Copy the downloaded IBMIUNIT.SAVF to the IFS
2. Copy from the IFS to the *SAVF, i.e. CPYFRMSTMF FROMSTMF('/path/to/file/IBMIUNIT.SAVF') TOMBR('/QSYS.LIB/xxx.LIB/IBMIUNIT.FILE') MBROPT(*REPLACE) CVTDTA(*NONE) ENDLINFMT(*FIXED) TABEXPN(*NO)

Transfer Using FTP

1. Go to a command window on your PC
2. Go to the location on the PC where IBMIUNIT.SAVF is located
3. Enter one of the following: ftp (ibmi_ip_address) or ftp (ibmi_name)
4. Enter your IBM i username and password for that system when prompted
5. Ensure the transfer mode is binary (there will be no conversion) with bin
6. Go to the library on the IBM i where the save file is stored using something like cd /QSYS.LIB/xxx.LIB
7. Transfer the save file from the PC to the empty save file on your IBM i with put IBMiUnit.savf IBMiUnit.savf
8. When the transfer is complete, exit FTP with quit
9. Close the MS-DOS shell with exit

From Save File (part 2)

1. Create the library for the objects, i.e. CRTLIB yyy
2. Restore from the *SAVF, i.e. RSTLIB SAVLIB(IBMIUNIT) DEV(*SAVF) SAVF(xxx/IBMIUNIT) RSTLIB(yyy) MBROPT(*ALL) ALWOBJDIF(*ALL)

Examples

Program Source

ctl-opt bndDir( 'IBMIUNIT/IBMIUNIT' );

/copy IBMiUnit/QRPGLESRC,IBMiUnit_H

// test initialization/registration

IBMiUnit_setupSuite( 'TextUtil Tests' );

IBMiUnit_addTestCase( %pAddr( toUpperCase_fromLower ) : 'toUpperCase_fromLower' );

IBMiUnit_teardownSuite();
return;

// test cases

dcl-proc toUpperCase_fromLower;

   assertCharEquals( 'MARINA SCHWENK'
                   : toUpperCase( 'marina schwenk' ) // defined in service program
                   );

end-proc;

Running

A successful test example:

> ibmiunit/runtest qtehdr_t
  All 2 tests ran successfully

A test with a failure:

> ibmiunit/runtest qtehdr_t                                             
  assertion failure in calculateSurcharges_changeOrder: Number of tariff
    items expected:<1> but was:<2>                                      
  Done: 0 errors, 1 failures, 1 successful test(s)

FAQ

1. What version of IBMi OS does IBMiUnit Support? As of 2025 we still go back to V7r3. However moving forwards, any enhancements will be for V7R4 and above.

2. When will there be a GUI version? The plan has always been to integrate IBMiUnit into RDi or as of the last couple of years, VsCode. However this process takes time and we do not have a ETA on the extension for vsCode yet.

3. How hard is it to pivot to unit testing? Unit testing is part of the test driven development paradymn. However you do not have to implement every piece of that paradymn and can pick up unit testing pretty quickly.

4. Can you unit test subfiles? No, as of right now we dont have support for validating subfiles and including them into the framework.

5. Can I unit test existing RPG programs. Technically yes, however that does not fit the true unit testing paradymn. The process of unit testing is to take small pieces and test them individually. Service program procedures fits beautifully for this task, however you can just take straight logic and unit test those pieces. For example

   ctl-opt bndDir( 'IBMIUNIT/IBMIUNIT' );

   /copy IBMiUnit/QRPGLESRC,IBMiUnit_H

   // test initialization/registration

   IBMiUnit_setupSuite( 'TextUtil Tests' );

   IBMiUnit_addTestCase( %pAddr( myLogic) : 'myLogic' );

   IBMiUnit_teardownSuite(); return;

   // test cases

   dcl-proc myLogic;

    dcl-s myString  varchar( 50 ) inz( 'Testing plain logic' ); 
    
   assertCharEquals( 'Testing'
                   : %subst( myString, 1 7  )
                   );
   

   end-proc;

6. Do I need a special compile command for the unit test programs? No, IBMiUnit uses the standard compile commands and don't need anything special.