Test CICS Application

This topic contains the following sections:

•

Overview

•	CICS Execution Environment

•	Upload Customized Scripts for CICS Test Group

•	CICS 3270 Test Case (Online Screens)

•	CICS DPL Test Case (Message-driven Transactions)

Overview

Test Manger can be used to test rehosted CICS applications running on Tuxedo ART for CICS. It helps users to test two kinds of CICS programs:

•	Programs associated with 3270 screen transactions, which are identified as CICS 3270 test cases

•	Asynchronous programs triggered internally using EXEC CICS LINK or from external environments (e.g., CICS CTG, Web Services, DPL calls from mainframe CICS regions,) which are identified as CICS DPL test cases.

Before doing any testing, a project needs to be created as described in the previous chapters. After the project is created and associated with a deployed APPDIR location on a test machine, all available CICS test units are identified by scanning transactions.desc and programs.desc configuration files in the specified APPDIR for transaction and program definitions. These two files are generated by the ART Workbench from the CICS system definition (CSD) in CICS region configuration on z/OS. Once the project has been created and associated with an APPDIR on a test machine, the scan is performed automatically and all identified test cases are added into a default test group named as CICS_RT. A CICS test case can be executed in this default group or a new group with a custom name created manually, or in a test plan, which is created in a group. The user interface of a CICS group is shown below.

Clicking on the navigator on the left side will expand the tree menu and show the project, group, test plan and test case names. Detailed information and operation buttons are available on the top and right side of the main panel.

CICS Execution Environment

CICS cases are executed in a CICS region in a Tuxedo domain. Each CICS group has an independent CICS region in a Tuxedo domain. Before executing a case, the CICS domain should be booted up. Once started, the region remains running and available for all CICS test cases until it is shutdown.

Start/Shutdown Tuxedo Domain with CICS Region

To start/shutdown CICS region in a Tuxedo domain, enter a test group of CICS type, and then click “Startup Domain” or “Shutdown Domain”. “Domain up”, “Domain up (partial)” or “Domain down” status is indicated on the right side of the panel. The detailed startup or shutdown process and related messages can be viewed in the Console area at the bottom of the main operations panel.

If the status indicates the domain is up only partially, examine the messages in the Console area to determine which servers failed to start and whether they will impact your test cases. If they do, examine Tuxedo ULOG messages (click Result button for the group in the Project view) and related logs to determine the cause. Once the underlying issue has been resolved, shutdown the domain, run Cleanup Domain if any configuration changes have been made, and start it up again.

Monitor Tuxedo Domain with CICS Region

Click “Monitor Domain” to open the CICS Domain Monitoring screen and view information on transactions by polling interval. The view is updated dynamically based on a polling interval that can be changed at the top of the screen by changing the number and clicking Apply button. If there is no data, it means there are no transactions currently running.

This provides basic monitoring of CICS execution within the Test Manager. For more advanced monitoring capabilities Tuxedo System and Application Monitor Plus (TSAM Plus) provides additional capabilities, including real-time and historical performance monitoring, execution detailed tracing, SLA alerting, and much more.

Cleanup Tuxedo Domain with CICS Region

To apply domain configuration changes, such as the ubbconfig or setenv changes, a cleanup operation is needed before re-starting the domain, e.g., deleting tuxconfig and TLOG generated in the setup phase. Click on the “Cleanup Domain” button to have Test Manager perform the cleanup tasks. If the domain is up, first shut it down before clicking “Cleanup Domain” since these operations aren’t allowed while the domain is up.

Upload Customized Scripts for CICS Test Group

Test Manager provides built-in extension framework that can run user-provided pre- and post-execution scripts or executables as well as a result checking script. These custom scripts are supported for CICS group/plan/case.

•	Pre-execution file and post-execution files are executed before and after running a group/test plan/case. They can be either scripts or executable binary files.

•	Result check script can be used to extend the built-in results checking with additional steps to help determine whether a case failed or succeeded after it’s been executed.

Clicking the “Upload” button on group/test plan/case panel will open the upload dialog. These custom scripts are optional and are not required to run the test cases.

CICS 3270 Test Case (Online Screens)

When the project is created, the CICS 3270 test cases are automatically detected by analyzing the configuration file transactions.desc produced by ART Workbench from the CICS system definition (CSD) extract on z/OS.

Description

Tuxedo ART for CICS provides 3270 support that enables online transactions to interact with tn3270 emulators based on screen definitions in CICS BMS maps. That interaction, in the form of 3270 data stream, is identical to the interaction with online CICS transactions running on z/OS. In order to automate the testing, the Test Manager enables capturing the baseline during mainframe interaction, and then replaying it against rehosted transactions in Tuxedo ART for CICS environment and comparing the corresponding 3270 data streams and screens.

Testing a CICS 3270 case involves the following:

1.

Running CICS 3270 transaction (or sequence of screen interactions) on the mainframe to capture the baseline 3270 data stream using the Test Manager provided TN3270 Recorder tool. A complete guide for it can be found in Appendix I. Baseline captured by TN3270 Recorder contains three components packaged as a compressed tar file with “.tgz” extension:

•	Blueprint file (input part): the data stream sent from tn3270 to CICS on z/OS;

•	Benchmark file (output part): data stream sent from CICS on z/OS to tn3270;

•	Screen view rendered in HTML file (output part): the HTML view of the 3270 screenshot.

2.	Uploading the baseline to the test case configuration in ART Test Manger using the Upload dialog.

3.

Execute the same 3270 transaction sequence in the ART CICS environment using the blueprint (input part of the baseline), capturing the result. This is simply a matter of running the test case individually or as part of a test plan, the uploaded blueprint is then used to replay the interactions as they were captured.

4.

Compare the captured ART CICS output data stream against the benchmark captured from z/OS interaction and show any differences. The comparison is performed automatically after running the test case and the results can be viewed after clicking the Result icon for the test case. Console tab shows any execution messages or errors, and Screen Diff tab shows screen differences either as a list of fields or actual side-by-side view of the baseline (z/OS) and actual (ART CICS) screens.

Note that there may naturally be some differences if the CICS screens include date/time fields, or fields sensitive to the execution environment, for example host name, IP address, name of the batch job that started the CICS region, userid, or other external attributes. To help overcome these expected differences the Test Manager supports field filtering for 3270 fields. The filter simply enables users to remove certain fields from comparison. Filters can be set up at a test case level, and defined pro-actively when configuring a test case, or post-execution when comparing the results. In the latter case, the test case will initially show Failed status, which user can change to Passed after verifying all the other fields and selecting fields to filter out. Subsequent execution of the test case will automatically apply the filter, and barring any other differences, will mark the case as Passed.

Configuration

For CICS 3270 case there’s one mandatory configuration item, tn3270 recorder’s baseline, and 5 optional: pre- and post-execution scripts, 3270 field filter, field filter pattern, and comments. Click the icon in the Configuration column to open the detail configuration dialog for the CICS 3270 case.

The configuration dialog provides six tabs that can be used to enable checking the Pre/Post-Execution scripts already uploaded, to generate the baseline using tn3270 recorder, to check or edit the 3270 field filter list, to add or edit the 3270 field filtering pattern, and to add or edit text comments for this test case.

These tabs are:

 

Table 5‑1 Details for Test Case Tabs

Tab	Description
Pre-Execution	Showing the Pre-Execution script uploaded by user
Post-Execution	Showing the Post-Execution script uploaded by user
tn3270rcd	tn3270 recorder’s baseline is loaded here. Further information can be found in section 7.3.2.1
tn3270cpr filter	3270 fields filter configuration consisting of the page number and field position settings for fields to ignore during the comparison
tn3270cpr pattern	3270 field filter pattern Differences, which match the pre-defined pattern, would be marked
Comments	Showing comments added by the user

Using tn3270 Recorder and Uploading Captured Baseline

Before running a CICS 3270 test case, the transaction must be run on z/OS, capturing the 3270 data stream as a baseline in “.tgz” file. The tn3270 recorder tool is used to accomplish this. For the detailed usage of the tn3270 recorder in a standalone mode, refer to Appendix I - tn3270 Recorder.

In the case detail view, click Upload button to open the upload wizard where the baseline “.tgz” file can be uploaded along with optional pre- and post-execution scripts and result checking script for additional custom verification steps (e.g., MQ message has been sent or retrieved from a queue, file or DB have been updated, TSQ item has been posted, batch job submitted through TDQ, etc.).

Alternatively, there is another (more user-friendly) way to generate the baseline file of 3270 case and upload it using the following steps:

1.	Open “Configuration” of related case by clicking on the icon in the Configuration column. This will show the Details for the Test Case view with 6 tabs.

2.	Click the “tn3270rcd” tab to open a dialog.

3.	Input the mainframe host name and port for tn3270 connections.

4.	Click “Start tn3270rcd”. A message indicating tn3270rcd gateway port is shown to the right of the buttons if tn3270 recorder was started

5.

Open the tn3270 (for example: IBM PCOM) and establish a connection to the tn3270rcd gateway. In the screen shot above it is “bej301713.cn.oracle.com:48933”. If using IE browser, Test Manger can help to launch 3270 client (only w3270 client is supported), and connect to the tn3700rcd gateway automatically. Enter the path to the w3270 client and click “Start 3270 client” button.

Note:

This function is only supported IE browser, and ActiveX must enabled in IE. For other browsers and tn3270 clients, start the client manually and enter the connection information for the gateway. Once the connection is established:

•	In the 3270 terminal, navigate to the CICS application and, when positioned on the screen where you want to start baseline capture, press “PA1” to start recording.

•	Execute the application test sequence entering input values, tabs, and using PF keys as normal.

•	Press “PA1” again to end recording of the baseline.

5) Return to Test Manager screen and click “Kill tn3270rcd” to stop the tn3270 recorder demon.

6) Click “Collect baseline” to automatically upload the generated baseline. No manual upload is required.

Setting up field filtering

Assuming the application is executing correctly, most screen fields will match the mainframe baseline. However, some explainable differences may exist, precluding 100% match during the compare. For example, if the screen includes a date or timestamp, this value may differ between the captured z/OS baseline and the date or time of execution on ART for CICS. The difference will cause the Test Manager to fail this test case, even if all other fields match. However, if differences in some 3270 fields are not important, they can be added to the filter specification to be ignored when comparing the captured z/OS output with ART CICS. For example, in following screen, the field in line 1, column 70 is the current date (08-03-17). The test case will fail if the date in the baseline is not same as the date when the test case was executed in ART for CICS.

There are two ways to define the fields to be filtered out of comparison: pre-execution and post-execution. To add fields to the filter before running the test case, open “Configuration” of the related case and click the “tn3270cpr filter” tab.

Each line defines the position of a field to be ignored.

The filter format is:

Pagenumber;rowXcolumn

For example, to ignore the field in line 1 column 70 in the second screen, enter 0002;001X070

Alternatively, there is another (more user-friendly) way to add a filter for a test case post-execution. After running the test case, the differences are shown in the case’s Result view under the”Screen Diff” tab in the table form (under Diffs tab) and in side-by-side screen view (under Screens tab).Choose one or more fields from the list under the Diffs tab and click the “Add to filter file” button. The corresponding fields will be added to the filter and ignored the next time the case is executed and the captured results compared. Click "Add to group filter file" to add the corresponding fields to the filter file of this group. The group filter is applied to each case in this group if no filter is specified for the case.

After adding fields successfully, the list of the filtered fields (pagenum:position) can be checked under “tn3270cpr filter” tab in the case configurations view.

If the fields are added to the group filter file, the list of the filterd fields can be checked in the "tn3270cpr filter" tab of group view panel.

Execute Test Case and Check the Results

After generating the baseline, the CICS 3270 case can be executed individually or as part of a test group or test plan by clicking the “Run” button. The 3270 replayer will run the case using the captured blueprint (input) and capture a new benchmark (output), which will then be compared to the baseline benchmark. The log will be displayed in the Console view as shown in the figure below.

Data Stream Compare

After the test case finishes, the detailed result can be viewed in the “result” dialog. Click the icon in the “Result” column in the row corresponding to the case to open the result dialog. In this dialog, the comparison result is displayed under the “Screen Diff” tab in two ways: data stream difference and side-by-side screen capture rendered in HTML.

The data stream diff result can be found under “Diffs” tab. After examining differences, the results can be accepted by clicking the “Accept” button, which will change the status of the case to “PASS”. To reject the results, click the Reject button which will change the status of this case to “FAIL”.

The differences are listed in the table as follows:

 

Table 5‑2 Screen Diff Result

Column	Description
Page	The page number of screen.
Position	The field position in screen, format is: rowXcolumn
Content in Mainframe	Value in Mainframe
Content in ART CICS	Value in ART for CICS
ATTRB	Format: value in Mainframe|value in ART CICS. A: ASKIP, B: BRT, D: DET, R: DRK, F: FSET, I: IC, O: NORM, N: NUM, P: PORT, U: UNPROT.
COLOR	Format: value in Mainframe|value in ART CICS. D: DEFAULT, B: BLUE, R: RED, P: PINK, G: GREEN, T: TURQUOISE, Y: YELLOW, N: NEUTRAL.
HILIGHT	Format: value in Mainframe|value in ART CICS. O: OFF, B: BLINK, R: REVERSE, U: UNDERLINE.
OUTLINE	Format: value in Mainframe|value in ART CICS. B: BOX, L: LEFT, R: RIGHT, O: OVER, U: UNDER.
Predefined?	Y: The field could match the predefined pattern, N: The field is different, and no predefined pattern could be matched.

For more information about 3270 data stream field attributes, please refer to DFHMDF in IBM Knowledge Center.

Side-by-Side Screen Compare

The screens comparison result in HTML format is displayed by clicking the “Screens” tab. The mainframe screen is shown on the left, with the corresponding ART screen on the right. This view is intended as a visual aid to field list under Diffs tab and can also be snipped for inclusion in any test report or for further analysis.

Examining Server Logs and Traces

The ULOG and server traces in CICS group can be checked by viewing the result dialog for the test group. The logs accessible through this dialog include:

 

Table 5‑3 Accessible Logs

Log Type	Description
ULOG	Tuxedo ULOG with messages pertaining to Tuxedo domain and key messages from all the servers
Server Log	ART CICS server logs for all CICS application server types: synchronous screen transactions (ARTSTRN/ARTSTR1), async transactions (ARTATRN/ARTATR1), DPL programs (ARTDPL), and logs from CICS system servers providing supporting functions under Others (e.g., ARTTSQ, ARTCKTI, etc.). For CICS 3270 testing the servers executing online transactions are ARTSTRN/ARTSTR1 and their logs are named in the following format: std{out|err]_str[n|1].
stdout	stdout file display normal program output information.
stderr	stderr file display program error information.
Program Trace	ART CICS trace file showing EXEC CICS level traces for all CICS verbs and program trace output. Level of trace is defined in ART CICS runtime configuration via KIX_TRACE_LEVEL environment variable.

Under each tab, multiple logs can be listed based on what’s available in the runtime. Click on the one that corresponds to the time of the test and it will be displayed with search and pagination capabilities as shown in the figure below.

CICS DPL Test Case (Message-driven Transactions)

When the project is created, the CICS DPL test cases are automatically detected by analyzing the configuration file programs.desc produced by ART Workbench from the CICS system definition (CSD) extract on z/OS and all programs with a non-null value in REMOTESYS field are considered to be DPL programs and are imported as CICS DPL cases.

Description

Tuxedo ART for CICS provides many ways for online transactions to be triggered without user interaction. Internally to a CICS program, EXEC CICS LINK can trigger another program, referred to as DPL (Dynamic Program Link). DPL programs are also used for external interactions from CICS CTG, inbound Web Services requests, mainframe EXEC CICS LINK calls connected to ART CICS over the Tuxedo Mainframe Adapter, and other cases. All of these interactions are supported by DPL programs running in ARTDPL servers. In order to automate their testing, the Test Manager enables users to upload a client that can simulate the DPL request using Tuxedo ud32 driver tool.

To test a DPL program, first prepare a DPL client (currently, only ud32 scripts are supported) and then upload it. When running the test case, ART Test Manger executes this DPL client. However, since no mainframe baseline is available, the test case results cannot be automatically compared. Custom Result Check script can be provided and executed to verify the content of returned messages or for other evidence of successful execution (e.g., file or DB updates).

Configuration

For CICS DPL case there’s one mandatory configuration item, DPL client, and 4 optional: pre- and post-execution scripts, result check script, and comments. Clicking the Configuration column will open the detail configuration dialog tor CICS DPL case.

Creating DPL Client Using Tuxedo ud32 Script

Description

A client program is needed to launch DPL program. Currently, only ud32 scripts are supported as DPL clients.

For the usage of ud32, refer to ud,ud32, wud,wud32(1).

To create a working ud32 script the correct service name in a supported format and correct message fields must be defined in the ud32 script based on the actual client messages being passed on the DPL call. For details of the DPL interface in ART CICS refer to Oracle Tuxedo External DPL Communication Interfaces.

Example

Here is an example of ud32 DPL client in a text file:

Listing 5‑1 Example - ud32 DPL Client

SRVCNM CICC_TOLOSVR

CX_USERID MAU

CXMW_MESSAGE Hello_DPL

 

Note the following ud32 syntax requirements:

•	the field name and field value are separated by one tab.

•	the last line must be an empty line.

Uploading DPL Client

Once the ud32 script is prepared, it can be uploaded through the upload dialog of the test case.

Generating Ud32 Script

You can find an easy way to generate ud32 script and upload it for the DPL case. Open the case configuration view and click the "ud32 script" tab. Enter the program name, user ID, and COMMAREA Data in corresponding fields. For COMMAREA data , you can select the input content type string or file. If file is selected, the following page is displayed.

Then you can choose the file from local machine or other machine. Once clicking "Finish", the file content is linked to the COMMAREA Data field.

You can specify additional parameters in the "Other Parameters" text area in the format shown on the screen.

When finishing configuration, you can click "Save" to generate corresponding ud32 script and upload for DPL case. You can check the ud32 script in the upload dialog, and click "Uploaded" link in the line of "DPL Client(ud32 script)".

Execute Test Case and Check Results

After uploading the DPL client, the CICS DPL case can be executed by clicking the “Run” button. The log will be displayed in the Console view.

Currently, the check result logic is: if the keyword “error” is found in the ud32 output, the DPL case would be marked as “FAIL”, otherwise, it would be marked as “PASS”. Additional verification can be performed through the custom Result Checking script.

Examining Server Logs and Traces

The ULOG and server traces in CICS group can be checked by viewing the result dialog. For more information, seeExamining Server Logs and Traces. Under the Server Log tab, the relevant server executing DPL programs is ARTDPL and its logs are named using the following format std[out|err]_dpl_* as shown in the figure below.