Concept

Unit test artifacts

Unit tests virtualize external subsystem calls, allowing z/OS programs to be tested without requiring CICS, IMS, Db2, or other external file artifacts. Early development testing uses three types of artifacts to create and execute unit tests:

Recording file (.rec extension): A binary file that contains data captured by the Dynamic Test Engine during real execution of one or more programs on z/OS. Recording files are created with the Record program data action or by the Data Collector Service and downloaded by the Data Collector View. Recording files are used as input when creating tests with the Create new unit test action. You can rename or reorganize recordings in the workspace to clarify their content or purpose. Deleting a recording does not affect any test files created from it.
Test case file (.ztest extension): A YAML file that defines one or more unit tests for a single program under test that use a common data file. Test case files are created with the Create new unit test action. The test case file (.ztest) is associated one-to-one with a test data file (.zdata). If you copy a test case file, you must also copy the test data file and update the dataFilePath property in the test case file to point to the new test data file.
Test data file (.zdata extension): A JSON file that is generated from a recording file when a test case is created. Any changes made to a test case using the Test Data Editor UI are automatically reflected in the associated test data file. Each test case has a one-to-one association with a test data file. If you copy a test case file, you must also copy its corresponding test data file and update the dataFilePath property in the test case file to point to the new test data file.

Mocks and assertions

During test execution, the Dynamic Test Engine intercepts program statements that access external data sources and uses mocks and assertions to validate program behavior:

Test points: Locations where the program makes external resource call statements. The Dynamic Test Engine intercepts all program statements that access external data sources at these test points.
Assertions: Validations of program data performed at each test point to verify whether the program under test is working as expected. Assertions compare the actual values of the variables in the program under test at each test point with expected values recorded in the unit test. Mismatches in these value comparisons indicate that the behavior of the program under test does not match the expected behavior as defined by the unit test. For most test points, the data used for assertions is what was originally captured by the Dynamic Test Engine as inputs passed to the external data source of the test point. The exception is the test point for the program under test, where the data is what is returned by the program under test.
Mocked data: Data inserted into the application at each test point to replicate external data sources. Mocked values allow the program under test to be isolated from requiring real external data sources like CICS, IMS, or Db2. For most test points, the mocked data is what the Dynamic Test Engine captured as being returned from the original external data source. The exception is the test point for the program under test, where the mocked data is what was originally passed to the program under test. Early development testing allows editing of the expected values of assertions or mocked data to change the behavior of the test.

Test file properties

Test case files (.ztest) contain the following properties that define unit test behavior:

version

The test file format or schema version. Whenever new fields are added to the test case schema, the version is incremented accordingly. The current schema version is 1.0.1.

name

A short name for the test file. The original name automatically assigned when the test was created may be changed to something more meaningful.

description

A summary for the test file.

program

Program ID or entry name for all unit tests in a .ztest file. This is set when the test file was created.

sourcePath

Relative workspace path to the source file from which the .ztest file was created.

dataFilePath

Relative workspace path to the test data file used by unit tests in .ztest file. Test data files must not be shared by different test files. If you copy a test file to create a new test file, also copy the test data file and update this property.

testPointDefinitions

Named definitions of test points common across all unit tests in the test file. These are referenced by name in the unitTest.testPointOccurrences properties. If the name is changed in one location, it must also be updated in the other.

name: The name of the test point. A more meaningful name than the one auto-generated by early development testing may help easily identify a test point. If the name is changed, references in all unitTest.testPointOccurrences sections must be updated.
dataID: The data ID that the early development testing extension generates for internal use. Do not change this value.
resolvedSourceID: The source ID that the early development testing extension generates for internal use. Do not change this value.

unitTests

The unit tests in the test file. All unit tests target the same program and use the same test data file (dataFilePath).

name

A meaningful name for the unit test.

description

A summary for the unit test.

programIndex

The test data file can have multiple invocations of the program under test being executed. This property specifies which invocation from the test data file is used for this unit test. Starts at 1, default is 1.

validate

The Dynamic Test Engine can validate (assert) test point inputs state before a test point is executed. This property is an array that sets the default types of test points that are enabled for this validation. The default may be overridden for individual test point occurrences. Types of test points are:

PROGRAM for the program under test
CICS for EXEC CICS statements
IMS for IMS calls
SQL for EXEC SQL
CALL for calls other than IMS
FILE for file I/O

The special values ALL and NONE may also be used as synonyms for all of the types or none, respectively, but if used should be the only element in the array. The default is PROGRAM.

testPointOccurrences

List of occurrences of test points from the test data, identified by name and occurrence number.

name

The name of a test point defined in the testPointDefinitions property. If the name is changed there, it must also be updated here.

occurrence

The program under test may execute a test point multiple times. This property specifies which execution this test point occurrence refers to. Starts at 1, default is 1.

enabled

If true, the Dynamic Test Engine checks that the runtime values match the captured data or data supplied in the assertions property, if present. If false, it does not. If not present, the behavior is determined by the validate property.

assertions

Before the Dynamic Test Engine executes a test point, it can validate (assert) that the runtime values in the test match the values provided in this array. If the values are not specified here, they are compared to the data captured in the test data file.

name: The name of a test point input variable or data item to be validated (asserted).
enabled: If assertions are enabled for the test point occurrence, this property can be set to false to exclude the data item from the validation.
value: The updated value that the Dynamic Test Engine should validate (assert) instead of what was captured in the test data file.
type: The data type of the value, one of string or hex (default: string). String values are in UTF-8 but are interpreted according to the variable type. Hexadecimal values are characters in the range "0" to "9" and "A" to "F", inclusive, where two hexadecimal digits represent one byte, and the number of bytes must match the size of the data item.
redefines: The name of a data item being redefined if this data item redefines another.
fields: For group items, this property contains an array of any modified subordinate data items.

mocks

When the Dynamic Test Engine executes a test point, it uses the data captured in the test data file as the data returned unless overridden by this parameter.

name: The name of a test point output variable or data item to be modified.
value: The updated value that the Dynamic Test Engine should return instead of what was captured in the test data file.
type: The data type of the value, one of string or hex (default: string). String values are in UTF-8 but are interpreted according to the variable type. Hexadecimal values are characters in the range "0" to "9" and "A" to "F", inclusive, where two hexadecimal digits represent one byte, and the number of bytes must match the size of the data item.
redefines: The name of a data item being redefined if this data item redefines another.
fields: For group items, this property contains an array of any modified subordinate data items.