I often get questions on Mainframe test automation using Selenium. However Selenium automates browsers, that’s it! Selenium does not automate Mainframe Green screens, and it’s completely different technology.
Automating Mainframe Green screen is primarily needed to test front to back scenarios in complex transaction processing systems with Web and Mobile integration.
There are tools available that can be used to automate Mainframe Green screen interaction. In this post, we will see how to use Jagacy3270 from Jagacy Software along with Cucumber for writing Automated Acceptance Tests on Mainframe Green Screens also known as CICS interface.
About Jagacy3270
Jagacy3270 is a 3270 screen-scraping library written entirely in Java. As described on Jagacy product website it supports SSL, TN3270E, Internationalization, and over thirty languages. This library can be used to create highly reliable and faster screen-scraping applications. However, this tool comes with a cost and details are available on the website.
We can use this same screen-scraping capability to create automated tests on Mainframe Green screens.
Jagacy provides Session3270 class through which we can connect to a Mainframe host and read or write to screens to perform actions.
Writing Automated Acceptance Tests for Green Screens
We can use Jagacy along with testing frameworks like Cucumber in Agile Software development to automate acceptance criteria for Mainframe user stories involving Green screen interaction. These tests can be integrated into CI/CD pipeline and run in headless mode (Jagacy provides an Emulator screen mode or headless mode).
In this post, we will use a Mainframe host used in Jagacy examples to create a simple Automated Acceptance test for a Phonebook application. Here is our example user story
As an university application user I should be able to search faculty members in Phonebook So I can contact them for help
Here is Feature file with one of the acceptance criteria or scenario that searches for Faculty phone number on Phonebook application:
Feature: Phonebook As an univeristy mainframe user I should be able to search faculty members in Phonebook So I can contact them for help Scenario: Search faculty phone number using name Given I start a new emulator session When I open phonbook application And search for faculty name "NAME" Then I should see the results matching with my search criteria |NAME1 111-111-1111 LIBRARIES 5000| |NAME2 UNAVAILABLE MARY KAY O'CONNOR PROCESS 3122|
To automate Screen entry and retrieve values, we need to use screen coordinates by using Row and Column numbers (Typically 3270 sessions are 24×80 rows and columns long).
We can use PageObject Pattern to abstract Mainframe Green screens and provide screen actions and state to tests. For example, here is HomeScreen object which provides feature on the Home Screen:
package com.example.screens; import com.example.Fields.EntryField; import com.example.session.Session; import com.example.Fields.LabelField; import com.jagacy.Key; import com.jagacy.util.JagacyException; /** * Created by upgundecha on 14/10/16. */ public class HomeScreen { private Session session; private String screenCrc = "0xb0c10358"; // Screen fields private LabelField waitForLabel = new LabelField(17, 6, "TEXAS A & M UNIVERSITY"); private EntryField applicationEntryField = new EntryField(23, 1); public HomeScreen(final Session s) throws JagacyException { this.session = s; if (!session.waitForTextLabel(waitForLabel)) { throw new IllegalStateException("Not Home screen!"); } if (session.getCrc32() != Long.decode(screenCrc)) { throw new IllegalStateException("Home Screen has been changed!"); } } /** * Open Phonbook Menu screen. * @return Phonbook Menu Screen * @throws JagacyException JagacyException */ public final PhonbookMenuScreen openPhonbook() throws JagacyException { session.setEntryFieldValue(applicationEntryField, "PHONBOOK"); session.writeKey(Key.ENTER); session.waitForChange(10000); return new PhonbookMenuScreen(session); } }
We can check if a correct page is displayed in the emulator by using the arbitrary text displayed on the screen. We can also use CRC of the screen to make sure it is not updated otherwise tests might fail as fields or text values on screen are not found at specified locations.
Finally, we will call the PageObjects in step definitions to perform the scenario and validate the output:
package com.example.test; import com.example.screens.HomeScreen; import com.example.screens.PhonbookMenuScreen; import com.example.screens.PhonbookSearchScreen; import com.example.session.Session; import com.jagacy.util.JagacyException; import cucumber.api.Scenario; import cucumber.api.java.After; import cucumber.api.java.Before; import cucumber.api.java.en.Given; import cucumber.api.java.en.Then; import cucumber.api.java.en.When; import static org.junit.Assert.*; import java.util.List; /** * Created by upgundecha on 14/10/16. */ public class Stepdefs { private Session session; private HomeScreen homeScreen; private PhonbookMenuScreen phonbookMenuScreen; private PhonbookSearchScreen phonbookSearchScreen; private Scenario scenario; @Before public void setUp(Scenario scenario){ this.scenario = scenario; } @Given("^I start a new emulator session$") public void i_start_a_new_emulator_session() throws Throwable { session = new Session("test"); session.open(); } @When("^I open phonbook application$") public void i_open_phonbook_application() throws Throwable { homeScreen = new HomeScreen(session); scenario.embed(session.getScreenshot(), "image/png"); phonbookMenuScreen = homeScreen.openPhonbook(); } @When("^search for faculty name \"([^\"]*)\"$") public void search_for_faculty_name(String q) throws Throwable { scenario.embed(session.getScreenshot(), "image/png"); phonbookSearchScreen = phonbookMenuScreen.openFacultyStaffListing(); phonbookSearchScreen.searchByFirstOrMiddleName(q); } @Then("^I should see the results matching with my search criteria$") public void i_should_see_the_results_matching_with_my_search_criteria(List<String> records) throws Throwable { scenario.embed(session.getScreenshot(), "image/png"); assertEquals(records, phonbookSearchScreen.getResults()); } @After public void tearDown() throws JagacyException { session.close(); } }
We can also get the screenshot (not available as part of Jagacy API) embedded in the reports.
And if you already have a well established Selenium framework (on JVM) and want to automate Mainframe Green screens, you can use above approach with Cucumber or any other xUnit testing framework that you might be using.
The complete source code for this post is available here. Please drop me a message for access with your Github username. I have built this simple framework on top of Jagacy API. If you need any further information or have suggestions, please do reach out to me.
Great Article Unmesh..Mainframe automation,Cucumber,PageObjects all in one.
Very good information.
Can you please share the source code in github. The link you have provided is not working
Hi Unmesh,
Thanks for sharing the detail.
I wanted to have the further discussion in this regards, I got your this reference from your colleague.
Kindly share your email detail at nitin.jain05@mphasis.com
Github username: nitinjain0512
unable to find the below classes inJagacy3270.
import com.jagacy.Key;
import com.jagacy.Session3270;
Can anyone please help.
Hi Unmesh,
I am trying to automate M/F using your script. I have followed the same directory structure as you have provided but I am getting the following error:
Given I start a new emulator session(Scenario: Enter and Login to Region) Time elapsed: 0.007 sec <<< ERROR!
com.jagacy.util.JagacyException: [PROPERTY NOT FOUND ERROR] Could not find property jagacy.host
Scenario: Enter and Login to Region Time elapsed: 0.008 sec <<< ERROR!
com.jagacy.util.JagacyException: [PROPERTY NOT FOUND ERROR] Could not find property jagacy.host
Please help me how to resolve this issue.
Thanks
Anuj
HI Umesh,
gr8 article, i tried this for my MF application but having few doubt
Umesh can you ple help me to know about session.getCrc32()
Hi Unmesh, I downlaoded your Github Jagacy project but while running getting exception “com.jagacy.util.JagacyException: [PROPERTY NOT FOUND ERROR] Could not find property jagacy.host”. I tried all possible combinations given by Jagacy support team but no luck so far. I stopped the firewall too but still same error. Could you please help me out in this regard as I am blocked in my POC creation.
Isn’t this article is from dzone, because when I see it I see word to word similarity!!
Hi Unmesh,
I am working on poc where we decided to use jagacy to automate a simple validation in mainframe application.
Basically I made changes to make the same code(in git) to point to the aplication we are testing.
But I am facing this error while running the scritpt.
com.jagacy.util.JagacyException: [INVALID POSITION ERROR] Protected field
at com.jagacy.tn3270.c.if(Unknown Source)
at com.jagacy.c.a(Unknown Source)
at com.jagacy.AbstractSession.writeString(Unknown Source)
at com.jagacy.AbstractSession.writePosition(Unknown Source)
at com.example.session.Session.setEntryFieldValue(Session.java:57)
at com.example.screens.HomeScreen1.openPhonbook(HomeScreen1.java:38)
at com.example.test.Stepdefs.i_open_phonbook_application(Stepdefs.java:52)
at ✽.When I open phonbook application(src/test/resources/features/com/example/phonebook.feature:9)
public class HomeScreen1{
///////////////////////////////////////////////////
public final PhonbookMenuScreen1 openPhonbook() throws JagacyException, InterruptedException {
Thread.sleep(4000);
session.setEntryFieldValue(applicationEntryField1, “logon”);
session.writeKey(Key.ENTER);
session.waitForChange(session.DEFAULT_TIMEOUT);
Thread.sleep(4000);
Thread.sleep(2000);
session.setEntryFieldValue(applicationEntryField2, “user1234”);
session.writeKey(Key.ENTER);
session.waitForChange(session.DEFAULT_TIMEOUT);
System.out.println(“Screen text after login:”);
System.out.println(session.readScreenText());
Thread.sleep(20000);
return new PhonbookMenuScreen1(session);
}
}
Do we need to apply any specific configuration to be able to type on prtected fields?
I tried to know if there is any otherway to handle the protected fields but nowhere I found the reference.
Pls help me with this case. Thanks in advance.
If it cannot find the jagacy.host property it means the property file location is not found or the property in it has no value. Try and put the properties file in the root folder of your project
are there any other groups where Jagacy is discussed?