Skip to content
Code for IBM i Docs

Configuring Tests

Compile Configuration

The process of defining how to compile your tests is greatly simplified using a configuration file called testing.json. This file allows you to specify the parameters for the RPGUnit compile commands (RUCRTRPG and RUCRTCBL) and the code coverage command (CODECOV) in JSON format. The scope in which these parameters are applied is determined by the location of the testing.json file and depends on whether you are working with local files or source members.

Local Files

The following hierarchy is used to determine the configuration for local files:

  • <directory>/testing.json: This is a directory level configuration file that will apply to all tests in that directory.
  • .vscode/testing.json: This is a global configuration file that will apply to all tests in that project. Parameters not set at the directory level will be inherited from this global configuration.

Shown below is an example of a project structure with the testing.json file at the global and directory level:

  • Directorymy-project
    • Directory.vscode
      • testing.json Global configuration
    • Directoryqsqlsrc
      • employee.sql
    • Directoryqrpglesrc
      • utilsA.rpgle
      • utilsB.rpgle
      • employee.rpgle
    • Directoryqtestsrc
      • Directoryutils
        • testing.json Directory level configuration
        • utilsA.test.rpgle
        • utilsB.test.rpgle
      • employee.test.rpgle

Source Members

The following hierarchy is used to determine the configuration for source members:

  • <sourceFile>/testing.json: This is a source file level configuration file that will apply to all tests in that source file.
  • VSCODE.FILE/testing.json: This is a global configuration file that will apply to all tests in that library. Parameters not set at the source file level will be inherited from this global configuration.

Shown below is an example of a project structure with the testing.json file at the global and source file level:

  • DirectoryMYUSER.LIB
    • DirectoryVSCODE.FILE
      • TESTING.JSON Global configuration
    • DirectoryQSQLSRC.FILE
      • EMPLOYEE.SQL
    • DirectoryQRPGLESRC.FILE
      • EMPLOYEE.RPGLE
      • UTILSA.RPGLE
      • UTILSB.RPGLE
    • DirectoryQTESTSRC.FILE
      • EMPLOYEE_T.RPGLE
    • DirectoryUTILTESTS.FILE
      • TESTING.JSON Source file level configuration
      • UTILSA_T.RPGLE
      • UTILSB_T.RPGLE

Default Configuration

Use the following steps to create a default configuration for your project:

  1. Create a testing.json file or source member in the desired location.
  2. Press Ctrl+Space and select the IBM i Testing Configuration option to generate the default configuration: 
    {
        "rpgunit": {
            "rucrtrpg": {
                "tgtCcsid": "*JOB",
                "dbgView": "*SOURCE",
                "rpgPpOpt": "*LVL2",
                "cOption": [
                    "*EVENTF"
                ]
            },
            "rucrtcbl": {
                "tgtCcsid": "*JOB",
                "dbgView": "*SOURCE",
                "cOption": [
                    "*EVENTF"
                ]
            },
            "rucalltst": {
                "order": "*API",
                "libl": "*CURRENT",
                "jobD": "*DFT",
                "detail": "*BASIC",
                "output": "*ALLWAYS",
                "rclRsc": "*NO",
                "onFailure": "*ABORT"
            }
        },
        "codecov": {
            "module": []
        }
    }
  3. Use Ctrl+Space within any of the commands to see the available parameters and their descriptions.

Execution Configuration

When it comes time to executing the tests, the extension essentially runs the RUCALLTST command provided by RPGUnit. The parameters for this command modify how the tests are executed, such as the order to run the tests and whether to reclaim resources after each test case. These parameters can be configured in the either the VS Code settings or in the testing.json configuration file.

VS Code Settings

Configuring the execution parameters via the VS Code settings is the suggested option if you prefer to treat these parameters as preferences that will allow each developer to configure for how tests are executed. These settings can be found by going to the extension’s settings and searching for IBM i Testing (from Run Order to Reclaim Resources).

Configuration File

The alternative option is to configure the execution parameters in the testing.json configuration file (the same one used for compile command configuration). This is useful if you want to enforce specific execution parameters to be used by all developers working on a project.

Here is an example with all execution parameters set in the testing.json file:

{
    "rpgunit": {
        "rucalltst": {
            "order": "*API",
            "libl": "*CURRENT",
            "jobD": "*DFT",
            "detail": "*BASIC",
            "output": "*ALLWAYS",
            "rclRsc": "*NO",
            "onFailure": "*ABORT"
        }
    }
}

Compile, Execution, and Coverage Parameters

ParameterNameDescriptionDefault
tstPgmTest programSpecifies the name of the test program (*SRVPGM) to create. By default, this will be set to &OPENLIB/&OPENMBR for source members and &CURLIB/&SHORTNAME for local files.
srcFileSource fileSpecifies the name of the source file containing a member with the same name as TSTPGM. By default, this will be set to &OPENLIB/&OPENSPF for source members.
srcMbrSource memberSpecifies the name of the member containing the source code to be compiled. By default, this will be set to &OPENMBR for source members.
srcStmfSource stream fileSpecifies the path name of the stream file containing the source code to be compiled. By default, this will be set to &FULLPATH for local files.
textText descriptionAllows you to enter text that briefly describes the RPGUnit test case and its function.
cOptionCompile optionsRefer to the OPTION parameter in CRTRPGMOD command help.*EVENTF
dbgViewDebugging viewsRefer to the DBGVIEW parameter in CRTRPGMOD command help.*SOURCE
bndSrvPgmBind service programRefer to the BNDSRVPGM parameter in CRTSRVPGM command help.
bndDirBinding directoryRefer to the BNDDIR parameter in CRTSRVPGM command help.
bOptionBinding optionsRefer to the OPTION parameter in CRTSRVPGM command help.
defineDefine condition namesSpecifies condition names that are defined before the compilation begins. Using the parameter DEFINE(condition-name) is equivalent to coding the /DEFINE condition-name directive on the first line of the source file.
dltSplfDelete spooled filesSpecifies if all spooled files (compile listing) created by the object creations commands are deleted on success.
actGrpActivation groupRefer to the ACTGRP parameter in CRTSRVPGM command help.
moduleModuleRefer to the MODULE parameter in CRTSRVPGM command help.
rpgPpOptPre-compiler RPGPPOPTRefer to the RPGPPOPT parameter in CRTSRVPGM command.*LVL2
pOptionPre-compiler OPTIONSRefer to the OPTION parameter in CRTSQLRPGI command help.
compileOptPre-Compiler COMPILEOPTRefer to the COMPILEOPT parameter in CRTSQLRPGI command help.
tgtRlsTarget releaseRefer to the TGTRLS parameter in CRTSRVPGM command help.
incDirInclude directorySpecifies one or more directories to add to the search path used by the compiler to find copy files. The compiler will search the directories specified here if the copy files in the source program can not be resolved.
tgtCcsidTarget CCSIDSpecifies the CCSID that the compiler uses to read the source files.*JOB
wrapperCmdWrapper CommandSpecifies a custom command to wrap the RUCRTRPG command.

Advanced Configuration

Some compile and execution configuration parameters (TSTPGM, SRCFILE, SRCMBR, SRCSTMF) are special because the extension typically manages and sets them for you. This is because they can be determined by the extension based on what tests are being compiled and executed. However, to provide maximum flexibility in configuring even these parameters, users can still do so via the testing.json file. A simple use case could be that you want to build your source member tests into your current library instead of the library containing the source.

Under the covers, the extension has default values for these special parameters along with supported variables based on whether you are working with local files or source members. The defaults below can be overwritten in the testing.json file:

{
    "rpgunit": {
        "rucrtrpg": {
            "tstPgm": "&OPENLIB/&OPENMBR",
            "srcFile": "&OPENLIB/&OPENSPF",
            "srcMbr": "&OPENMBR"
        },
        "rucalltst": {
            "tstPgm": "&OPENLIB/&OPENMBR"
        }
    }
}

Supported Variables:

  • &CURLIB: Current library, changeable in the Library List
  • &OPENLIB: Library name where the test source member lives
  • &OPENSPF: Source file name where the test source member lives
  • &OPENMBR: Name of the test source member

Vendor Integration

The wrapperCmd parameter in the RUCRTRPG/RUCRTCBL/RUCALLTST specifications are not actual parameters of the RPGUnit commands, but rather are provided by the extension to allow wrappering them. This is primarily used when integrating RPGUnit with other vendor tools.

Example testing.json configuration:

{
  "rpgunit": {
      "rucrtrpg": {
          "tgtCcsid": "*JOB",
          "dbgView": "*SOURCE",
          "cOption": [
              "*EVENTF"
          ],
          "wrapperCmd": {
              "cmd": "MYLIB/MYCMD TSTCMD",
              "params": {
                  "desc": "My description"
              }
          }
      },
      "rucalltst": {
          "wrapperCmd": {
              "cmd": "MYLIB/MYCMD CALLCMD",
              "params": {
                  "desc": "My description"
              }
          }
      }
  }
}

Compile Command:

MYLIB/MYCMD TSTCMD(RPGUNIT/RUCRTRPG TSTPGM(MYUSER/TEMPDET)
SRCSTMF('/home/MYUSER/builds/ibmi-company_system/qtestsrc/empdet.test.sqlrpgle')
TGTCCSID(*JOB) DBGVIEW(*SOURCE) COPTION(*EVENTF) RPGPPOPT(*LVL2)
INCDIR('''/home/MYUSER/builds/ibmi-company_system''')) DESC('My description')

Execution Command:

MYLIB/MYCMD CALLCMD(RPGUNIT/RUCALLTST TSTPGM(MYUSER/TEMPDET) ORDER(*REVERSE)
DETAIL(*ALL) OUTPUT(*ALLWAYS) LIBL(*CURRENT) JOBD(*DFT) RCLRSC(*NO)
XMLSTMF('/tmp/testing/vscode-ibmi-testing/RPGUNIT/TEMPDET_1751646914682.xml'))
DESC('My description')