Using Total Test Unit Test

Because most mainframe development is not green field development, the first step in working with Total Test will be executing a program in question under control of the Code Debug. During the debugging session, Code Debug and Total Test allows you to record individual test cases. One such test case, in the sense of Total Test, is one execution of a program (compile unit) from beginning (PROCEDURE DIVISION or ENTRY point) to end (GOBACK). It consists of:

Input values as recorded at program ENTRY
Output values as recorded at program exit (e.g. GOBACK)
Assertions for the recorded output values
Stubs (simulated data) for:
- Sub-program calls
- File I/O, i.e. QSAM or VSAM reads and writes
- DB2 SQL statement execution
  - Host variables
  - Column values
  - SQLCODE, SQLSTATE
- IMS DL/I calls
  - PCB/ACB before and after each call (incl. IMS STATUS-CODE)
  - Segment Search Argument (SSA)
  - Segment data
Any write stub will also create assertions for the data written to the external data source

Using Total Test to record test cases

This section describes how to record a test case.

Preparing to record

The prerequisites for recording are as follows:

Install and setup the required software.
Install Workbench for Eclipse.
Find a simple batch program for the first test case.
In Eclipse, open the Code Debug perspective.
Select Run>Debug Configurations....

The following figure displays the Debug Configurations screen.
Select the required program to debug from the right pane, and click Debug.

Recording the test case

Perform the following steps to record the test case.

Record the test case using the Code Debug launch configuration.
Right click on PROCEDURE DIVISION USING, and select Record Test Case....
Select a new or existing project for recording results from the Record Test Case dialog, and click OK.
The Unit Test Options tab enables you to modify the settings for the creation of stub data during recording. The defaults will enable recording of any type of stub, if needed. Under normal conditions, the defaults should be sufficient to run a successful recording.
In rare situations, the maximum number of records for a given stub may be breached during recording. In such a situation, we recommend reducing the amount of data to be processed by your program before recording, rather than increasing the maximum number of stub records to be created.

Viewing the results

To view the results, execute the test case and see the result.

Structuring tests

Total Test allows storing one or more test cases for one or more programs within one project. It is a good practice, though, to create one Total Test project per program. These projects allow grouping test cases into different folders and scenarios (for example, by major program branch being executed) and to define and use test suites to execute all test scenarios in a single run. When it comes to storing Total Test projects in, for example Git repositories, the recommendation is to create one repository per application, containing sub-projects per program.

Naming conventions

In order to “map” Total Test projects, folders and scenarios and program components, naming conventions are recommended. There is a form of integration between Code Pipeline and Total Test allowing automatic identification of test scenarios “related” to a program, without having to follow a naming convention. Having such a naming standard in place will support users in identifying the target component of a given scenario without any additional “guesswork”. This will simplify work for the developers and other users drastically.

Such naming standards should be followed when recording the tests. However, asset names can be changed at a later stage (for example, after recording).

The examples presented here use the following naming conventions:

The Total Test project name uses <Target_Program_Name>_Unit_Tests as project name.
The test scenario files or test suite files contain the <Target_Program_Name> as first part of their file name, followed by an underscore _, followed by any trailing name.
Total Test itself requires the file extensions:
- .testscenario for test scenarios
- .testsuite for test suites

Total Test project structure

A Total Test project will use the following folder structure, which will be generated and populated automatically, when the first test case gets recorded by Code Debug/Total Test:

<project_name>(root)                            # e.g. <Target_Program_Name>_Unit_Tests
+- Unit Tests
   +- Interfaces                               # interfaces to programs (LINKAGE SECTION) and I/O stubs
   +- JCL                                      # jcl 'members' for the execution of tests
   +- Scenarios                                # test scenarios
   +- Structures                               # COBOL structures (01-levels and sub-fields) making up the different interfaces
   +- Stubs                                    # Simulation data for sub-programs and external I/O
   +- Suites                                   # test suite(s) executing one or more test scenarios

Test execution JCL

When using Code Debug/ Total Test to record test cases, the JCL folder will be empty. Use of this folder has been deprecated and the folder is being retained for exceptional situations.

Instead – depending on your configuration of Total Test, the execution JCL may:

Either be stored centrally in the Total Test Repository
Or each user has defined their local TotalTestConfiguration project.

The examples documented here make use of the former option. Therefore, specifying the location of the execution JCL is not necessary.

Due to the design of the example application, there are three paths through the development stages. Therefore, there will be the need for different STEPLIB concatenations to use during test execution.

To accomplish this, the example makes use of Total Test’s context variables. These allow defining variables within, for example the execution JCL, and setting the actual values for these variables at execution time via the Total Test pipeline step parameters.

Total Test already supports switching between load library names at execution time. For this to work, the standard template for the execution JCL, generated by Total Test on first use, uses the variable reference ${loadlibraries} in the STEPLIB concatenation.

UsingTTUnitTest_execution jcl skeleton.png

When executing a test scenario, this value can be modified using the load libraries tab in the context dialog.

The example takes this one step further by using a load library name, which itself contains variables.

These variables need to be resolved in the Context Variables tab for the execution to be successful. The advantage is that at execution time in the pipeline, these context variables can be set via the contextVariables parameter for the pipeline step.

UsingTTUnitTest_pipeline code snippet.png

Adding new test cases

New test cases may be added to an existing test scenario by duplicating existing test cases and modifying the input and assertion data (based on any new requirements). Refer to the Total Test online help for more details.

Storing the Total Test project in Git or GitHub

The recommended procedure to share Total Test projects across teams and to use them in automation pipelines is by storing these projects in Git or GitHub repositories.