Unit Testing COBOL. Rational Developer for System z Introduction to zunit: IDz V14. IBM Software Group. IBM Corporation

Transcription

1 IBM Software Group Rational Developer for System z Introduction to zunit: IDz V14 Unit Testing COBOL Jon Sayles / IBM - jsayles@us.ibm.com IBM Corporation November, 2017

2 IBM Trademarks and Copyrights Copyright IBM Corporation 2008 through All rights reserved by IBM including the right to use these materials for in-house IDz technical instruction (please contact for permission) 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. 2

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 Venkat B. IBM/IDz Development Lead Reginaldo Barosa IBM Client Technical Professional Zvi Weiss IBM Client Technical Professional Mark Boyd IBM Client Technical Professional 3

4 IBM Doc for zunit 4

5 UNIT zunit Testing with IDz zunit Terms, Vocabulary, Run-Time Architecture zunit Development Process 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 Course prerequisites: Two+ years of production z/os COBOL application development or maintenance Formal IDz training + six months of regular IDz usage Installed IDz Client software and access to IDz Server at versions or higher 5

6 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, usage procedures, and operating procedures are tested to determine if they are fit for use. Wikipedia 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 Co-pay calculation This method of testing is sometimes called white Box testing (See Slide Notes for more on White Box Testing) 6

7 Black Box (traditional z/os) Testing Black Box Testing examines the functionality of an application (what the software does) without regard to its internal semantics (how the program does what it does) Analyze Input Black Box Analyze Output Classic Example - Batch File Maintenance Testing Analyze Data Files Run File Update Program Verify Changes to Data Files QSAM DB2 or IMS VSAM QSAM Note that IDz 14 generates, builds and runs traditional Batch File Maintenance Unit Tests DB2 or IMS VSAM 7

8 What is zunit? (v9.5 and Prior Releases) z/os zunit Test Runner Test Cases - Date Validation Internal Table Lookup Address Validation State Tax Calculation zunit is IBM s implementation of the xunit component framework for unit testing z/os programs LINKAGE SECTION values Call-able Subroutine Date Validation Routine Internal Table Lookup Address Validation State Tax Calculation Call-Able Subroutine QSAM/VSAM GDG Files DB2 Tables zunit s White Box Testing allows you to test and evaluate specific application methods/functions and routines- as opposed to program outputs. During White Box testing, code is run with predefined input values that validate specific output results values. 8

9 Current zunit Support IDz v14 A compiled/linked z/os Load Module written in COBOL or PL/I: Call-able subroutines can be zunit tested through any data values passed through LINKAGE These values are interrogated by entries called logical assertions or test assertions QSAM/VSAM file I/O is supported in the subprograms DB2 is supported, and zunit tests of call-able subprograms with embedded SQL are run via batch/jcl Assembler subroutines can be supported if you create a COBOL wrapper program for their Call interface Support for zunit testing of COBOL main or standalone programs is available in beta: File I/O black box type testing SUPERC dataset comparisons Customized value entry editing Support for CICS and IMS applications is under development 9

10 Standalone Batch Module zunit Support 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 10

11 Standalone Batch zunit Testing Development Process Runtime 2. Execute zunit Test Specify input file DSN or Enter Input test data values or Import Input test data values Specify Unit Test Input Values or File(s) 1. Design Unit Test Specify Unit Test Output values or File(s) Specify Output file DSN or Enter Output test data values or Import Output test data values 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) 11

12 Testing Main Batch Programs a closer look Emulates standard batch program testing but provides ability to customize Input / Output file values. Evaluates Unit Test results, based on expected...vs... produced file records z/os Input Dataset(s)/Values Output Dataset(s) Produced by Batch Program 2. Run Batch Program Execute Batch PGM Expected Output Dataset(s)/Values 1. zunit Test Runner Test Cases - File Input/Output Value Input/File Output File Input/Value Output Evaluate Test Results 4. Evaluate SuperC File Compare Unit Test SuperC File Compare 3. Execute ISRSUPC 12 COBOL only and Requires Updated Client & Host

13 SuperC Output Compare Batch Program zunit Generated JCL SuperC Utility compares file output produced by Batch Job (USER170.ZUNIT.IO.TOURFIL3.OUTPUT) to existing (regression) dataset as specified in the Generation Wizard 13

14 zunit Subroutine Demo Subroutine Batch DB2 Alpha-data values in a numeric field 14

15 Other new zunit features in v14 Support for VSAM File I/O and VSAM Test Data Wizard - data file Import Previously only supported for QSAM files VSAM 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 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 used to create the zunit configuration datasets A few cosmetic/workflow enhancements to the Eclipse U.I. 15

16 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 16

17 The value of early and extensive testing 80% of development costs are spent identifying and correcting defects ** During the Coding or Unit Testing phases $80/defect During the BUILD phase $240/defect 17 During Quality Assurance or the System Test phases $960/defect Once released into production **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. $7,600/defect + Law suits, loss of customer trust, damage to brand

18 zunit and Unit Testing is Not a Silver Bullet IBM recognizes this - and provides multiple testing solutions, each optimized for different problem areas within the software testing space: GUI 3270 Regression Testing Performance Testing Interactive Testing Integration Testing Rational Function Tester Application Performance Analyzer IDz Integrated Debugger IBM Debug Tool Automated Unit Testing Test Driven Development zunit 18

19 UNIT zunit Testing with IDz zunit Terms, Vocabulary, Run-Time Architecture zunit Development Process 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 19

20 xunit Components and Terminology (Distributed Vocabulary) All xunit frameworks share the following basic component architecture, with some varied implementation details. Test Runner Test Case Test Suite Assertions Test Fixture A test runner executes test cases or test suites and makes the results available in some programmatically-consumable way (e.g., XML,...). Test 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 suites define a set of test cases for test execution. Assertions verify the behavior and state of a test case. A failed assertion should result in an exception being thrown. A 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 Execution Test Execution Test execution involves invoking the Test Runner with input that includes, among other things, which test Cases or test suites should be run. Launches Test Runner Reads from Test Suite Test Results (XML File) Which identifies Test Case 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. Which constructs Test Fixture Which contain 20 Assertions Against Your program and the program logic to be tested

21 zunit Component Implementation IDz substitutes generated z/os-specific resources for distributed technology classes, and frameworks. Test Runner A z/os systems program developed by the IDz team, and installed with IDz. The Test Runner orchestrates the unit testing process Test Case Test Suite Assertions Entries Test Execution A 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 An XML file that provides a list of Test Cases to be executed by the Test Runner COBOL or PL/I conditions that test individual units of source code in your program A generated set of COBOL or PL/I programs that implement the xunit framework standard; for setting up, running and tearing down individual Unit Tests z/os JCL that invokes the Test Runner Test Execution //JCL Submit JCL EXEC PGM= Test Runner - IDz zunit Run-time OPEN INPUT READ Test Suite Which identifies Test Case Load Module Test Suite - List of Test Cases (Test Configuration) Test Case - Generated COBOL or PL/I program Test Results (XML File) 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 and releases unit test resources (Tear Down) Entry - Generated COBOL or PL/I program Makes 21 Assertions - Conditional Expressions coded in COBOL or PL/I Your program and the logic to be tested

22 zunit Run-time Architecture JES Launches zunit Test Runner Which does the following: READ Test Suite CALL (invoke) Test Case Invoke Entry Submit JCL Interact with different nested COBOL subprograms or PL/I procedures within your Test Case to automatically: - Setup unit test variable values - Run the subprogram - Evaluate the Assertion outcome - Release system resources - Generate Results File // EXEC PGM=Test Runner //AZUCFG Test Suite //AZURES Test Results //AZULOD Load Library Entry Test Execution //AZUCFG DD DSN= Names the Test Case module(s) Test Case (PDSE) - SETUP Linkage Variables Test Suite - Run Unit Test Assertion Logic (CALL) - Evaluate outcome - Release resources z/os Test Results //AZURES DD DSN= Stores test results in XML PDS member 22 Target Subroutine Load Module to be unit tested Verifiable logic routine Verifiable logic routine Verifiable logic routine (PDSE)

23 A Closer Look at Unit Test Assertions Assertions are testing hypotheses, a pass/fail examination about how specific processing in your program is supposed to work. Here are some examples 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. 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. 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. Your JCL s DD card points to an empty QSAM file. Your JCL s DD card points to a QSAM file that contains data records. Pass in the following date : Pass in the following date: Pass in a variable value not found in the table. Pass in a variable value that is found in the table In your generated Test Case programs, Assertions are like SQL predicates: If Empty_QSAM_File and File_Status <> -4 (Assertion = Fail) If Date = and Return_Code <> -1 (Assertion = Fail) 23-4 File Status upon file open. 0 File Status upon file open. You expect a -1 return code upon GOBACK from the Subroutine You expect a 0 return code upon GOBACK from the Subroutine You expect a -8 return code. You expect a 0 return code.

24 Contains one-to-many Generated Test Cases, Entries + Assertions Test Case Target Subroutine Entry (COBOL subprogram or a /PL/I procedure) Test - Assertion/Evaluation Entry Test - Assertion/Evaluation Entry Test - Assertion/Evaluation Entry Test - Assertion/Evaluation Verifiable logic routine Verifiable logic routine Verifiable logic routine Verifiable logic routine Verifiable logic routine Verifiable logic routine 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 Entries - Entries are implemented as subprograms, nested within your Test Case 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. 24

25 Entries, Assertions and Verifiable Subroutine Logic Your Subroutine ENTRY USING LINKAGE Variables... Verifiable logic routine...do business logic Return values through Linkage that can be examined by the Entry s Assertion logic. The COBOL RETURN-CODE special register can also be used Verifiable logic routine Call Target Subroutine Passing values Return Results to Test Case Verifiable Logic is some section of code in your program that: Can be accessed independently Modifies one or more of the Assertion values passed through Linkage Returns to the calling Entry program and can be evaluated Entry-1 Call Subroutine zunit genned Test Case IF Assertion Results Entry-2 25

26 Additional Options with v9.1.1 and 9.5.x v9.1.1 & v9.5.x offer new options: XML (Test Data) Editor that controls the zunit workflow: Add/Delete Entries Copy/Paste values within Entries Collapse/Expand records Show Entry columns Import data records plus edit imported data record values Entire unit test process is wizard-driven from define values to run test case (except for DB2 sub-programs, where the test case run is done via JCL) Can Debug your Test Case: View values passed thru LINKAGE from the Test Runner/Test Case/Entries to your program Understand the control flow of the zunit generated Unit Test architecture 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 Copy values into Test Case Entries 26

27 UNIT zunit Testing with IDz Topics: Terms, Vocabulary, Run-Time Architecture zunit Development Process zunit Setup, Required Datasets, Wizards and Workflow XML Editor Options QSAM Data Import Working with DB2 Programs Stubbing out Program Calls Debugging Test Cases Analyzing Programs for Unit Testing Fit Workshop/Lab Instructions Appendix 27

28 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 28

29 Allocate the Datasets Used in zunit Work AZU libraries DCB Allocation for libraries Required AZU.* libraries 29

30 Big Picture Datasets and Generation Wizards Subroutine to be tested <HLQ>.ZUNIT.COBOL BUILD Generate JCL for Compile/Link Load Library <HLQ>.ZUNIT.LOAD Generate Test Case Test Case Wizard If program has FD File Import Wizard Runtime defaults used to execute Test Case <HLQ>.ZUNIT.AZUCFG XML Entry data used to generate Test Case <HLQ>.ZUNIT.AZUGEN Library of Imported File Data Records <HLQ>.ZUNIT.AZUTDT Library of Import file layouts (SCHEMA) <HLQ>.ZUNIT.AZUSCH zunit Generated COBOL Programs <HLQ>.ZUNIT.GEN.COBOL Test Case programs and Stub programs zunit Generated COBOL Programs <HLQ>.ZUNIT.GEN.COBOL 30

31 Big Picture Datasets and zunit Processes zunit Test Run <HLQ>.ZUNIT.AZUCFG (Test Case) <HLQ>.ZUNIT.GEN.COBOL (Test Case) <HLQ>.ZUNIT.LOAD (Subroutine to be tested) <HLQ>.ZUNIT.GEN.COBOL (Stub Program) Output results from Unit Test <HLQ>.ZUNIT.AZURES Note that you can save the JCL Job from the zunit Test Run for repeated testing 31

32 Allocate Datasets and Setup Property Group file Allocate the datasets necessary for zunit work: If using zserveros you can use Allocate Like (Create/Modify) Your Property Group file: 1. JCL tab Library for generated JCL JOB Card and JCLLIB 2. COBOL tab Standard Compilation datasets 3. Link tab specify: Link options: Link libraries: Your load library (PDSE) The LE library The Test Runner runtime-library 4. Run tab Step name/run Additional JCL for QSAM files not part of the data file import for your test cases 5. zunit tab specify: Procedures and Steps defaults for the Test Runner Generation options for the Test Cases 32

33 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 33

34 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 The IDz - zunit run-time library CSPSHR.HHOP950.V95@1.SFEKSAMP 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 Additional JCL to find the AZUTSTRX member j 34

35 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 35

36 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 36

37 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 37

38 zunit Wizard-Workflow (dev process for Generate Test Case Action) Right-click on COBOL subroutine Generate JCL for Compile Link Create Load Module for Subroutine Right-click on COBOL subroutine, select Generate zunit Test Case Generate Test Case Dialog 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 Verify Results (view output of batch run) z/os Batch Job Results (JES) 38

39 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 39

40 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) Generate Test Case 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 See Slide Notes or contact IBM for the source code for this example 40

41 Create the Test Case - Using the IDz Wizard - Part 2 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 41

42 Create the Test Case - Using the IDz Wizard - Part 3 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 42

43 All of the fields in the LINKAGE SECTION The first 01- level in the LINKAGE SECTION Group Field Elementary Fields The Test Case Entry Editor You cannot enter values into a group field You can enter values for any/all elementary data fields (PIC clause) 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 43

44 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 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 Not the variable names just copy the values 44

45 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)? 45

46 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: Build the Test Case Run the Test Case The Test Case executes on z/os The build occurs on z/os 46

47 Run the Test Case Let IDz Locate the Job for you At the Run wizard you can: Rename the config/results member names And/or overwrite config/result members if they exist in the PDS 47 IDz will also open the Member named from the Wizard in an Editor so that you can view results

48 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 48

49 Evaluate results Batch job information SYSPRINT displays the Test Runner SYSOUT - displays the: Names of the Test Case internal modules. Any COBOL DISPLAY data 49

50 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). 50

51 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 51

52 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 52

53 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 53

54 UNIT zunit Testing with IDz Topics: Management Overview Terms, Vocabulary, Run-Time Architecture zunit Development Process Overview zunit Setup, Required Datasets, Wizards and Workflow XML Editor Options QSAM Data Import Working with DB2 Programs Stubbing out Program Calls Analyzing Programs for Unit Testing Fit Futures Workshop/Lab Instructions Appendix 54

55 XML Editing - Toolbar Add a new Entry Edit Entry: Change generated module / Test name Delete Selected Entry Work with imported records Expand all parameters 55 Expand to parameters Collapse all parameters Show Layout for Items c Show Entry Columns Refresh XML from Source Import QSAM records Generate Test case IDz s XML Editor provides functionality to define sophisticated Entry Input/Expected values for complex LINKAGE SECTIONS

56 XML Editing Context Menu The Context Menu offers most of the options found on the Toolbar accessed from Ctrl+Spacebar Four important 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 Additional XML Editing features are available for dealing with large COBOL tables (arrays) 56

57 UNIT zunit Testing with IDz Topics: Management Overview Terms, Vocabulary, Run-Time Architecture zunit Development Process Overview XML Editor Options QSAM Data Import Working with DB2 Programs Stubbing out Program Calls Debugging Test Cases Analyzing Programs for Unit Testing Fit Futures Workshop/Lab Instructions Appendix 57

58 zunit XML Edit Session 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 QSAM File File Layout Schema R e c o r d I m p o r t Record Values Record Values If imported records contain garbage in numeric fields, the Import process will change those values to zeroes 58

59 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 59

60 Data Import Process 1 of 3 2. In the Editor: Click the Import Test Data icon 1. Delete the default ENTRY1 Test entry Click: Edit Test Entry Data 60

61 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 61

62 Imported Records Import Process 3 of 3 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) AZUE

63 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 63

64 UNIT zunit Testing with IDz Topics: Management Overview Terms, Vocabulary, Run-Time Architecture zunit Development Process Overview XML Editor Options QSAM Data Imports Working with DB2 Programs Stubbing out Program Calls Debugging Test Cases Analyzing Programs for Unit Testing Fit Futures Workshop/Lab Instructions Appendix Best Practice name the Test Case the same as the 64

65 Process Working with DB2 Programs zunit supports unit testing calls to subroutines with embedded SQL statements. The process is however, 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. Generate and Build your Test Case: But do not Run the Test Case 4. From the zunit Framework select: Generate Runner Configuration Typically you will check all of the zunit Run Option continuation settings 5. 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 6. Validate your Unit Test, using: The AZURES member SYSPRINT/SYSOUT from the batch job 65

66 Working with DB2 Generating a standalone Test Runner Configuration 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

67 JCL To run a DB2/zUnit Test 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) 67

68 UNIT zunit Testing with IDz Topics: Terms, Vocabulary, Run-Time Architecture zunit Development Process Overview XML Editor Options QSAM Data Imports Working with DB2 Programs Stubbing out Program Calls Debugging Test Cases Analyzing Programs for Unit Testing Fit Workshop/Lab Instructions Appendix 68

69 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 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 stub-routine (!!) do so at this point, using Generate Compile/Link JCL Note that the zunit Generated Stub Program will be found in the library mentioned above (from your zunit Property Group tab) 4. Then re-build the Subroutine you wish to zunit test (you have to do this because 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 69

70 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) 70

71 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 71

72 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? 72

73 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 73

74 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 74

75 UNIT zunit Testing with IDz Terms, Vocabulary, Run-Time Architecture zunit Development Process Overview XML Editor Options QSAM Data Imports Working with DB2 Programs Stubbing out Program Calls Debugging Test Cases Analyzing Programs for Unit Testing Fit Workshop/Lab Instructions Appendix 75

76 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 76

77 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 77

78 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 78

79 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 79

80 UNIT zunit Testing with IDz Terms, Vocabulary, Run-Time Architecture zunit Development Process Overview XML Editor Options QSAM Data Imports Working with DB2 Programs Stubbing out Program Calls Debugging Test Cases Analyzing Programs for Unit Testing Fit Workshop/Lab Instructions Appendix 80

81 Current zunit Support Languages COBOL and PL/I Subroutines zunit Support Comments 100% Assertion values passed through Linkage variables. DB2, VSAM and QSAM File I/O is supported. Programs with CICS or IMS COBOL or PL/I Batch driver programs - Assembler, C++ and 4GL programs as z/os Subroutines No Support No in-the-box Support No in-the-box Support 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. Support for IMS and CICS is in-plan for the future. Support for monolithic programs where test-values are not passed through Linkage variables but are contained in file I/O is currently not supported through the Wizard. However, you may refactor your code, adding a LINKAGE SECTION that provides insight into your program s procedural logic. You would of course have to remove the refactored code before going into production. Only COBOL and PL/I subroutines (where values are passed through Linkage variables) are currently supported. However, you can create simple COBOL or PL/I stub programs that pass Linkage values into your Assembler/4GL programs. Making them available for zunit Testing. 81

82 Choosing programs for zunit Consider the following simple decision-tree N COBOL or PL/I Batch Subroutine(s) Y Black Box esting N The functionality I need to test can be validated through the LINKAGE SECTION of the first subroutine Y Black Box Testing N I understand the programs and data logic well enough to create Entry values for my Unit Test Y Black Box Testing zunit 82

83 What do you put under source control? The prevailing wisdom is that because the generated/compiled/linked Test Case programs in our case: <HLQ>.ZUNIT.GEN.COBOL(*) are all generated by the Test Case Entries, the date in the files in AZUGEN and AZUCFG are what is needed to manage with your SCM You should note that the AZU libraries are: PDSE LRECL: BLKSIZE: RECFM: VBA In other words, these are not simple Fixed-byte TSO datasets Source managing these files using products like Rational Team Concert will make source control easier. 83

84 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 Subroutine-to-be-tested + copybook(s) 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. 84

85 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 : A , A , A , A 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. 85

86 UNIT zunit Testing with IDz Management Overview zunit Development Workshop/Lab Instructions Appendix 86

87 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 87

88 Workshop - Prerequisites Software: IDz Client v9.1.1 or IDz Server v9.5 or later Note that IBM s zserveros LPAR will provide you with what you ll need to finish this 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 88

89 Workshop 1 - Your First zunit Lab 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 89

90 Workshop 1 Allocate files/setup Filters Launch IDz from a new Workspace Add a new z/os connection to the IBM Mainframe zserveros.centers.ihost.com Port: 4035 Create MVS File Filters - for both your ID s ZUNIT datasets and for DDS0001.ZUNIT.* Expand the DDS0001.ZUNIT.* Filter, and Allocate Like the following Datasets on your student/zserveros ID Use the DDS0001 datasets as a model Note that if you are using your own mainframe: The AZU.* libraries have the following DCB: LRECL: BLKSIZE: RECFM: VBA Library Type: PDSE CNTL, COPYLIB, OBJ libs are all FB/80 LRECL LOAD is a Load Library of type PDSE LISTING is: FBA/133 SYSDEBUG is: FB/ Note that if the above datasets are already defined to your zserveros ID Delete your existing file and Allocate Like the DDS0001 Datasets

91 Import the Property Group Step 1. From the Property Group Manager, Import the zunit_v95_april_2016.xml Property Group file *** Don t forget to associate the Property Group to MVS Files Import the correct Property Group for your IDz Client Version Step 2. (OPTIONAL) open and browse through the Property Group specification tabs: JCL Run COBOL Link zunit *** Note that if you re using IDz v9.1.1 client, import zunit_v91_april.xml 91

92 Create a z/os Project and an MVS Subproject Workshop 1 Copy datasets/create an MVS Subproject Copy all of the DDS0001.ZUNIT.COBOL programs to your ZUNIT.COBOL library Copy all of the DDS0001.ZUNIT.COPYLIB files to your ZUNIT.COPYLIB library Create an z/os Project and an MVS Subproject connected to zserveros Drag the ZUNIT.COBOL programs into the MVS Subproject Add COBOL program DSNs to an MVS Subproject Note that if you wish to use your mainframe you will have to copy COBOL files and copybooks to your mainframe from a zipped file on DeveloperWorks: 92

93 Additional Library DSNs you will need to specify in your Property Group - if you plan to use your own mainframe during class Libraries you will need to discover with the help of your System Programmer(s) 93

94 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. 94

95 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 95

96 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) Generate Test Case 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 See Slide Notes or contact IBM for the source code for this example 96

97 Workshop 1 - Create the Test Case - Using the IDz Wizard - Part 2 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 97

98 Workshop 1 - Create the Test Case - Using the IDz Wizard - Part 3 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 98

99 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: Build the Test Case Run the Test Case The Test Case executes on z/os The build occurs on z/os 99

100 Run the Test Case Let IDz Locate the Job for you 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 100 IDz will also open the Member named from the Wizard in an Editor so that you can view results

101 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 101

102 Evaluate results Batch job information SYSPRINT displays the Test Runner SYSOUT - displays the: Names of the Test Case internal modules. Any COBOL DISPLAY data 102

103 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 103

104 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 104

105 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 105

106 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 106

107 (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 107

108 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 108

109 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) 109

110 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 multithreads Successful Compile/Link runs will create executables (Load Modules) in your ZUNIT.LOAD library 110

111 Workshop 4 - XML Editing Techniques EBUD01 XML Entries Generate a Test Case for EBUD01 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 111

112 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 112

113 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 113

114 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 114

115 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 115

116 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 116

117 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.. Important Note: SAM2 s editing paragraphs have numerous bugs 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. 117

118 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 118

119 Workshop 6 - Create the Test Case Create a Test Case for PERFCALC In the Editor: Click the Import Test Data icon Delete the default ENTRY1 Test entry Click: Edit Test Entry Data 119 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]

120 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 DSN Recall that you need to setup an MVS File Filter for this Select the file Click OK 120

121 Imported Records View the data records 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) AZUE

122 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_RECORD structures ** 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. 122

123 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 123

124 Workshop 7 Working with DB2 Initial Steps 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.CBOL 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 This workshop uses a COBOL program called: PHONEC1, which requires a copybook: IDzDCLS Both of these are available from the DDS0001.ZUNIT.* datasets 124

125 Workshop 7 Edit and Generate the Test Case 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 Here are some sample values 4. Generate and Build your Test Case But do not Run the Test Case 125

126 Workshop 7 Create the Test Runner Configuration 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

127 Workshop 7 Run your DB2/zUnit Test 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 127

128 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 128

129 Workshop 8 Creating Stub programs 1 of 6 In this workshop you will utilize a copy of the PERFCALC and CLCPTSP programs to learn how to create and use Stub programs in your zunit testing. Steps: 1. From <HLQ>.ZUNIT.COBOL; 1. Copy PERFCALC CLC2 and PERFCALC PERF2 2. Build CLC2 and PERF2 in this order (build CLC2 1 st then build PERF2) 3. Validate the results for (0 or 4 compile & link) 2. Go through the standard process to Generate a Test Case for PERF2 Note the additional fields that show up in the XML Entry editor for CLC2 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 3. Modify the values of the CLC2 fields and the LINKAGE for PERF2 as shown on the next slide 129

130 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) 130

131 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 131

132 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 132

133 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 133

134 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 134

135 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 135

136 UNIT zunit Testing with IDz Appendix 136

137 UNIT zunit Testing with IDz Topics: zunit Program Model 137

138 UNIT zunit Testing with IDz Management Overview zunit Terms, Vocabulary, Run-Time Architecture zunit Development Process zunit Program Model - Deeper Dive Maintaining your Test Case Analyzing Programs for Unit Testing Fit Futures Workshop/Lab Instructions Appendix 138

139 Review - zunit Component Implementation IDz substitutes generated z/os-specific resources for distributed technology classes, and frameworks. Test Runner A z/os systems program developed by the IDz team, and installed with IDz. The Test Runner orchestrate the unit testing process Test Case Test Suite Assertions Entry Test Execution A 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 An XML file that provides a list of Load Modules to be executed by the Test Runner COBOL or PL/I conditions that test individual units of source code in your program A generated set of COBOL or PL/I programs that implement the xunit framework standard; for setting up, running and tearing down individual Unit Tests z/os JCL that invokes the Test Runner Test Execution //JCL Submit JCL EXEC PGM= Test Runner - IDz zunit run-time OPEN INPUT READ Test Suite Which identifies Test Case Load Module Test Suite - List of Test Cases (Load Modules) Test Case - Generated COBOL or PL/I program Test Results (XML File) 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 and releases unit test resources (Tear Down) Entry - Generated COBOL or PL/I programs Makes 139 Assertions - Conditional Expressions coded in COBOL or PL/I Your program and the logic to be tested

140 Review - zunit Run-time Architecture JES Launches zunit Test Runner Which does the following: READ Test Suite CALL (invoke) Test Case Invoke Entry Submit JCL Interact 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 // EXEC PGM=Test Runner //AZUCFG Test Suite //AZURES Test Results // Test Case Load Library Entry Test Execution //AZUCFG DD DSN= Names the Test Case module(s) Test Case - SETUP Linkage Variables Test Suite - Run Unit Test Assertion Logic (CALL) - Evaluate outcome - Release resources z/os Test Results //AZURES DD DSN= Stores test results in XML PDS member 140 Target Subroutine Load Module to be unit tested Verifiable logic routine Verifiable logic routine Verifiable logic routine

141 Test Case Program Structure Initialization Top-level initialization module: PROGRAM-ID will be whatever you specified for the Driver program name in the Wizard zunit Test Case Module USER.ZUNIT.LOAD(UNIT0001) UNIT0001(...) ADDTESTS(...) SETUP(...) TEARDOWN(...) TEST1(...) TESTn(...) IDz generates nested COBOL or PL/I programs 141

142 Test Case Program Structure ADDTESTS ADDTESTS Dynamically defines your unit tests to the Test Runner (test harness) zunit Test Case Module USER.ZUNIT.LOAD(UNIT0001) UNIT0001(...) ADDTESTS(...) SETUP(...) TEARDOWN(...) TEST1(...) TESTn(...) 142

143 Wizard-generated 3. Test Case Program Structure SETUP SETUP - zunit Test Case Module USER.ZUNIT.LOAD(UNIT0001) UNIT0001(...) ADDTESTS(...) SETUP(...) TEARDOWN(...) TEST1(...) TESTn(...) Assertion Linkage value Assertion Linkage value Assertion Linkage value 143

144 Test Case Program Structure Entries 1 M Generated Entry template COBOL programs or PL/I procedures zunit Test Case Module USER.ZUNIT.LOAD(UNIT0001) UNIT0001(...) ADDTESTS(...) SETUP(...) TEARDOWN(...) TEST1(...) TESTn(...) 144

145 Test Case Program Structure TEARDOWN TEARDOWN zunit Test Case Module USER.ZUNIT.LOAD(UNIT0001) UNIT0001(...) ADDTESTS(...) SETUP(...) TEARDOWN(...) TEST1(...) TESTn(...) 145

146 Compile and Link SAM1 From Remote Systems: Right-click over SAM1 Select Generate JCL for Compile Link Submit the Job Check the Job and Step Return Codes Successful Compile/Link runs will create executables (Load Modules) in your ZUNIT.LOAD library SAM1.cbl 146

147 What do you use to Unit Test? Unit Testing is typically done using a product or a framework that provides: 1. Standardized process, methodology and a component framework (architecture) 2. Tools for code generation or some method of simplifying the development Unit Tests 3. Automation - running scripts - or in the case of zunit - running JCL and not testing interactively The industry leadership position in the Unit Testing space is occupied by the xunit component framework xunit has been adopted by almost all of the major computing languages/vendors/tools providers Including IBM Thus zunit 147

148 Generated Test Case and Runtime Behavior for Standalone Batch Unit Test Generated Test Case Initialization and Add Test Setup Set input data to parameters CALL AZUACPYQ Prepare input files by calling AZUFILE Runtime AZUACPYQ Runner API Copy input files for reuse Target COBOL source Input File Copy Input File Copy Input File is OPEN EXTEND in order to preserve original values Test Program CALL PROG1 CALL AZUTSC Compare output data with expected value by calling AZUTSC AZUTSC : Generated COBOL program Call SuperC with dynamic CALL AZUTSC CALL ISRSUPC Check ISRSUPC return code Output File Expected Output File Teardown ISRSUPC result file Free test fixture for each test (serial reusable behavior) Check detail result 148

149 Testing Main batch programs Input File PGM FD Generate Test case Runtime Test Runner Test Case Copy Input output PGM FD Input File ISRSUPC Test Entry Data Editor Output File Input File Check detailed results Expected Output File Expected Output File ISRSUPC result file 149