IBM Test Accelerator for Z Early Development Testing

IBM TAZ Early Development Testing VS Code extension enables the creation and execution of unit tests that can run without middleware for COBOL v6.2+ applications running in CICS, IMS TM, or Batch. Data recording and the running of unit tests are powered by the Dynamic Test Engine, which is part of z/OS Debugger. As the program-under-test executes, mocked data for each Test Point is inserted into the application to replicate external data sources. Mocked values allow the program-under-test to be isolated from real external data sources like CICS, IMS, or Db2.

Table of contents

• Key Concepts
• Prerequisites
• Setup
• Recording program data
• Creating unit tests
• Test assertions and mocks
• Running tests
• Running tests with code coverage

Key Concepts

Test Points: Locations in your COBOL program where external data sources (CICS, IMS, Db2) are accessed. During test execution, the Dynamic Test Engine intercepts these calls and provides mocked data instead of requiring real external systems.

File Types:

• Recording file (.rec): Binary file created during the recording session that captures program execution data
• Test data file (.zdata): JSON file derived from the .rec file when you create a unit test. Contains the mocked data for Test Points
• Test case file (.ztest): YAML file that defines one or more unit tests and references a test data file via the dataFilePath property

Mocked Data: Data inserted at each Test Point during test execution to replicate external data sources. This allows your program to run in isolation without requiring CICS, IMS, or Db2. The mocked data is what was originally captured from the external source during recording.

Assertions: Validations that compare actual program data at Test Points against expected values from the test data file (.zdata). Test failures indicate mismatches where the program behavior differs from what was recorded.

For more details, see the TAZ Concept documentation.

Prerequisites

Host dependencies

• Host z/OS Debugger version 17.0.4 or above
• RSE API version 1.2.4 and above

Client dependencies

• Install IBM Developer for z/OS Enterprise Edition (IDzEE) Extension Pack from VS Code marketplace
• Recommended: Install the YAML Language Support by Red Hat extension. This is needed to parse YAML files and see YAML file syntax errors.
• Configure RSE connection

For full details, see TAZ documentation.

Setup

Setting up Zowe profiles

Before recording or running tests, configure the required Zowe profiles in a team configuration file (zowe.config.json).

Creating the team configuration file

1. Open the Zowe Explorer view in VS Code
2. Click the Add profile... (plus button) in the Data Sets, USS, or Jobs view
3. Click Create a new Team Configuration file
4. Choose the scope:
   • Global: File accessible in any project (~/.zowe/zowe.config.json)
   • Project: File accessible only in current Git project (zowe.config.user.json in repo)

The team configuration file is created with default values and RSE profile template (since Z Open Editor is installed).

Configuring profiles

Edit the zowe.config.json file to add your connection details. You can hover over each JSON key for explanations. Contact your system administrator to obtain the correct port numbers and connection details for your z/OS system.

1. RSE Profile (Required for z/OS connection. z/OSMF profile can also be used):

For more information about RSE profiles, see the RSE API documentation.

"profiles": {
  "rse-vm1": {
    "type": "rse",
    "properties": {
      "host": "yourZmachine.yourCompany.com",
      "port": 6800,
      "basePath": "rseapi",
      "protocol": "https",
      "rejectUnauthorized": false
    },
    "secure": ["user", "password"]
  }
}

2. IBM Z Open Debug Profile (required to connect to Debug Engine for recording and running tests):

For more information about debug profiles, see the Debug profile documentation.

"zOpenDebug": {
  "type": "zOpenDebug",
  "properties": {
    "host": "yourZmachine.yourCompany.com",
    "dpsPort": 8143,
    "dpsContextRoot": "api/v1",
    "dpsSecured": true,
    "rdsPort": 8002,
    "rdsSecured": true,
    "rejectUnauthorized": false,
    "uuid": "eb56ad6a-38b8-4e2f-bad3-10fc1530ea9f"
  },
  "secure": ["user", "password"]
}

Verifying connection

Use Zowe Explorer to verify your connection by browsing z/OS Unix files or MVS data sets. You'll be prompted for credentials, which are stored securely (e.g., Keychain on macOS). Secure credentials will appear as "secure": ["user", "password"] in the zowe.config.json file.

In addition, you can verify RSE API access via browser: https://yourZmachine.yourCompany.com:6800/rseapi/api-docs/

Use z/OS Debugger profiles in the Zowe Explorer section to verify the Debug profile can connect.

For detailed setup instructions, see TAZ documentation.

Setting up a test ZAPP profile

A ZAPP profile of type test is required for running unit tests. Create a zapp.yaml file at the root of your workspace. For more information about ZAPP profiles, see the ZAPP documentation.

Minimal example (required fields only):

name: my-application
description: Unit test configuration
version: 1.0.0
author:
  name: Your Name

profiles:
  - name: myApp-test
    type: test
    settings:
      unitTest:
        procLib:
          - CUST.V70.PROCLIB # Required: Procedure libraries
        userLibraries:
          - IBMUSER.LOAD.LIB # Application load libraries

Advanced example with recording and allocation settings:

name: my-application
description: Copybooks and unit test setup
version: 3.0.0
author:
  name: IBM CORPORATION

profiles:
  - name: myApp-test-advanced
    type: test
    settings:
      recording:
        sourceMaps: # Define source maps if your program ID and module names are different
          - source: /my/local/program/PROG.cbl
          - module: ModuleName
        applicationToCapture: # ZAPP profile can hold information to record program data
          recordingType: Batch
          jclSteps: /my/local/program/PROG.cbl
        hostRecordingSettings:
          dteEngineLocation: YOUR.DTE.SEQAMOD # Contact your system administrator for the correct DTE dataset name
      unitTest:
        procLib:
          - CUST.V70.PROCLIB
        userLibraries:
          - IBMUSER.LOAD.LIB
          - IBMUSER.LOAD.LIB2

Key properties:

• procLib (required): List of z/OS procedure libraries for test execution
• userLibraries: Data sets containing the program-under-test binaries. During a test run, the Engine will search through these data sets to find the program binaries.
• sourceMaps: Specify which application load modules correspond to application source files.

Creating unit tests

• Right-click on a COBOL source program and choose "Test Accelerator for Z" > "Create unit test". A test creation form will open. Choose a program type: Batch, CICS, or IMS. The form will guide you through recording data for your program type. Alternatively, you can choose an existing recording to create tests. Once program data recording is complete, a test case will be automatically created.

• Open the Testing tab in VS Code. Depending on the data, there will be one or more unit tests in your test case file (.ztest). Each unit test represents one invocation of the program during recording. If your program was called 5 times during the recording session, 5 unit tests will be generated. Each unit test has a programIndex property: programIndex: 1 means this is the first invocation of the program in your test data file (.zdata).

• You can choose to remove unit tests. Make sure you use the proper "programIndex" to identify a program call from the test data file (.zdata).

Below is an example of a test case with 2 unit tests:

dataFilePath: taz-unit-test/lgucdb01-andre-demo.zdata
name: lgucdb01-test-case
description: Unit test for LGUCDB01
sourcePath: base/src/cobol/lgucdb01.cbl
program: LGUCDB01
version: 1.0.1
unitTests:
  - name: add-auto-policy
    programIndex: 1
    description: Default assertions to unit test program inputs and outputs
    validate:
      - PROGRAM
  - name: remove-auto-policy
    programIndex: 2
    description: Default assertions to unit test program inputs and outputs
    validate:
      - PROGRAM

Test assertions and mocks

Once your test is generated, it will appear in the VS Code Test Explorer.

• Expand the test case to see each unit test.

• Right-click on a unit test and select "Show test points explorer".

• This will open a view where each Test Point is displayed in order of execution.

• Click on a test point to open the Test Data Editor view showing the data with which the program executed. Use the data editor to enable or disable assertions and modify mocked data.

• To modify data, toggle "Assert enabled variables in test point occurrence" on in the data editor. You can then modify the expected values (assertions) or the mocked data that will be provided during test execution.

• When test points are enabled/disabled or test point data is modified, both .ztest and .zdata artifacts will update. Make sure to save both .ztest and .zdata artifacts to your repository.

Running tests

1. Open the Testing view in VS Code (beaker icon in the Activity Bar).
2. Hover over a unit test or test case and click the play button to run tests.
3. The extension uploads necessary artifacts to z/OS and runs unit tests via the Dynamic Test Engine.
4. The Dynamic Test Engine runs the program under test with the recorded mock data.
5. Test results appear in the standard TEST RESULT console.
6. Click on each individual result to see detailed results.
7. Tests fail if there are assertion mismatches, meaning the actual program data at a Test Point differs from the expected values in the test data file (.zdata). This indicates the program behavior has changed from what was recorded.

For information about running tests with code coverage, see Running tests with code coverage.

Running tests with code coverage

1. Install IBM Compiled Code Coverage extension to view code coverage reports (included in IBM Developer for z/OS Enterprise Edition Extension Pack).
2. Open the Testing view in VS Code (beaker icon in the Activity Bar).
3. Hover over a unit test or test case.
4. Click the play button with a checkmark icon to run tests with code coverage enabled.
5. The extension automatically opens the code coverage report when the test run completes.