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 is 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 will be inserted into the application to replicate the external data sources. Mocked values allow the program-under-test to be isolated from requiring 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):

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"]
  }
}

Verify RSE API access via browser: https://yourZmachine.yourCompany.com:6800/rseapi/api-docs/

2. IBM Z Open Debug Profile (required to connect to Debug Engine for recording and running of 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"]
}

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 info 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 datasets to find the program binaries.
• sourceMaps: Specify which application load modules correspond to application source files.

Verifying connection

Use Zowe Explorer to verify your connection by browsing z/OS Unix files or MVS datasets. 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.

For detailed setup instructions, see TAZ documentation.

Recording program data

In order to create a unit test, you will need program mock data. A unit test will run one individual program in isolation.

Right-click on the source of a COBOL program in VS Code's explorer section and choose "Test Accelerator for Z" > "Record program data". Follow the quick-pick flow and enter recording information. See full documentation for more detail: https://www.ibm.com/docs/en/test-accelerator-for-z/2.x?topic=testing-early-development-vs-code

After successful recording, the extension will automatically download a recording file with a .rec extension. When you create a unit test from this recording, it will be converted to a test data file (.zdata) that contains the mocked data.

Creating unit tests

• Right-click on the source of a COBOL program and choose "Test Accelerator for Z" > "Create unit test". The extension will search through all recording files with a .rec extension in your local workspace.

• Choose a recording file to create your test with.

• Confirm the test name or modify it and press Enter.

• Your test is automatically generated!

• 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 1st invocation of the program in your test data file (.zdata).

• You can choose to remove or duplicate 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 click "Show test points explorer".

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

• Click on a Test Point to open the data editor view showing the captured data values. 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.

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 will upload necessary artifacts to z/OS and run unit tests via the Dynamic Test Engine.
4. The Dynamic Test Engine will run the program under test with the recorded mock data.
5. Test results will show up in the standard TEST RESULT console.
6. Click on each individual result to see detailed results.
7. Tests will 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 will automatically open the code coverage report when the test run completes.