DevOps Unit Testing with COBOL ADFz/IDz

1

zUnit – Unit Testing with COBOLADFz/IDzVersions 9.5 ➔ 14.1.5

February, 2019

Jon Sayles / IBM - [email protected]

DevOps

mailto:[email protected]

2

IBM Trademarks and Copyrights

© Copyright IBM Corporation 2016, 2017, 2018, 2019. All rights reserved.

The information contained in these materials is provided for informational purposes only, and is provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, these materials. Nothing contained in these materials is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in these materials to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates.

This information is based on current IBM product plans and strategy, which are subject to change by IBM without notice. Product release dates and/or capabilities referenced in these materials may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way.

IBM, the IBM logo, the on-demand business logo, Rational, the Rational logo, and other IBM Rational products and services are trademarks or registered trademarks of the International Business Machines Corporation, in the United States, other countries or both. Other company, product, or service names may be trademarks or service marks of others.

3

Course Contributing Authors

Thanks to the following individuals, for assisting with the materials in this course:

Satoko Yoshida – IBM/IDz Senior Developer

Crystal Zinn – IBM/IDz Senior Developer

Bill Alexander – IBM/IDz Development Lead

Reginaldo Barosa – IBM Client Technical Professional

Zvi Weiss – IBM Client Technical Professional

Mark Boyd – IBM Client Technical Professional

4

IBM Doc for zUnit

http://www-01.ibm.com/support/knowledgecenter/SSQ2R2_9.5.0/com.ibm.etools.IDz.zunit.doc/topics/c_zunit_overview.html

http://www-01.ibm.com/support/knowledgecenter/SSQ2R2_9.5.0/com.ibm.etools.rdz.zunit.doc/topics/c_zunit_overview.html

5

Prerequisites for zUnit Workshops

IDz Software Environment:• Installed, Configured & Tested RDz v9.5 or IDz v14.1 ➔ v14.1.5

software:

• Client

• Server

• IDz PROC setup complete and tested

zUnit Class Attendee:• Two+ years of z/OS application Development, Maintenance or

Production Support

• Formal IDz training and at least six (6) months of regular IDz

usage

• Production navigation

• Terms & Concepts

• Workspace and Property Groups

6

UNIT zUnit Testing with IDz

▪ zUnit Terms, Vocabulary, Application Support/Limitations

▪ zUnit Development Process and Run-Time Architecture

▪ XML Editor Options

▪ QSAM Data Import

▪ Working with DB2 Programs

▪ Stubbing out Program Calls

▪ Debugging your Test Case

▪ Analyzing Programs for Unit Testing “Fit”

▪ Workshop/Lab Instructions

▪ Appendix

7

What is Unit Testing?Unit Testing is a software testing method by which individual units of source code (sets of one or more computer program modules together with associated control data, and operating procedures) are tested to determine if they are fit for use. Unit testing verifies code according to design specifications – and uncovers application vulnerabilities. . Wikipedia

IDz provides two approaches to Unit Testing:1. White Box Testing – aka “Glass Box” Testing:

• Testing to ensure/validate the internal logic and the interfaces of a software application

• Java: Methods

• Enterprise Application: COBOL Subroutines …and… PL/I External Procedures

2. Black Box Testing

• Traditional enterprise application testing that examines output data or changes to data structures (DB2 tables/IMS DBs, etc.) modified by running programs

• Batch

• Online

http://en.wikipedia.org/wiki/Unit_testing

8

White Box Testing

White-box (Glass-box) testing verifies code according to design specifications and uncovers application vulnerabilities – making them visible to the testers.

An individual unit of software is an isolated logic construct or routine within a call-able program:

• Date validation

• Credit Card number look-up

• Tax computation

• Healthcare Co-pay calculation

With zUnit, White Box testing is done at the “Compilation Unit” level – which is:

• A single program

• Plus all its copybooks – necessary for a clean compile

Compilation Unit == Subroutine

9

zUnit Black Box testing is available for QSAM and VSAM files

Black Box testing is done against a Compilation Unit.

Black Box TestingBlack Box Testing examines the I/O outcome of an application: What the program produces as output data or changes to DB2/IMS datawithout regard to internal program code/logic

10

White Box Testing – Subroutines

Using zUnit you Analyze/Customize LINKAGE SECTION values, then Build and Run the Unit Test• Customized input LINKAGE values test specific functionality within the subroutine

• Output LINKAGE data are compared against defined/expected returned values from the subroutine

• If the expected values match the returned values the test passes. If not the test fails

zUnit subroutine testing allows you to validate specific application functionality as opposed to program file outputs.

During Unit Test your module is run with defined input values.

The subroutine’s zUnit run produces LINKAGE SECTION output values which are compared against the defined expected output values.

The results of these comparisons dictates Unit Test pass/fail return codes.

Man

ipu

late

11

12

JES

zUnit Run-time Architecture & Execution Flow

zUnit Test RunnerDoes the following:

READ AZUCFG(MEMBER)

CALL (invoke) Test Case Which invokes each Test Case Entry

Which interacts with your program’s logic

The generated code:- Sets up unit test variable values - Runs the subprogram

- Evaluates the Assertion outcome- Releases system resources

WRITE AZURES(MEMBER)

//AZUCFG DD DSN=…

• Names the Test Case module(s)

//AZURES DD DSN=…• Stores test results in XML PDS member

//… EXEC PGM=Test Runner//AZUCFG ➔ Test Suite PDS//AZURES ➔ Test Result PDS//AZULOD ➔ Load LibrarySchedules/Launches…

Submit JCL…

Test Case(PDSE)

Load Module to be unit tested

• Verifiable logic routine• Modify LINKAGE SECTION values

during program execution

For each assertion:- Assign Linkage Variables to Assertion values- CALL subroutine using Assertion values- Evaluate outcome

- Did expected values return from subroutine?- Release resources

z/OS

Test Suite

Target SubroutineTest Results

GOBACK ENTRY

13

Current zUnit Support

Subroutine compiled as a z/OS Load Module to a PDS or PDSE:

• COBOL v4, v5 and v6 supported

• Subroutines are Unit Tested through data values passed in LINKAGE

• Passed/Returned values (Assertions) are setup & evaluated by the Test Case

• QSAM/VSAM file I/O is supported in the subprograms

• Programs that contain SQL statements are supported

• But there currently is no support for comparing results of Embedded SQL statements

against expected returns for any SQL DML statement

• Assembler subroutines can be supported using a work-around that creates a COBOL wrapper program for the Assembler Call interface

• Stubbing out called programs is supported

• Saving/Externalizing Test Assertion values is supported

• Support for zUnit testing of COBOL “main” or standalone file processing programs is available as of IDz v14

• File I/O “Black Box update testing” of QSAM and VSAM data sources

• SUPERC dataset comparison is generated by zUnit

• Support for IMS (DB/DC) and for DB2 “result set testing” is in development

14

• Technology Preview - CICS Support

• Recording of CICS data at runtime for use in the Test Case Editor

• Running a CICS test case and user interface changes

• Support for VSAM File I/O and VSAM Test Data Wizard - data file Import

• Previously only supported for QSAM files - VSAM is not supported for PL/I programs

• Support for adding non-numeric data to numeric fields

• Previously type-checking was done during edit, and only valid numerics were allowed into PIC 9 fields

• Now you can dynamically redefine the data for the Test Case, and enter alphabetic values & garbage

• Support for One-Click Generate ➔ Test Case Run for DB2 programs

• Previously DB2 program run had to be run standalone Test Case (the were not part of the wizard cycle)

• Debugging:

• Show test target source first. Test case failures documented with record and field names in SYSPRINT

• Allocate JCL – sample JCL that is used to create the zUnit configuration datasets by running a single batch job

• Recorded runtime data now can be imported from z/OS Debugger to Test Data Entry for unit testing purpose.

• In existing zUnit features, local Enterprise COBOL and Enterprise PL/I sources are supported in scenarios of open source configuration management.

• zUnit identifies a return value parameter of a PL/I Function CALL type sub programs. You can see the return value in the Test Entry Data Editor.

Current zUnit Support – continued

15

Preparation, Steps & Experience – Prerequisites• (IDz Admin)

• IDz v14 – or later installed: Both client & server

• Customized Property Groups are a “best practice”

• (Systems Programming Staff)

• The IDz PROCs must be installed/configured for correct Property Group Build

• This is covered in the IDz Installation guide

• (Application Developers)

• Must create a set of zUnit-specific z/OS Libraries

• Specifics (DCB attributes, SPACE suggestions, etc.) are contained in this course

• Along with quality IDz skills you must have an understanding of both IDz Property Groups and the standard z/OS Build (Compile/Link) process

• This is because while using the zUnit Wizard you compile & link a z/OS Load Module as part of

the Unit Test process. The Wizard pulls DSNs and other over-rides from your Property Group

and file tailors JCL to Build the Test Case “on the fly”

• It then submits the JCL – so you must understand your “standard” batch testing environment

• Your shop may have its own complex/sophisticated Build steps & software.

Working within your customized environment is out-of-scope for the course

• Also – program source code for zUnit resides in native TSO Libraries – only.

The use of SCM tools such as Endevor, Changeman, SCLM, RTC, Git, etc.

is also out-of-scope.

16

Discussion: Why Unit Test?

By testing individual logic routines in your programs:

• You can move through the lifecycle more quickly, because you have precise feedback about separate logic routines

• So you can better understand cause & effect

• And you know that your code works and you know how your code works, which gives you confidence to make enhancements and modifications

• Because you execute zUnit Tests through JCL:

• The testing can be automated

• The end-to-end process takes less time than interactive debugging.

• And it can be more systematic

• Unit Testing allows you to understand “cause & effect” in your program logic – and brings you much closer to your code

All of the above benefits allow you to catch errors earlier in the lifecycle…

17

Discussion: The value of early lifecycle testing

During the Coding orUnit Testingphases

$80/defect

During the BUILD phase

$240/defect

During Quality Assurance or the System Test phases

$960/defect

Once releasedinto production

$7,600/defect+

Law suits, loss of customer trust,

damage to brand

“80% of development costs are spent identifying and correcting defects” **

**National Institute of Standards & Technology

Source: GBS Industry standard study

Defect cost derived in assuming it takes 8 hours to find, fix and repair a defect when found in code and unit test. Defect FFR cost for other phases calculated by using the multiplier on a blended rate of $80/hr.

18

Discussion: Unit Testing is Not a “Silver Bullet”

GUI

3270

Regression

Testing

Performance

Testing

Interactive Testing

Integration Testing

Automated Unit Testing

Test Driven Development

Rational Function Tester

Application Performance Analyzer

zUnit

IDz Integrated Debugger

IBM Debug Tool

IBM recognizes this - and provides multiple testing solutions, each

optimized for different problem areas within the software testing

space:

19

Break… then:• Setup and configuration for Property Groups

• Allocate zUnit Configuration files

• Deeper dive into Elements and Assertions

• DB2 Property Group - setup

Next Steps – Today’s Class

20


▪ zUnit Terms, Vocabulary, Application Support/Limitations

▪ zUnit Development Process and Run-Time Architecture





▪ Debugging your Test Case



▪ Appendix

This chapter describes the conceptual terminology of the xUnit framework – and the parallels with zUnit. It also covers zUnit

Terms & Concepts necessary for your successful work.

21

xUnit Components and Terminology (Distributed Vocabulary)

Test RunnerA test runner executes test cases or test suites and makes the results available in some programmatically-consumable way (e.g.,

XML,...).

Test CaseTest cases execute within a Entry and make assertions during test execution. Test cases contain any number of tests where each

test is a separate subprogram, function, method, or procedure in the test case.

Test Suite Test suites define a set of test cases for test execution.

Assertions Assertions verify the behavior and state of a test case. A failed assertion should result in an exception being thrown.

Test FixtureA Entry is a context and/or environment that the programmer creates (setup()) before a test in a test case is executed, and

discards (teardown()) immediately after the test is run.

Test ExecutionTest execution involves invoking the Test Runner with input that includes, among other things, which test Cases or test suites

should be run.

All xUnit frameworks share the following basic component architecture, with some varied implementation details.

Test Execution

Test Runner

Test Suite

Test Case

Test Fixture

Assertions

Your program and the

program logic

to be tested

Test Results

(XML File)

There are hundreds of distributed xUnit products and implementations (jUnit, JSUnit, NUnit, XMLUnit,etc.). They all contain code frameworks in the underlying supported language. Many but not all are TAP compliant.

Launches

Reads from

Which identifies

Which constructs

Which contain Against…

22

zUnit – xUnit Framework Implementation

Test RunnerA z/OS systems program developed by the IDz team, and installed with IDz. The Test Runner orchestrates the unit testing process

Test CaseA generated COBOL or PL/I program compiled into a Load Module that calls your target Subroutine. Test Cases are executed

(Called) by the Test Runner

Test Suite An XML file that provides a list of Test Cases to be executed by the Test Runner

Assertions COBOL or PL/I conditions that test individual units of source code in your program

EntriesA generated set of COBOL or PL/I programs that implement the xUnit framework standard; for setting up, running and tearing

down individual Unit Tests

Test Execution z/OS JCL that invokes the Test Runner

Test Execution //JCL

Test Runner - IDz zUnit Run-time

Test Suite - List of Test Cases (Test Configuration)

Test Case - Generated COBOL or PL/I program

Entry - Generated COBOL or PL/I program

Assertions - Conditional Expressions

coded in COBOL or PL/IYour program and the

logic to be tested

Test Results

(XML File)

IDz substitutes generated z/OS-specific resources for distributed technology classes, and frameworks.

EXEC PGM=

OPEN INPUTREAD Test Suite

Which identifies Test Case Load Module

The Test Runner CALLs (interacts with)Test Case Load Module

Which contains Entries(COBOL subprograms or PL/I procedures

Each Entry sets up and CALLs(executes) individual Unit Tests andreleases unit test resources (Tear Down)

Makes

Submit JCL

23

A Closer Look at Unit Test/Entry Assertions

Assertions are testing hypotheses, pass/fail inspections about how specific processing in your program is supposed to work…

Assertions can also be thought of like SQL predicates – without a WHERE clause:

• If Empty_QSAM_File and File_Status <> -4 (Assertion = Fail)

• If Date = ‘20140132’ and Return_Code <> -1 (Assertion = Fail)

Program Logic Unit Tests Assertions

A batch program’s file open

routine is supposed to set a File Status variable value to a -4 if

there are no records a in the data

set and to 0 if there are records in

the file.

Your JCL’s DD card points to an empty

QSAM file.

-4 File Status upon file open.

Your JCL’s DD card points to a QSAM

file that contains data records.

0 File Status upon file open.

You’ve coded a Gregorian date

validation Subroutine which should return a -1 if it finds an

invalid date - and a 0 if the date is

valid.

Pass in the following date : “20140132”. You expect a -1 return code upon

GOBACK from the Subroutine

Pass in the following date: “20140131”. You expect a 0 return code upon

GOBACK from the Subroutine

If a variable value from in an input

file is expected to be found in a

COBOL table and it isn’t found the SEARCH verb returns a -8.

Pass in a variable value not found in the

table.

You expect a -8 return code.

Pass in a variable value that is found in

the table

You expect a 0 return code.

24

Generated Test Cases, Entries + Assertions

Entry (COBOL subprogram or a /PL/I procedure)

Test - Assertion/Evaluation

Test Case

• …• …• Verifiable logic routine• …• …• …• Verifiable logic routine• …

• Verifiable logic routine• …

• Verifiable logic routine• …

• Verifiable logic routine• …• Verifiable logic routine• …• …

Target Subroutine

Using IDz you generate a Test Case - A Test Case is a COBOL program or a PL/I procedure

A Test Case contains 1➔M Test Entries - Entries are implemented as nested subprograms

Each Entry contains exactly one (1) Test which executes an Assertion and evaluates the result• Assertions are CALLs to your Target Subroutine

• Results of each Assertion/Evaluation are journaled (written) to an XML file.

EntryTest - Assertion/Evaluation



Con

tain

s o

ne-t

o-m

an

y

25


▪ Terms, Vocabulary, Run-Time Architecture

▪ zUnit Development Process

▪ zUnit Setup, Required Datasets, Wizards and Workflow





▪ Debugging Test Cases



▪ Appendix

This chapter describes the workflow for starting zUnit testing; Required dataset allocation, Property Group specification and

additional zUnit run-time explanation.

26

zUnit Development with IDz – Steps

One time tasks:1. Allocate the datasets for zUnit testing

2. Setup your Property Group

3. Compile/Link each of your application program(s) –Test Cases will be compiled/Linked to a PDSE

Iterative steps (do the following for each unit test):

1. Use the wizard to generate a test case

• Define the Test Case defaults and the Entry names

• Edit the Entry data values:

• Edit the Entry_n input values

• Edit the Entry_n expected result values

• Optionally populate program FDs, by importing records from external datasets

2. Save, Build and Run the test case

3. Evaluate your zUnit test

• AZUCFG file

• JCL SYSOUT and SYSPRINT files

• (Optionally) Debug the Test Case or run Code Coverage

27

Allocate the Datasets Used in zUnit Work – AZU… Libraries

Req

uir

ed

AZ

U.*

… lib

rarie

s

DCB Allocation for libraries

28

BUILD

(Concepts) – Datasets and Generation Wizards

Subroutine to be tested<HLQ>.ZUNIT.COBOL

Load Library<HLQ>.ZUNIT.LOAD

Library of Imported File Data Records

<HLQ>.ZUNIT.AZUTDT

Library of Import file layouts (SCHEMA)

<HLQ>.ZUNIT.AZUSCH

XML Entry data used to generate Test Case

<HLQ>.ZUNIT.AZUGEN

Runtime defaults used to execute Test Case

<HLQ>.ZUNIT.AZUCFG

zUnit Generated COBOL Programs

<HLQ>.ZUNIT.GEN.COBOL

Test Case Wizard

File Import Wizard

If program has FD

Test Case programs …and… Stub programs

zUnit Generated COBOL Programs

<HLQ>.ZUNIT.GEN.COBOL

Generate JCL for Compile/Link

Generate Test Case

29

(Concepts) – Datasets and zUnit Processes

Output results from Unit Test

<HLQ>.ZUNIT.AZURES

zUnit Test Run

<HLQ>.ZUNIT.AZUCFG (Test Case)

<HLQ>.ZUNIT.GEN.COBOL (Stub Program)

<HLQ>.ZUNIT.GEN.COBOL (Test Case)

<HLQ>.ZUNIT.LOAD (Subroutine to be tested)

Note that you can save the JCL Job from the zUnit Test Run for

repeated testing

30

zUnit Property Group file Configuration

(Create/Modify) a Property Group file for zUnit:1. SYSLIB tab – to resolve COPY / INCLUDE references in your code

2. JCL tab

• Library for generated JCL

• JOB Card and JCLLIB

3. COBOL tab

• Compilation datasets: Listing, OBJ, SYSDEBUG, DBRM

4. Link tab:

• Link Step options: DYNAM(DLL) NOREUS

• Link libraries: Your load library (PDSE), The LE library, The Test Runner runtime-library

• Additional JCL://LINK.AZUTSTRX DD DISP=SHR,

// DSN=YOUR.IDZ.INSTALL.SFELLOAD(AZUTSTRX)

5. Run tab ➔ Step name/Run

• Additional JCL for QSAM files not part of the data file import for your test cases

6. zUnit tab – specify:

• Procedures and Steps – defaults for the Test Runner

• Generation options – for the Test Cases

31

In order for IDz to access copybooks and includes in your programs, you must specify SYSLIB (Search path through a concatenated list of Library DSNs)

Steps:From the Property Group Manager view

Select your connection

Right-click and select: New Property Group…

Property Group: SYSLIB – 1 of 2

You can also hardcode fully-qualified DSN for each PDS

32

Property Group: SYSLIB – 2 of 2Once your Property Group has been edited, you need to assign (Associate) it to MVS Files in Remote Systems

Steps:From Remote Systems:

- Right-click over MVS Files

- Select Property Group > Associate Property Group…

- Check your named Property Group

- Click OK

Test your work:

Open a program that has a COPY statement

Find the reference to the COPY statement

Check variable references:

Scroll to find some variable defined in a

copybook

PATIENT-ID, VALID-BILLABLE-TYPES

Right-click over the variable name and select

Open Declaration

33

Property Group: Job Card for your LPAR – 1 of 2

Because zUnit integrates tightly with z/OS runtime services, you will need to setup a JOB Card specific to your mainframe LPAR

Do this by copy/pasting in a JOB Card from one of your JCL files:▪ Expand MVS Files

▪ Expand a JCL (source library)

▪ Double-click and open the file

From within the opened JCL file:

Select your Job Card

All parts of the existing text: //JOBLIB, etc.

▪ Right-click and copy the selected text into your Windows copy/paste buffer

Co

py

a JO

B C

ard

fro

m

an e

xist

ing

JC

L fi

le

34

Property Group: Job Card for your LPAR – 2 of 2

From the JCL tab

Paste your copied Job Card into the JCL job card area above. Ensure that there are no

extra blank lines below the Job Card statements, and save changes to the Property Group

(press Ctrl+S)

Copy a Job Card that works on your LPAR to here

<TSOID>.ZUNIT.CNTL Enter the name of a JCL PDS.

zUnit will create Build JCL members into it.

zUnit Property Group

35

Property Group: COBOL Tab

ELAXFCOC - COBOL step:

• Specific Compiler options only needed for debugging using the IDz Integrated Debugger

• You’ll need the Listing and SYSLIB entries – as per standard use

• And you’ll need Error Feedback for present syntax errors in IDz

• Note that you do not necessarily need Object and Debug data sets

• Check with your instructor

36

Property Group: Link Tab

ELAXFLNK - LINK step:

• Specific/Required Link-Edit options

• Link (Load) libraries for:

• Additional statically called programs:

• <HLQ>.ZUNIT.LOAD (PDSE)

• LE Runtime library

• CEE.SCEELKED

• Sample IDz run-time library –Note the FEKPRFX symbolic

• FEKPRFX..SFELSAMP

• INCLUDE AZUTSTRX

• AZUTSTRX is an entry point to the zUnit Test Runner

• Your load library:

• It must be a PDSE for Test Cases

• It can be a PDSE for your Subroutines• j

Additional JCL to find the AZUTSTRX member

37

Property Group: zUnit Tab – 1 of 2

AZUZUNIT - RUNNER step:

• Specification/Selection of the DSN for the:

• zUnit configuration library

• zUnit results library

• AZUCFG: Defaults for the Test Runner actions – if run-time failures occur

• Think of these like EXEC SQL WHENEVER … or CICS HANDLE CONDITION constructs

• AZURES: PDS to hold the Test Runner zUnit run-time results

38

Property Group: zUnit Tab – 2 of 2

Generation Options:

• Specification/Selection of the DSNs for the:

1. zUnit generated test case values

2. zUnit Test Case source libraries for COBOL & PL/I for all Generated program files

3. zUnit Imported Test Data libraries:

• File schema

• Test records

4. High-level dataset qualification for files generated to hold import data

5. Space parameters for the generated files

39

zUnit Context Menu Options and Workflow

Basic steps:

• Select a COBOL or PL/I program, that has been successfully compiled/linked

• Right-click, and from the Context Menu, and select: z/OS Automated Unit Testing Framework (zUnit)

• Generate Test Case…

• Create, Build, Run the zUnit Test

• Prompted options to run through all Steps

• Build the Test Case

• Run the Test Case

• Debug the Test Case

• Run Code Coverage for the Test Case

• Create the Test Runner Configuration

• Primarily used for DB2 subroutine testing

40

zUnit Wizard-Workflow (dev process for Generate Test Case Action)

Create Load Module for Subroutine

Right-click on COBOL subroutine,

select Generate zUnit Test Case

Right-click on COBOL subroutine –

Generate JCL for Compile Link

Specify Test Case name

Specify XML Entry values (Assertions)

Build and Run Test Case

Create Load Module for Test Case

Run Test Case and Subroutine

Generate Test Case Dialog

z/OS Batch Job Results (JES)Verify Results (view output of batch run)

41

zUnit Development with IDz – Steps

One time tasks:• Allocate the datasets for zUnit testing

• Setup your Property Group

• Compile/Link each of your application program(s) –Test Cases will be compiled/Linked to a PDSE

Iterative steps (do the following for each unit test):

1. Use the wizard to generate a test case

• Define the Test Case defaults and the Entry names

• Edit the Entry data values:

• Edit the Entry_n input values

• Edit the Entry_n expected result values

• Optionally populate program FDs, by importing records from external datasets

2. Save, Build and Run the test case

3. Evaluate your zUnit test

• AZUCFG file

• JCL SYSOUT and SYSPRINT files

• (Optionally) Debug the Test Case or run Code Coverage

42

Create the Test Case - Using the IDz Wizard - Part 1

Right-click on your source program and select:• z/OS Automated Unit Testing Framework(zUnit)


See Slide Notes – or contact IBM for the source code – for this example

It goes

without

saying that

you must

fully

understand

the

procedural

logic in the

program

you want to

zUnit test

before

jumping into

the Test

Case wizard

and building

Entry values

43


IDz will fill in the

• Data set name from the Property Group

• Member name (by adding the letter “T” as a

suffix to the selected program

• You can override (over-type) the

Member name

You can enter• Test case ID – (optional – typically associated with an

RTC Work Item or Endevor CCID, etc.)

• Test entries

• Entry Name is the 8-character MVS name

• Test Name is a an optional annotation for

the Unit Test

• Click Edit Test Entry Data…

• If your program contains Copybooks

(dependent files) you should import them

44


• IDz will render all of the data items in your

program’s LINKAGE SECTION like a

spreadsheet

• You fill in the:• Input values to your Unit Test

• Expected output values from the call to

your subroutine

• Note that your Entry values must be:• Type compatible

• And range compatible with the variables

45

The Test Case Entry Editor

• The editor provides cells for you to create test data values, based on your program logic – and

LINKAGE SECTION data declarations. A few notes:• Fields that you enter values for will participate in the:

• Initializing of the LINKAGE SECTION prior to invoking your subroutine

• Generated Assertion/Evaluation logic

• Fields that you do not enter values in:

• Are not referenced in the Test Case

• Are not uninitialized by the Test Runner

• The data you enter must conform to the PIC Clause (type) of the variable

• You cannot enter non-display (binary) data – at the v9.5.x release

• OCCURS DEPENDING on tables can be expanded to the MAX value in the field definition

• IDz v14.1.2 and later provides a mechanism to dynamically REDEFINE a field definition

• This allows you to enter & test for non-numeric values in PIC 9 fields

All

of

the

fie

lds

in t

he

LIN

KA

GE

SEC

TIO

N

The

fir

st 0

1-

leve

l in

th

e L

INK

AG

E SE

CTI

ON

Gro

up

Fie

ld

Ele

men

tary

Fie

lds

You can enter values for any/all elementary data

fields (PIC clause)

You cannot enter values into a group field

46

Options for creating Test Case Entries using the XML Wizard/Editor

• Typing – plain text

• Copy fields from one entry to another

• Copy/Paste field values from an external file:

• MS-Excel spreadsheet

• Notepad or any plain-text source

For lengthy/complex structures, it’s useful to Debug your application before building Entries in the Wizard, in order to capture LINKAGE values

From the Variables or Monitors view (top right, in Debug Perspective)

• Copy view to clipboard ➔

• Open an external ASCII file

• Paste into Notepad/Excel/etc.

• Copy values into Test Case Entries

• Edit out the variable names – just copy the

values into the Entry input fields

If you are using IDz v14.1.3 or later, you may capture the Input/Output LINKAGE SECTION variable values…

//CEEOPTS DD *TEST(ALL,,,*)ENVAR("EQA_STARTUP_KEY=LD,*,rec=both,out=/u/dds0001,testid=demo")/*

47

Considerations for creating Test Case Entries in the XML Wizard/Editor

• Data values must be type and range compatible with the LINKAGE SECTION variable declaration

• If variables are REDEFINED you can enter values in either of the type definitions

• The Entry will pass/fail depending on the assertion – which is dependent on your program logic, coupled with the Entry-Input and Expected values

• In this example which Entry will pass and which will fail (and why)?

48

Save and Build the Test Case

• When you are finished specifying

Test Case Entries click the

Generate Programs… icon on

the toolbar

• You will be prompted to finish the

Wizard:



The build occurs on z/OSThe Test Case executes on

z/OS

49

Run the Test Case

At the Run wizard you can:• Rename the config/results

member names

• And/or overwrite config/result

members – if they exist in the PDS

Let IDz Locate the Job for

you…

IDz will also open the

Member named from the

Wizard in an Editor – so that

you can view results

50

Evaluate results

The wizard shows the Test run results in an editor

The JES Jobs should be

expanded – and you’ll want to

look at SYSPRINT and SYSOUT

51

Evaluate results – Batch job information

SYSPRINT

displays the Test

Runner

SYSOUT - displays the:

• Names of the Test Case internal modules.

• Any COBOL DISPLAY data

52

zUnit Test - JES Output – Deeper dive

▪ Your Batch Job which executed the Test Runner will end with an MVS Return Code. SYSPRINT and SYSOUT are also produced in spool files

The zUnit Test Runner can set the following return codes:⚫ U0000: All tests passed.⚫ U0004: One or more tests failed with an assertion.⚫ U0008: One or more tests are in error (for example, SOC4, DIV/0)

⚫ Note that if a program failure occurs, the Test Runner will end your Unit Test run

⚫ U0016: A severe error occurred (for example, file I/O error).

53

Reusing the JCL produced by the zUnit Test

Your Batch JCL can be utilized as a repeatable test through the following steps:

1. From JES, right-click on the zUnit job and Show JCL

2. Select All, Copy/Paste and Save the JCL into a new JCL PDS

Reusing Unit Test JCL is a foundation element of DevOps “Continuous Integration”

54

Best Practices for adding complex Entries

It is useful to Debug your application before building Entries in the Wizard, in order to capture LINKAGE values

From the Variables or Monitors view (top right, in Debug Perspective)

• Copy Variables ➔

• Paste into Notepad or Excel, as ASCII fields

• Edit/Copy values into Test Case Entries

• The Copied Variables from Debug contain both field names and values

• You need only the field values

55

zUnit Vocabulary - Review**

▪Test Execution: JCL that invokes the Test Runner (a “supervisor program” or “test harness” that runs your Test Suite)

▪Test Runner: The zUnit “supervisor program” invoked by Test Execution, that:

▪ Reads a Test Configuration Test Suite

▪ Calls your Test Cases

▪Test Suite: an XML configuration file that defines which Test Cases the Test Runner should execute (Note - a Test Case == a Load Module)

▪Test Case: An IDz-generated COBOL or PL/I program that:

▪ Is called by the Test Runner

▪ Uses a Entry to Call your Subroutine and write test outcomes to a Test Results file

▪Entry: A set of generated programs nested inside your Test Case. Entries run Tests that utilize Assertion logic to Call your Subroutine, and evaluate the result.

▪Subroutine: The target call-able program to be Unit Tested

▪Test Results: An output dataset that describes the results of each test run in xUnit standard (XML) file format

▪Assertion: A simple pass/fail predicate used to test one part of your Subroutine’s logic

** Test Execution, Test Runner, Test Suite, Test Case, Entry, Assertion == xUnit vocabulary

56

UNIT

Topics:

zUnit Testing with IDz

▪ Management Overview


▪ zUnit Development Process – Overview

▪ zUnit Setup, Required Datasets, Wizards and Workflow






▪ Futures


▪ Appendix

This chapter introduces the Testcase Editor options; Workflow, Dialogs & Specifications, Build Options

57

XML Editing - Toolbar

Ad

da

ne

w E

ntry

Ed

it En

try: C

ha

ng

e g

en

era

ted m

od

ule

/ Te

st n

am

e

De

lete

Se

lecte

d E

ntry

Ex

pa

nd

all p

ara

me

ters

Re

fres

h X

ML

from

So

urc

e

Ge

ne

rate

Te

st c

as

e

Work with imported records

Sh

ow

La

yo

ut fo

r Item

s c

Ex

pa

nd

to p

ara

me

ters

Co

llap

se

all p

ara

me

ters

Sh

ow

En

try C

olu

mn

s

Imp

ort Q

SA

M re

co

rds

or Im

po

rt ba

tch

-run

D

ata

Cap

ture

of L

INK

AG

E v

alu

es

IDz’s XML Editor provides functionality to define sophisticated Entry Input/Expected values for complex

LINKAGE SECTIONS and/or Imported QSAM data records

58

XML Editing – Context Menu

The Context Menu offers most of the options found on the Toolbar – accessed from Ctrl+Spacebar

Additional options that simplify XML assertion editing:

1. Copy - selected values to be pasted in other Entry(s)

2. Cut - selected values

3. Paste - copied values

4. Delete – selected values

5. Select Data Type… allows you to dynamically REDEFINE a field - typically used to provide non-numeric values as input to PIC 9 fields to test for S0C7 problems

Notes:

• Additional XML Editing features are available for dealing with large COBOL tables (arrays)

• If the program you’re working with contains an FD for an external file a cell appears in the matrix – allowing you to import QSAM Data Records

59

Select Data Type…

1. Select Data Type… allows you to dynamically REDEFINE a field. This is typically used to provide non-numeric and values as input to PIC 9 variables which are used to Unit Test for potential S0C7 ABENDS

Steps:

Right-click in the cell you wish to REDEFINE and from the menu choose: Select Data Type…

Choose a different Data Type then click OK

Enter your REDEFINED value in the cell

Note that you will have the REDEFINED number of bytes to work with

60






▪ QSAM Data Import – and Linkage Data Capture from batch jobs





▪ Futures


▪ Appendix

This chapter introduces two different approaches to capturing lengthy and complex Test Case values; 1. From data files 2. Pulled from

Linkage Section values during program runs

61

QSAM Data Import Option – Overview

Starting IDz v14 you can Import z/OS QSAM data records for files that are defined in a program FD into your XML Data Editing Session

• QSAM files only are allowed: No DB2, VSAM, IMS, etc.

• You may import as many records as you’d like

• Once imported, you can:

• Modify record/field values

• Delete records

• Copy and paste data values

The File Layout (schema) is established by the program FD and associated data structures

Each Entry can contain a set of Imported data records

All data records that are part of an Entry are read – in sequence for the Unit Test

The File System Mapping entries for AZU… are used in the File Import process

The Run tab on the Property Group is also used in Data Import

If imported records contain “garbage” in numeric fields, the Import process will change those values to zeroes

zU

nit

XM

L E

dit

Sessio

n

Record

Import

QSAM File

FileLayoutSchema

RecordValuesRecordValues

62

QSAM Data Import Option – Process

1. From the Generate Test Case dialog – select and delete the default ENTRY1 test

• The Import process will create an Entry test for each Import

2. In the Entry Data Editor, click the Import test data toolbar button Import Test Data toolbar button.

• The Import Test Data window opens.

3. Select the data parameter into which you want to import data, specify the number of records to import and then click Browse.

4. In the Browse for File window, navigate to the QSAM data set that contains the data you want to import, select that file, and click OK.

5. In the Number of imported records field of the Import Test Data window, specify the number of records you want to import into the test case, and then click OK.

• zUnit generates JCL and submits a job to import the data from the data set into a new test entry.

• The data is added to records of the parameter that you chose in the Import Test Data window

63

Data Import Process – 1 of 3

1. Delete the default

ENTRY1 Test entry

Click: Edit Test Entry Data…

2. In the Editor: Click the Import Test Data… icon

64

Data Import Process – 2 of 3

3. From Import Test • Select the File you wish to import into – the internal file (FD)

name shows

• Specify the number of records you wish to import

• Click Browse

4. From Browse For File• Navigate within Connection/Datasets to the

file you wish to import

• Click OK

65

Import Process – 3 of 3

Im

po

rte

d R

eco

rd

s

• A batch Job will launch

to compile/link/run a

process that extracts

your specified number

of records from the

QSAM file into the

AZUTDT dataset –

and into the XML Entry

editor

• The record data will be

laid out in the Entry

editor according to

your program’s

schema for the file

layout

• The Entry will be

named (by default)

AZUE0000

66

Editing Imported Data

• At this point, the standard XML Entry editing functionality is

available

• You may:

• Over-type Imported record values

• Cut/copy/paste values throughout the Entries

• Add/Delete records

• When you are finished customizing the Entry tests, Generate

the Test Case program and proceed as before

67

Linkage Section Data Capture from Batch Jobs – 1 of 2

Starting with IDz v14 you can capture LINKAGE SECTION values from executing batch programs running under Debug. This is useful for populating large LINKAGE SECTION structures with meticulous, complex test data values

rec=both Capture both Input and Output LINKAGE values from the subroutine

out= Specifies to the UNIX directory for the output *.xml file

Notes:

• Running the Debug job produces the *.xml file that you will import (next slide)

• The Debug/TEST statement is case sensitive

• All other punctuation shown above must be coded exactly as shown

Steps: Create a //CEEOPTS DD * statement with the following TEST parameters:

TEST(ALL,,,*)

ENVAR("EQA_STARTUP_KEY=LD,*,

rec=both,out=/u/dds0001,testid=demo")

/*

“My Home ➔ /u/dds0001

68

Linkage Section Data Capture from

Batch Jobs – 2 of 2

When the Debug job completes you can:

• Generate a zUnit Test Case without any Entries

• Import the Recorded data - to create an Entry

• Click the Import icon and select Import Recorded Input/Output Data… You will be prompted to Browse – select the Unix file file that the batch Job run created

Your values are imported

69






▪ QSAM Data Imports





▪ Futures


▪ Appendix

This chapter describes the specifications necessary to Unit Test DB2 programs – both for IDz & RDz v9.5

70

Process – Working with DB2 Programs

zUnit supports Unit Testing calls to subroutines that contain embedded SQL statements. The process is slightly different from what you did in the last section…

1. Build your Subroutine with embedded SQL statements using your standard Build Process for DB2 modules: Precompile/Compile/Link/BIND

2. Go through the standard the Generate Test Case dialog – to create a zUnit test Entry values for the Subroutine’s LINKAGE SECTION

3. RDz v9.5 only - Generate and Build your Test Case, but do not Run the Test Case

• From the zUnit Framework select: Generate Runner Configuration…

• Typically you will check all of the zUnit Run Option continuation settings

4. Run your DB2 zUnit Test using JCL that references the AZUTSTRN (Entry point to the zUnit Test Runner) The detailed slide will show an example

5. Validate your Unit Test, using:

• The AZURES member

• SYSPRINT/SYSOUT from the batch job

71

Generate a standalone Test Runner Configuration - RDz v9.5 only

1. Right-click over the COBOL program and select:

• zUnit Framework ➔ Generate Runner Configuration…

2. Select the AZUCFG library location, and name the Configuration

3. Select the Test Run options (Typically you check all of the boxes)

• Save your work

1.

2.

3.

72

JCL – To run a DB2/zUnit Test – RDz v9.5 only

There are three areas of interest in the JCL to run zUnit against a DB2 subroutine:

• The PROC is ELAXFTSO –which is supplied by IBM and installed with IDz Server

• You need to reference the Test Runner Configuration file (just created)

• You need to supply batch/DB2 SYSTSIN statements:

• DB2 Sub-System

• RUN (AZUTSTRN)

• PLAN (your program’s plan)

• LIB (the IDz SFEKLOAD library)

73











▪ Appendix

This chapter describes the steps & workflow needed to create COBOL program stubs – and to Build & use the stubs during zUnit testing

74

Stubbing out sub-routine calls - Overview

The zUnit wizard allows you to stub out “static” calls to subroutines, replacing them with return values that allow you to control the unit test process.

Here are the steps:

1. Go through the standard the Generate Test Case dialog – to create a zUnit test Entry –including modifying specific values for the Subroutine’s LINKAGE SECTION

• These fields will show up in the XML Entry editor for statically-called subroutines

2. Generate your test case. When you get to the Generation Programs dialog, Check the box for any/all subroutines to stub out.

• IDz will proceed to create the stub programs into the library specified in the property group file: zUnit / Generation Options / COBOL Test Case Programs

3. In step 3 you’ll be prompted to Build your new sub-routine – do so at this point, using Generate Compile/Link JCL

• Note that the zUnit Generated Stub Program will be found in the library specified in your zUnit Property Group tab

4. Then re-Build the Subroutine you wish to zUnit test (you have to do this if the modules are statically linked)

5. Return and from the zUnit Framework: Build and Run your Test Case

6. Validate results using:

• The AZURES member

• SYSPRINT/SYSOUT from the batch job

75

The Entry XML Editor – Creating values for the Stub program

In this example (because we intend to stub out the call to CLC2) you can see that we have added values to the fields that call CLC2 from PERF2 ➔

And we’ve Copied/Pasted those same values in the record that will be evaluated by the zUnit process (Assertion values)

76

Generation Programs dialog – When working with a static call

After you click the Generate Program icon – the wizard will present you with this dialog ➔

By checking the box under “Programs to generate as test cases or stubs” IDz will generate a stub program – that will be called in place of the real subprogram

During the generation process you will be prompted to build your new stub program

77

Build the Stub and Calling Programs

• Generate JCL for the new stub subprogram ➔

• Run the generated JCL

• Check the JES return codes

• And if good (0 or 4) Re-build the calling subroutine

You have to rebuild the calling subroutine because this is a static load module, right? ☺

78

Build and Run the Test Case

When you’ve finished successfully compiling the stub and compiling the calling subroutine, return to the zUnit Wizard and Build the Test Case

• Right-click over the program and select; Build the Test Case

• During this wizard process you will be prompted to Run the Test Case…

• Do so – and verify your results

79

Looking at the stub program’s generated code

Optionally – you might open the generated Stub program to understand how the Entry XML Wizard values are transposed into COBOL code:

• Alphanumeric (PIC X) fields become structures in WORKING-STORAGE

• Numeric values become literals

• Both are moved to the corresponding fields – that you edited in the XML

80











▪ Appendix

This chapter describes the use of the IDz Debugger – for understanding your Unit Tests. It also describes the use of Code Coverage.

81

Debugging your Test Case

Once you have Compiled/Linked in the z/OS Projects or Remote Systems view, select a COBOL or PL/I source file or load module.

Right-click and select z/OS Automated Unit Testing Framework (zUnit) > Debug Test Case…

The Debug Test Case window opens ➔

Specify the member name for the

configuration file and results file

and choose an overwrite option.

Click OK

Note that – by default the IDz Integrated Debugger is used to test your code

82

Debugging your Test Case – Debug Perspective

Breakpoints are automatically set to stop at all entries. You can reach the entry point of the source file by repeatedly clicking Resume on the toolbar.

Be sure that a Breakpoint is set to: Stop at all function entries

Typically you Resume until your Debug session gets to your program

83

Code Coverage for your Test Case

From the Run tab in your Property Group, you can choose either the Integrated Debugger, IBM's Debug Tool - or you can specify settings for another client IP – if you wish to pass specific IP Address values into the debugging session (for example – if you wish to debug Java calling an IMS TM or CICS transaction.

Note that there are additional Debugging and LE (Language Environment) options you can setup on this tab

84

Code Coverage Results

Once you have Compiled/Linked in the z/OS Projects or Remote Systems view, select a COBOL or PL/I source file or load module.

Right-click and select z/OS Automated Unit Testing Framework (zUnit) > Code Coverage…

Your Test Case runs… and the values you’ve entered in the XML Entries dictate program execution results

85











▪ Appendix

86

Current zUnit Support

Languages

zUnit

Support Comments

COBOL and PL/I

Subroutines

100% Assertion values passed through Linkage variables. VSAM and

QSAM File I/O is supported. Embedded SQL statements can exist &

run in the code, but there is currently no support for evaluating

changes to DB2 table state due to unit test runs.

Use the IDz installed PROC: ELAXFTSO to zUnit test subroutines

that contain SQL statements. This PROC can only be executed

through batch/JCL. It cannot be run interactively.

Programs with CICS

or IMS

No Support Support for IMS and CICS is in-plan for the future.

COBOL or PL/I

Batch “driver”

programs -

100% Support for monolithic programs where test-values are not passed

through Linkage variables but are contained in file I/O is currently

supported through the Wizard for:

• QSAM Data – which can be imported and massaged

• VSAM Data

The generated Test Case executes the “ISRSUPC” MVS Utility –

which compares expected to actual unit test results.

Assembler, C++ and

4GL programs as

z/OS Subroutines

No in-the-box

Support

Only COBOL and PL/I subroutines (where values are passed through

Linkage variables) are currently supported.

However, you can create COBOL or PL/I stub programs that pass

Linkage values into your Assembler/4GL programs. Making them

available for zUnit Testing.

87

Choosing programs for zUnit

Consider this decision-tree…

Y

Black

Box

Testing

Black Box

Testing

Black Box

TestingI understand the

programs and data logic well

enough to create Entry values for

my Unit Test

Test evaluation can be achieved through the

LINKAGE SECTION – or for standalone

Batch, through ISRSUPC file

compare

zUnit

Y

Y

N

N

N

COBOL or PL/I Batch

Subroutine(s)Or standalone QSAM/VSAM

Batch

88

What do you put under source control?

Because the generated/compiled/linked Test Case programs – in our case: <HLQ>.ZUNIT.GEN.COBOL(*) are all generated by the Test Case Entries, the data in the AZU… library members are what is needed to source manage your test cases

You should note that the AZU… libraries are:• PDSE

• LRECL: 16383

• BLKSIZE: 32760

• RECFM: VBA

… In other words, these are not simple fixed-byte TSO datasets

… Source managing these files using products like Rational Team Concert makes source control easier

89

Modifying Test Cases

When you wish to modify/enhance your Test Cases right-click on the subroutine and from the z/OS framework select: Generate Test Case…

You will be prompted to select an existing AZUGEN member

• Recall that the AZUGEN dataset manages all of the metadata required to generate the Test Case

• If you open the AZUGEN member, and edit the XML you will see references to all of the parts that end up generating a zUnit Test Case

While editing the Test Case through the Wizard you have carte blanche to modify/update your Entries and their values. And you can utilize the XML editing techniques learned in this course.

When finished, Generate, Build and Run your new zUnit Test.

Test Case

Subroutine-to-be-tested + copybook(s)

90

Sharing Test Cases

Procedure to share/distribute the Test Case:

· Copy the generated XML file from <hlq>.ZUNIT.AZUGEN <program name>.xml

· Copy Testdata from <hlq>.ZUNIT.AZUTDT based in the list of files in the TestDataArray of the previous xml (from AZUGEN)

In the following example the files are :

A0000000, A0000001, A0000002, A0000003

· Copy the Data Formats (Schema Array) from <hlq>.ZUNIT.AZUSCH base in the list of element TestDataSchema shown in the xml (AZUGEN). In the example below the file is INTERFA4

· Import the Property Group ( or configure one for zUNIT)

· Compile the Program being tested

· Right click on the program and z/OS Automated Unit Test Framework Generate Test Case

· Click on Edit Test Entry Data and click on the icon Generate Programs,

· Run the tests

Note: the Test target source is also copied from <hlq>.ZUNIT.COBOL in the steps. AZUGEN file contains the source location, so that need not be copied.

91



▪ zUnit Development

▪ Workshop Setup – Property Groups & IDz Server PROCs

▪ Appendix

92

Workshop Setup

If you are responsible for your shop’s ADFz/IDz setup – for zUnit you will need to assess the following – vis a vis zUnit configuration/customization:

• IDz Client installation:

• Version: We recommend v14.1.3 or later

• Plug-ins: No particular functionality is required above whatever you’ve decided to use. However we do recommend IBM Data Studio

• Workspace: You can utilize your existing Workspace(s). However, we recommend that the Workspaces be created new, at the Client release level. And whatever Workspace you choose will need to import the Property Group files

• Property Group files: Upcoming slide on customization.

• IDz Server installation:

• Performance: A stress test should be deployed before production App-Dev use by your developers

• Client connectivity: Stability across all functions. And 100% configured/working functionality:

• Also, please look specifically at Allocate Like, which exercises the ISPF Gateway

integration/config.

• Source Management: This course works from COBOL programs in TSO Libraries. If you wish to integrate Endevor, Changeman, etc. you will need to work thru workflow & functionality independently from the workshops & materials in this doc

• IDz Installed PROCs: See next slides. DSNs in the PROCs must be resolved to the names of specific system Libraries in use at your shop (COBOL compiler, CICS, DB2, IMS and IDz Runtime Libraries)

93

zUnit Property / PROC UsagezUnit dynamically generates, builds & runs Test Cases – on your LPAR

It can accomplish this only by means using custom entries to your Property Group and PROCs

• JCL

• JOB Card that can be submitted & run in your LPAR

• Other JOB statements: //JOBLIB, JCLLIB, etc.

• COBOL:

• SYSLIB

• Language/Compile libraries

• Compile PARMs

• BIND statement – if DB2

• Link Edit:

• Load Libraries & Lib-path

• Link Edit specific PARMs

• IDz libraries

In turn, your Property Group entries rely on the customization of PROCs installed along with the IDz server. This is shown graphically, on the next slide …

94

Configuring for zUnit Build – Big Picture

Because zUnit dynamically Generates, Builds & Runs Test Cases the IDz server infrastructure must be configured correctly by your Systems Programmers – including references to: IDz System PROCs, Runtime Libraries, your Property Group(s) and your standard Build Runtime Libraries

IDz/ADFz

PROCsELAXFCOC

ELAXFLNK

ELAXFGO

AZUZUNIT

AZUZDB2

Standard

IBM Build

RuntimesCOBOL, PL/I, DB2

IDz/ADFz

Runtime

Libraries

Property

Groups

JCL tab points to PROCLIB

COBOL tab file tailors ELAXFCOC

Link tab file tailors ELAXFLNK

zUnit tab file tailors AZUZUNIT

zUnit tab file tailors AZUZDB2

95

The IDz/ADFz installed PROCs must be customized by Systems programmers so that various DSN= entries point to the correct LPAR System/Runtime Libraries

• There are a number of ways to do this: SET statements, Symbolics, etc.

• Property Groups can be used to specify additional Library DSNs

• Shop-specific Compile/Link PARMs may also need to be verified/customized

Configure IDz/ADFz Installed PROCs

//COBOL EXEC PGM=IGYCRCTL,COND=(4,LT),REGION=0M,

// PARM=('EXIT(ADEXIT(ELAXMGUX))’,

…

//STEPLIB DD DISP=SHR,DSN=YOUR.SHOP.COBOL.SIGYCOMP

// DD DISP=SHR,DSN=YOUR.SHOP.IDZ.RUNTIME.SFELLOAD

// DD DISP=SHR,DSN=YOUR.SHOP.CICS.SDFHLOAD

// DD DISP=SHR,DSN=YOUR.SHOP.DB2.SDSNLOAD

// DD DISP=SHR,DSN=YOUR.SHOP.DB2.SDSNEXIT

SFELLOAD

SDSNLOAD

SDSNEXIT

SIGYCOMP

SDFHLOAD

Your shop’s standard IBM System Libraries

ELAXFCOC: IDz COBOL Compile PROC

96

Property Group Customization – 1 of 2

Because IDz generates code for Test Cases then Builds and Runs the Test Cases, you will need to customize the Property Groups:

• PARMS (Options)

• Additional Libraries, DSN Overrides

• Specific Load Modules

• Default DSNs

DSNs in the IDz PROCs are overridden by individual user Property Group DSNs

JCL Tab COBOL Tab

97


Libraries you will need to discover with the help of your System Programmer(s)

Link Tab

98


zUnit Tab

99



▪ zUnit Development


▪ Appendix

100

Workshop – Prerequisites and zUnit Preferences

Software:

• IDz Client and Server v14.1.1 or later (point releases)

Skills:

You must have successfully completed formal IDz training, and:

• You must have used IDz in production work for at least 6 months

• You will need a minimum of 2 year’s production COBOL work on z/OS

Workspace preferences that should be considered before doing the labs:

• Check whether the test target load module exists – is crucial, and is on by default

• Enable clean up … will delete the AZU*** Library member entries – and is recommended for this course

101

Workshop 1 – Overview

What you will do:

1. Setup for the hands-on labs in this course

2. Develop Unit Tests for the education programs in the sample Workspace

• Use the zUnit Automated Testing Framework to generate a Test Case

• Which includes Entries that contain Assertion logic that unit tests your program

• Customize the SETUP and Test programs

• Compile & Link the Test Case

3. Execute the Unit Test

4. Interpret/Analyze results

102

Workshop Setup

In this first workshop, you will:

1. Launch IDz pointing to a brand new workspace

2. Connect to IDz Server/Host

3. Import the Property Group and associate it with your Workspace (one-time task)

4. Allocate the datasets needed for all of the workshops (also a one-time task)

5. Understand the target program (EBUD00) - which does simple date validation

6. Compile/Link the program using Generate JCL for Compile/Link

7. Run the wizard to Generate, Build and Execute a Test Case

8. Verify results - in the AZURES file, and in the Batch Job SYSOUT

(OPTIONAL – but recommended) Create an MVS Subproject – to hold

the disparate COBOL and JCL files which are used throughout the labs

103

Allocate Libraries

Launch IDz and allocate the following files. Use your TSO ID as the high-level qualifier:

1. The AZU* libraries have the following DCB:

• LRECL: 16383

• BLKSIZE: 32760

• RECFM: VBA

• Library Type: PDSE

2. .COBOL, .CNTL, .DBRMLIB .COPYLIB, .OBJ libraries are all: FB/LRECL: 80

3. LOAD (for Test Case) is a PDSE Load Library

4. LISTING is: FBA/LRECL: 133

5. SYSDEBUG is: FB/LRECL: 1024

104

IBM ships a batch job (AZUALLOC) which uses IEFBR14 to correctly allocate the AZU**** XML Libraries, as well as Libraries for COBOL, JCL, Listings & Test Cases

Steps:

• Edit the JCL

• Modify the Job Card according to your shop standards and JCL symbolics

• Note that the &SYSUID is the default high-level-qualifier

• Check out the SPACE parameters for the files –

• Note that SMS is not used in the job

• Run the Batch Job

• Note that if any of the named Data Sets to be Allocated exist, the IEFBR14 fails

• Validate results

Note that the source for AZUALLOC is in the PPT Notes

(Optional) Allocate AZU**** Data Sets using the AZUALLOC Batch Job

Allocated Data Sets

105

Once the files are downloaded, unzip them into a folder on your PC

There will be five subfolders: cbl, cpy, files, jcl and sql

Open each subfolder. Copy and paste the files from the folder into the associated source PDS:

cbl ➔ <HLQ>.ZUNIT.COBOL

cpy ➔ <HLQ>.ZUNIT.COBOL

jcl ➔ <HLQ>.ZUNIT.CNTL

sql ➔ <HLQ>.ZUNIT.CNTL

Copy each of the files from the files folder and paste them on top of My Data Sets

in Remote Systems

You will be walked through an IDz file allocation dialog for each dataset. All three files have the same DCB:

• Sequential

• Fixed Block: FB

• LRECL: 100

Copy Files & Property Group – Optional: Create an MVS Subproject

Download the following files from developerWorks:• Property Group file: https://www.ibm.com/developerworks/community/files/app#/file/00408ee2-9cca-4b1e-9ff5-7b4f148d9f93

• Source code files: https://www.ibm.com/developerworks/community/files/app#/file/e2ee8455-0dc7-4bb0-9cee-706333eaebcc

https://www.ibm.com/developerworks/community/files/app#/file/00408ee2-9cca-4b1e-9ff5-7b4f148d9f93

https://www.ibm.com/developerworks/community/files/app#/file/e2ee8455-0dc7-4bb0-9cee-706333eaebcc

106

Import the Property Group

Step 1. From the Property Group Manager, Import the Property Group file that you downloaded:

zUnit Property Group.xml ***

Step 2. Associate the Property Group to MVS Files

Step 3. Open and browse through the Property Group specification tabs for:

• JCL

• Run

• COBOL

• Link

• zUnit

*** Note that you may have to create your own Property Group file for class

Import the correct

Property Group for your

IDz Client Version

107

Workshop 1 - EBUD00 - a Simple Date Validation Routine

From your MVS Subproject open the <HLQ>.ZUNIT.COBOL library open EBUD00 in the editor, and review its simple date validation logic. Use split-screen (Ctrl+2) to view multiple areas of the program and understand what Linkage Values are sent and what are returned - and why.

108

Workshop 1 - Compile/Link

EBUD00

Close your EBUD00 edit session, and from your MVS Subproject:

1. Right-click over EBUD00

2. Select Generate JCL for Compile Link

3. Submit and Locate the Job

4. From JES, check the Job and Step Return Codes

• You will receive an [ABEND U0102] - because the Property Group is setup for DB2 – and the generated BIND step fails… which is expected

• Also, the first time you compile into this new Load Library the LKED:LINK step may not return with [0000]s. If this happens:

1. Right-click on the JES Output

and select Resubmit

2. Check the LKED:LINK return

codes (should be 0s)

Successful Compile and Link should create an executable (Load Module) in your ZUNIT.LOAD library ➔

109

Workshop 1 - Create the Test Case - Using the IDz Wizard - Part 1

Right-click on your source program and select:• z/OS Automated Unit Testing Framework(zUnit)


See Slide Notes – or contact IBM for the source code – for this example

You must fully

understand the

procedural logic in the

program you want to zUnit

test before jumping into the Test Case

wizard and building Entries

110

IDz will fill in the following:

• Data set name from the Property Group

• Member name (by adding the letter “T” as a

suffix to the selected program

• You can override (over-type) the

Member name

You can enter• Test case ID – (optional – typically associated with an

RTC Work Item or Endevor CCID, etc.)

• Test entries

• Entry Name is the 8-character MVS name

• Test Name is a an optional annotation for

the Unit Test

• Click Edit Test Entry Data…

• If your program contains Copybooks

(dependent files) you should import them


111


• IDz will render all of the data items in

EBUD00’s LINKAGE SECTION as a

spreadsheet

• You fill in the:• Input values to your Unit Test

• Expected output values from the call to

your subroutine

• Note that your Entry values must be:• Type compatible

• And range compatible with the variables

Suggested values for your first run

112

Save and Build the Test Case

• When you are finished specifying

Test Case Entries click the

Generate Programs… icon on

the toolbar

• You will be prompted to finish the

Wizard:



The build occurs on z/OSThe Test Case executes on

z/OS

113

Run the Test Case

At the Run As Test Case dialog, you can:• Rename the config/results member names

• And/or overwrite config/result members – if

they exist in the PDS

Let IDz Locate the Job for

you…

IDz will also open the

Member named from the

Wizard in an Editor – so that

you can view results

114

Evaluate results

The wizard shows the Test run results in an editor

The JES Jobs should be

expanded – and you’ll want to

look at SYSPRINT and SYSOUT

115

Evaluate results – Batch job information

SYSPRINT

displays the Test

Runner

SYSOUT - displays the:

• Names of the Test Case internal modules.

• Any COBOL DISPLAY data

116

Workshop – Discover reason for failed Assertion

If the program returns different values from your Test Case/Entry values:• The Unit Test will fail – with a

return code of “4”• You can find the specific value

that caused Test Case compare to test false the *.azures report

117

Optional Workshop– Run Code Coverage

To Run Code Coverage:

• Right-click on EBUD00.cbl

• Select z/OS Automated Unit Testing Framework ➔ Code Coverage…

• Select (check) the boxes to overwrite your azucfg and azures files

• Click OK

• And wait for the Code Coverage report to complete

Code Coverage Report

Code Coverage details for EBUD00

118

What if something went wrong in the workshop??

• First - look for syntax errors in the code (within Edit)

• Second - ensure that EBUD00 and the Test Case compiled and linked successfully

• Third - make sure that you’ve got the Assertion logic coded correctly

• EBUD00 returns a -1 if the date is not valid. • Check all of the values in your Test Case/Entry XML

• Finally - while it’s possible to Debug the Test Case, that topic and the workflow-process to use Debug is out-of-scope for this class.

• So don’t hesitate to add strategically placed DISPLAY statements, and look for them in the Batch job’s SYSOUT

119

Workshop 2 - Unit Test a String Length Subroutine

Repeat the steps from the previous lab to create and run a zUnit Test on the COBOL program: STRLTH

• Study the STRLTH code - which calculates the length of a string variable

• Open <HLQ>.ZUNIT.COBOL(STRLTH) in the editor and review its simple length calculation logic

• In order to understand this program utilize split-screen (Ctrl+2) to view multiple areas of the program at once - or use Editing Filters

• Close your STRLTH edit session before continuing

• Compile and Link STRLTH to your <HLQ>.ZUNIT.LOAD library• From Remote Systems:

• Right-click over STRLTH• Select Generate JCL for Compile Link• Submit and Locate the Job

• From JES, check the Job and Step Return Codes

Successful Compile and Link jobs should create executables (Load Modules.exe) in <HLQ>.ZUNIT.LOAD library

120

Workshop 2 – Create, run and evaluate your Test Case

zUnit Steps:

• Run the wizard to Generate, Build and Execute a Test Case for STRLTH

• Follow the wizard

• Enter values for the string text and resulting return string length

• As you did with EBUD00, save and follow the wizard to complete the zUnit workflow

• Verify results - in the AZURES file, and in the Batch Job SYSOUT

121

(OPTIONAL) Workshop 3 - Multiple Date Validation Tests

Repeat the steps from the previous workshops to create and run a zUnit Test on the

COBOL program: DTEVAL

• Study DTEVAL - which is a Gregorian date validation routine that returns different values

to the calling program based on the data passed in.

• Note that DTEVAL has bugs in the code that zUnit testing will reveal.

• Compile and Link DTEVAL

• Generate a Test Case with five (5) Entries (5 individual tests):1. Non-numeric date

2. Invalid CCYY

3. Invalid Month

4. Invalid Day

5. Valid Date

Name the Test Case and Entries anything you wish

• Complete the coding for your Test Case• Using the Snippets and custom code:

• Modify the Test Case’s SETUP subprogram, and initialize Linkage Variables for

the five tests

• Modify each of the five generated Entry subprograms using the Test Script

Pattern Snippet to run and evaluate Assertions for the above tests

• Compile and Link your Test Case

• Execute your Test Case interactively - and validate your results

122

Workshop 4 - Unit Test a Program that calls two other subroutines

Repeat the steps from the previous workshops to create and run a zUnit test on the COBOL programs: EBUD01, EBUD02 and EBUD03

▪You will need to:

1. Understand the subroutine set, which does date validation, manipulation and date math

2. Compile/Link the three COBOL programs

3. Run the wizard to generate a Test Case

4. Compile/Link your Test Case

5. Execute the Test Case Load Module using the z/OS Automated Unite Testing Framework

6. Verify results; In the AZURES file, and in the Batch Job SYSOUT

Detailed steps follow on the next slides…

123

Workshop 4 – Study the EBUD01, EBUD02, EBUD03 Date Validation Routines

From your <HLQ>.ZUNIT.COBOL library open EBUD01, EBUD02 and EBUD03.CBL in the editor, and briefly review their CALL and date processing logic

• There are three logic routines:

1. Date Validation

2. Date Math (days difference from current date)

3. Date Calculation (given someone’s birthday calculate when they can retire)

124

Compile and Link EBUD01,

EBUD02 and EBUD03

From Remote Systems:

• Right-click over EBUD01

• Select Generate JCL for Compile Link

• Submit and Locate the Job

• Check the Job and Step Return Codes

• Repeat for EBUD02 and EBUD03

• If your compiles are taking some time to complete, you can fire off additional Generate JCL steps - because IDz multi-threads

• Successful Compile/Link runs will create executables (Load Modules) in your ZUNIT.LOAD library

125

Workshop 4 - XML Editing Techniques – EBUD01 XML Entries

Generate a Test Case for EBUD01 and create four Entries for this Test Case:

1. DATEGOOD

2. DATEBAD

3. DATERETR

4. DATECALC

You can add these Entries from the initial Wizard screen, or from inside the XML Editor, using:

• Add Entry

• Edit Entry

• Once EBUD01 is loaded into the XML Editor – click:

• Collapse all

• Expand to parameter

• Expand all

Note the effect on the Editor

• Select Show entry columns

• Select/De-select several options.

• Click OK and note the effect

Website to calculate Retirement Date:

https://www.timeanddate.com/date/dateadded.html?m1=01&d1=01&y1=1952&type=add&ay=65&am=&aw=&ad=&rec=

https://www.timeanddate.com/date/dateadded.html?m1=01&d1=01&y1=1952&type=add&ay=65&am=&aw=&ad=&rec

126

Workshop 4 - XML Editing Techniques – EBUD01 Entry Values

• Manually edit an initial set of entry values in the L_CCYY, L_MM, L_DD fields for DATEGOOD

• Select/Copy/Paste DATEGOOD Input and Expected field values into the rest of the Entries

Modify the values: As shown here…………………………………………………….………………

• Generate the Test Case, and zUnit test EBUD01. Validate your work

127

OPTIONAL WORKSHOP – Utilizing a Spreadsheet for XML Entries

• From the Test Case, Select and copy all of the Entry values

• Open MS-Excel and paste the values into a spreadsheet

• For any “0x” values, format the cells as Text

• Add custom Entry headers

• Delete the existing Test Case Entries, and Copy/Paste the values from Excel

• Generate the Test Case, and zUnit test EBUD01. Validate your work

128

Workshop 5 - Unit Test a Program with complex logic and with a Copybook

Repeat the steps from the previous slides to create and run a zUnit Test on the COBOL subroutine: SAM2

Steps:

1. Start by Compiling/Linking SAM2

• Use Generate JCL for Compile and Link – and validate the return code

2. Take a minute to study the subroutine’s logic, which includes a number of processing options and edit validations

3. Run the wizard to generate a Test Case for SAM2

• Add specific XML Entry values (these are shown in the slide)

4. Compile/Link your Test Case

5. Execute the Test Case Load Module using the z/OS Automated Unite Testing Framework

6. Verify results - in both the AZURES file and the batch Job SYSOUT

Detailed steps follow on the next slides…

129

Workshop 5 – Study SAM2 - a field validation subroutine

• After you have successfully Compiled/Linked SAM2, from your <HLQ>.ZUNIT.COBOL library open SAM2 in the editor, and spend a few minutes studying the data editing logic based on the incoming parameters

• Open the copybook: CUSTREC. Also study the: TRANSACTION-RECORD fields

• Look for clear paths to Unit Test Assertions. Specifically, follow the variables: TRAN-CODE, TRAN-OK, TRAN-MSG and TRAN-UPDATE-NUM - use Occurrences in Compilation Unit

130

Create, Build and Run a Test Case for SAM2

• Create a Test Case for SAM2 utilizing XML Entry values the same as (or similar to) the following ➔

• After you’ve finished editing your Entry: Generate, Build and Run your Test Case

• Validate results using the AZURES member and batch output (SYSOUT and SYSPRINT) display values

131

OPTIONAL Workshop: Create, Build and Run a complex Test Case for SAM2

SAM2 actually has a large number of data edit/operations. To Unit Test this code you have to know enough about the program’s behavior to initialize values. Here’s a sample…………..

You can feel free to experiment Unit Testing SAM2. In the above screen capture we have: 1. Added a second Entry, 2. Deselected ENTRY1 and Collapsed some of the XML structures (for easier editing), 3. Typed in specific values to test for certain results, etc.

• When you are finished; Generate your Test Case, Build and Run the Unit Test. Validate results using the AZURES member, and batch output (SYSOUT) display values.

Important Note: SAM2’s editing paragraphs have

numerous bugs

132

Workshop 6 - PERFCALC Data Import – Process

The PERFCALC program reads an input file (CUSTMAST). Then calls a subroutine (CLCTPCTB) passing a record with field values that are compared against high watermark sales figures; in total and from a previous year. You will use zUnit to test the expected returned high sales figure against what the subroutine calculates…

Let’s get to work ☺

1. Start by creating an MVS File Filter for DDS0001.TEST.CUSTMAST

• This is the input file from which you will Import records.

2. Compile/Link two programs in this order (what’s significant about the order)?

• CLCTPCTB

• PERFCALC

3. Create and run a zUnit Test Case for PERFCALC – following the steps on the next four slides

133

Workshop 6 - Create the Test Case

Delete the default

ENTRY1 Test entry

Click: Edit Test Entry Data…

In the Editor: Click the Import Test Data… icon

Create a Test Case for PERFCALC ➔

As an aside, note that there are two

parameters PERFCALC passes to

CLCTPCTB. In the XML Entry Editor these

are described as; Parameter [Index=1]

and Parameter [Index=2]

134

Workshop 6 - Import the QSAM Test Data Records

From Import Test Data• Select CUSTMAST

• Specify 10 records

• Click Browse

From Browse For File➔• Navigate to

DDS0001.ZUNIT.CUSTMAST

• Recall that you need to

setup an MVS File Filter

for this

• Select the file

• Click OK

135

View the data records

Im

po

rte

d R

eco

rd

s

• A batch Job will launch

to compile/link/run a

process that extracts

your specified number

of records from the

QSAM file into the

AZUTDT dataset –

and into the XML Entry

editor

• The record data will be

laid out in the Entry

editor according to

your program’s

schema for the file

layout

• The Entry will be

named (by default)

AZUE0000

136

Workshop 6 - Modify the Imported Data in the XML Entry Editor

Using the techniques described in the last section, edit a few of the records to create values as shown in several of the CUSTOMER_MASTER_RECORDstructures

** Note that I have collapsed CLCTPCTB from the XML Edit fields

Copy paste the values into the LS_MAXIMUM_FIELDS

Generate, Build and Run the zUnit Test Case

Note: The subprogram (CLCTPCTB) finds the highest sales number this year - and the most improved sales number from the records fed into it.

As an optional exercise return to the Entries in the XML Editor, and create wrong values in LS_MAXIMUM_FIELDS

Again Generate, Build and Run the zUnit test case (the assertion should fail)

If you are having problems finding Expected values for your zUnit Test Case see the next slide….

137

Open the SYSOUT from the RUNNER step – to help you understand the stub values

The SYSOUT from the RUNNER step will show you what values were calculated by the programs

138

1. Open your Property Group file, and from the COBOL tab, check the box for the DB2 Runtime environment:

• Verify that you have allocated: <HLQ>.ZUNIT.DBRMLIB

• Save your changes

2. Build PHONEC1.CBL using Generate JCL

• Note that you will not actually BIND a DB2 Plan for PHONEC1 – and instead, will execute DDS0001.PHONEC1

• This means that the batch job to Build PHONEC1 will fail in the BIND step – however, Precompile/Compile/Link will work to produce a Load Module

Workshop 7 – Working with DB2 – Initial Steps

This workshop uses a COBOL program called: PHONEC1, which requires a copybook: RDZDCLSBoth of these are available from the DDS0001.ZUNIT.* datasets

139

3. Go through the standard the Generate Test Case dialog – to create a zUnit test Entry for the Subroutine’s LINKAGE SECTION

• Be sure to jot down the name of the Test Case

4. Generate and Build and Run your Test CaseNote – if you are using RDz v9.5 you will Generate & Build, but not Run the Test Case

Workshop 7 – Edit and Generate the Test Case

He

re a

re s

om

e s

am

ple

va

lues

140

Workshop 7 – Create the Test Runner Configuration ** RDz v9.5 only

1. Right-click over the COBOL program and select:

• zUnit Framework ➔ Generate Runner Configuration…

2. Select the AZUCFG library and name the Configuration (and remember the name)

3. Select the Test Run options (Typically you check all of the boxes)

• Save your work

• Close the config editor

1.

2.

3.

141

Workshop 7 – Run your DB2/zUnit Test ** RDz v9.5 only

Copy DDS0001.ZUNIT.CNTL(RPHONE1) into your ZUNIT JCL library’

• Change all DDS0001 to your TSO ID

• Submit the JCL

• Verify the batch run (see next slide for details)

Note if you are using zserveros … Standard DB2 BIND/EXECUTE rules will occur when you run. Meaning that you may get a -805 (shown as 80N in the SYSOUT) when you run the test.

This means that this zUnit/DB2 program ran – but that you’re not authorized for the DB2 PLAN Execution

142

Workshop 7 – Validate the DB2 / Unit Test

The SYSOUT Spool file from the job displays of SQLCODE and other results

So will DB2 Table browsing – ask your instructor to validate your table update

143

Workshop 8 – Creating Stub programs – Copy Programs

In this workshop you will utilize a copy of the PERFCALC and CLCTPCTB programs to learn how to create and use Stub programs in your zUnit testing.

Note that this is necessary only if you wish to preserve your previous work…

Steps:1. From <HLQ>.ZUNIT.COBOL;

1. Copy CLCTPCTB ➔ CLC2 and PERFCALC ➔ PERF2

2. Build CLC2 and PERF2 in this order (build CLC2 1st then build PERF2)

3. Validate the results for (0 or 4 compile & link)

144

Workshop 8 – Creating Stub programs – 1 of 6

1. Generate a Test Case for PERF2

• Import one record from DDS0001.ZUNIT.CUSTMAST• Note that you won’t be using the record during this lab … but if your testing required importing

QSAM data records to provide values for your Test Case entry, you could do so

2. Modify the values of the CLC2 fields and the LINKAGE for PERF2 as shown on the next slide

3. Generate Programs as…

• Check the box to stub out CLC2

• With the box checked IDz will stop the Generation process and let you know that you need to rebuild CLC2

4. Build CLC2 then Build PERF2

• You rebuild PERF2 only because the modules are statically linked

5. When the rebuilds complete; Right-click over PERF2 and

• Select: Build Test Case

• When prompted select: Run Test Case

145

Workshop 8 - Editing the stub program – 2 of 6

From the screen capture, you can see that we have added values to the fields for the second Parameter [Index=2] in the call from PERF2 ➔ CLC2

And we’ve Copied/Pasted those same values in Record1 – which will be evaluated by the zUnit process (Assertion values)

Generate Programs...

When prompted, save changes

Note that the Imported record contains the values for testing when CLCTPCTB is called without being Stubbed. Your Unit Testing run should not be affected by these (you can verify using: RUNNER.SYSOUT)

146

Workshop 8 – Generate the CLC2 stub program – 3 of 6

After you click the Generate Program icon – the wizard will present you with this dialog ➔

Check the box for CLC2 ➔

During the generation process you will be prompted to build CLC2

147

Workshop 8 – Build CLC2 and PERF2 – 4 of 6

• Generate JCL for CLC2 ➔

• Note that CLC2 shows up in the library specified in your Property Group/zUnit tab

• Using the samples from

class the CLC2 stub is

generated into: <HLQ>.ZUNIT.GEN.COBOL

• Run the generated JCL

• Check the JES return codes

• And if good (0 or 4) Re-build the calling subroutine

• Rebuild PERF2 – and verify Batch Job return codes for the Compile/Link

148

Workshop 8 – Build and Run the Test Case for PERF2 – 5 of 6

Time to finish…

• Right-click over PERF2 and select; Build the Test Case

• Do not Generate the Test Case – that’s already been done by the Wizard in a previous step. Generating the test case created your Stub program with your zUnit test values

• If there are no Build problems the wizard will prompt you to Run the Test Case…

• Do so – and verify your results in the JCL – and the AZURES result

149

Workshop 8 – Look at CLC2’s generated code – 6 of 6

Optionally – you might open the generated Stub program to understand how the Entry XML Wizard values are transposed into COBOL code:

• Alphanumeric (PIC X) fields become structures in WORKING-STORAGE

• Numeric values become literals

• Both are moved to the corresponding fields – that you edited in the XML

150

Workshop 8 – Return and change the Test Case values in the Stub

From Generate Test Case for PERF2:

• Overwrite the existing Target test case member name

• Edit the Test entry data

• Change the values those shown in the screen capture ➔

• Note that these incorrect

values will test false

when run in zUnit

• Generate the Test Case

• Check the box to generate CLC2

• Build CLC2 and validate the return code

• Build PERF2 and validate the return code

• Build and Run the PERF2 Test Case

• Validate results

• The batch job should finish with a 4 MVS Return Code

• The Test case should fail

151

• Extensions to zUnit in order to support “monolithic” (standalone) batch modules, executing like traditional “black box” tests

• Data sources for program input and for output files

1. Specify DSN of existing QSAM/VSAM data file

2. Import Data from existing QSAM/VSAM file into the Test Data wizard

3. Specify (hand-code) field values within records – in the Test Data wizard

• Can “mix & match” file I/O combinations any of the above data sources

• Maximum flexibility

• Simplifies test data value specification and reuse

• Can create test data for external/alternate testing purposes

• For a given Test Entry:

• When both input and output file data uses existing QSAM/VSAM datasets, zUnit invokes MVS SuperC utility

• When either the input or the output file data is imported or hand-coded as values in the Test Data wizard zUnit comparisons are done on a record-by-record/field-by-field basis

Workshop 9 – Unit Testing Standalone Batch Programs – Concepts 1 of 4

152

Standalone Batch zUnit Testing – Development Process

Runtime

• Specify input file DSN…or…

• Enter Input test data values…or…

• Import Input test data values

Specify Unit Test Input Values or File(s)

• Specify Output file DSN…or…

• Enter Output test data values…or…

• Import Output test data values

Specify Unit Test Output values or

File(s)• Output records from Batch

program captured in new Dataset – created by zUnit

• Program Output File(s) compared to existing Output File(s) using the MVS “SuperC” utility

Generate Test Case

Build Test Case

Run Unit Test

Evaluate Results

(File Compare)

2. Execute zUnit Test

1. Design Unit Test


153

Note that the Call to ISRSUPC is embedded in the generated Test Case PROCEDURE DIVISION code

Runtime (Execution Flow)

Emulates standard batch program testing – but provides ability to customize Input / Output file values. Evaluates Unit Test results, based on expected...vs... produced data records

zUnit Test Runner

Run Test Case:• Input - Output File DSNs part of

generated Test Case code

……

Evaluate Test Results• Test Case code calls SuperC File

Compare – passing DSN for expected results

• This file is compared to the output data records created by the Test Run

z/OSInput DSN(s) and/or

Record Values

Output Dataset(s)

Produced by Batch

Program

Execute Batch PGM

RunBatch

Program

Evaluate SuperC

File Compare

Unit TestSuperC

File Compare

Expected Output

DSN(s)

Execute ISRSUPC

1.

2.

3.

4.


154

After running the batch job, IDz

executes a SuperC file compare

against the output files produced

vs. files you identify with

expected results

zU

nit G

en

era

ted

JC

L

USER170.ZUNIT.IO.TOURFIL3.OUTPUT

..compared to existing/regression test dataset

USER170.ZUNIT.OLD IO.TOURFIL3.OUTPUT

The test – including EXEC ISRSUPC

was generated by IDz

Batch Program


155

Workshop 9 – Unit Testing Standalone Batch – Workshop Steps 1 of 6

In this workshop you will unit test a main batch program TOURFIL3 – A nested COBOL program*** which writes a QSAM (sequential) output file based on values read from an input file

Steps:1. From your COBOL library:

1. Open TOURFIL3.cbl and browse through the program logic

2. Using Generate JCL for Compile/Link build TOURFIL3 – to create a load module

Validate the results for (you should get a 0 or 4 compile & link MVS return code)

2. Go through the process to Generate a Test Case for TOURFIL3 that you followed in Workshop 6

• CHECK-CODE: N

• Check: Set File Test Type … and select:

• TOURDATA-INPUT-FILE <ID>.ZUNIT.TOURFIL3.INFILE

• TOURDATA-OUTPUT-FILE: <ID>.ZUNIT.TOURFIL3.OUTFILE

See the next slide for a close-up of the Testcase Entries

*** zUnit supported Nested COBOL programs as of v14

156

Workshop 9 – Set File Test Type (Select Files) – 2 of 6

From the screen capture you can see the test case values:

• N in CHECK-CODE

• For the datasets

• Select: Set File Test Type..

• Browse to and select the INPUT file and the ‘EXPECTED’ output file

157

Workshop 9 – Generate Program – 3 of 6

• From the toolbar, select: Generate Programs As…

• Save your work

• Generate, build, and run test case

Note that

158

Assuming you’ve copied the program code & data files correctly – and specified the Test Case correctly TOURFIL3 should pass unit test

Expand the Test Results, Select Test ENTRY1 and select: Shoe file compare result

Workshop 9 – Verify Results – 4 of 6

159

Change the Test Case values in the Expected Data Set – 5 of 6

• Right-click & copy <ID>.ZUNIT.TOURFIL3.OUTFILE

• Right-click and Pate on <My Data Sets

Name the new file: <ID>.ZUNIT.TOURFIL4.OUTFILE

• Edit <ID>.ZUNIT.TOURFIL4.OUTFILE

• Modify a few of the records in the file

• Save your work

160

Change the Test Case values in the Expected Data Set – 6 of 6

• Modify the Test Case, change the output DSN to <ID>.ZUNIT.TOURFIL4.OUTFILE

• Note that you can simply overtype the DSN in the matrix

• Again select Generate programs and run ➔

• This time you should get a 4 MVS Return Code

• From Runner Results, Show file compare results

161


Appendix

162



▪ zUnit Terms, Vocabulary, Run-Time Architecture

▪ zUnit Development Process

▪ zUnit Program Model - Deeper Dive

▪ Maintaining your Test Case


▪ Futures


▪ Appendix

163

Review - zUnit Component Implementation

Test RunnerA z/OS systems program developed by the IDz team, and installed with IDz. The Test Runner orchestrate the unit testing process

Test CaseA generated COBOL or PL/I program compiled into a Load Module that calls your target Subroutine. Test Cases are executed

(Called) by the Test Runner

Test Suite An XML file that provides a list of Load Modules to be executed by the Test Runner

Assertions COBOL or PL/I conditions that test individual units of source code in your program

EntryA generated set of COBOL or PL/I programs that implement the xUnit framework standard; for setting up, running and tearing

down individual Unit Tests

Test Execution z/OS JCL that invokes the Test Runner

Test Execution //JCL

Test Runner - IDz zUnit run-time

Test Suite - List of Test Cases (Load Modules)

Test Case - Generated COBOL or PL/I program

Entry - Generated COBOL or PL/I programs

Assertions - Conditional Expressions

coded in COBOL or PL/IYour program and the

logic to be tested

Test Results

(XML File)

IDz substitutes generated z/OS-specific resources for distributed technology classes, and frameworks.

EXEC PGM=

OPEN INPUTREAD Test Suite

Which identifies Test Case Load Module

The Test Runner CALLs (interacts with)Test Case Load Module

Which contains Entries(COBOL subprograms or PL/I procedures

Each Entry sets up and CALLs(executes) individual Unit Tests andreleases unit test resources (Tear Down)

Makes

Submit JCL

164

JES

Review - zUnit Run-time Architecture

zUnit Test RunnerWhich does the following:

READ Test SuiteCALL (invoke) Test Case

Invoke EntryInteract with different nested COBOL

subprograms or PL/I procedures within your

Test Case to:

- Setup unit test variable values - Run a test.

- Evaluate the Assertion outcome- Release system resources

Generate Results File

//AZUCFG DD DSN=…

• Names the Test Case module(s)

//AZURES DD DSN=…• Stores test results in XML PDS member

// EXEC PGM=Test Runner//AZUCFG ➔ Test Suite//AZURES ➔ Test Results//…Test Case Load LibraryLaunches…

Submit JCL…

Test Case

Load Module to be unit tested

• Verifiable logic routine• Verifiable logic routine• Verifiable logic routine

Test Execution

Entry- SETUP Linkage Variables

- Run Unit Test Assertion Logic (CALL)

- Evaluate outcome- Release resources

z/OS

Test Suite

Target SubroutineTest Results

165

Test Case Program Structure – Initialization

UNIT0001(...)

ADDTESTS(...)

SETUP(...)

TEARDOWN(...)

TEST1(...)

TESTn(...)

. . . . . .

zUnit Test Case ModuleUSER.ZUNIT.LOAD(UNIT0001)

• Top-level initialization module: • PROGRAM-ID will be whatever you specified for the Driver program name in the Wizard

IDz generates

nested COBOL or

PL/I programs

166

Test Case Program Structure – ADDTESTS

UNIT0001(...)

ADDTESTS(...)

SETUP(...)

TEARDOWN(...)

TEST1(...)

TESTn(...)

. . . . . .


• ADDTESTS• Dynamically defines your unit tests to the Test Runner (test harness)

167

3. Test Case Program Structure – SETUP

• SETUP -

UNIT0001(...)

ADDTESTS(...)

SETUP(...)

TEARDOWN(...)

TEST1(...)

TESTn(...)

. . . . . .


Assertion Linkage value

Assertion Linkage value

Assertion Linkage valueWiz

ard

-gen

erate

d

168

Test Case Program Structure – Entries

UNIT0001(...)

ADDTESTS(...)

SETUP(...)

TEARDOWN(...)

TEST1(...)

TESTn(...)

. . . . . .


1 ➔ M Generated Entry template COBOL programs or PL/I procedures

169

Test Case Program Structure – TEARDOWN

UNIT0001(...)

ADDTESTS(...)

SETUP(...)

TEARDOWN(...)

TEST1(...)

TESTn(...)

. . . . . .


• TEARDOWN

Documents

DevOps Unit Testing with COBOL ADFz/IDz