Rapise can automate these applications using protocol-aware terminal interfaces. The Rapise PowerPack includes two sample frameworks:

  • Term3270, which uses the x3270 terminal emulator and its local REST interface.
  • Term5250, which uses EHLLAPI to communicate with IBM iAccess Client Solutions or IBM Personal Communications.

Both samples contain reusable Rapise Page Objects and example test cases.

Background

Green screen automation differs from ordinary GUI automation. Instead of locating buttons, text boxes, and other visual controls, a test normally performs operations such as:

  1. Reading the current terminal screen.
  2. Waiting for specific text to appear.
  3. Entering text at the current cursor position.
  4. Sending terminal keys such as Enter, Tab, Clear, or PF1–PF24.
  5. Verifying that the expected screen has been displayed.
  6. Capturing the terminal window or screen text in the Rapise report.

Rapise encapsulates these operations in the Term and Term5250 Page Objects. The same actions can be called from JavaScript or selected from the Object and Action columns in an RVL test. Rapise also supports importing pre-built Page Objects into another testing framework.

Solution

Download the appropriate sample from the Rapise PowerPack:

Each folder is a complete Rapise testing framework. After downloading it, open Framework.sstest in Rapise.

The two samples use different integration methods, so their configuration is described separately below.

Automating a 3270 Terminal

How the 3270 Integration Works

The Term3270 sample contains the Windows wc3270 component from the x3270 terminal emulator suite.

Rapise starts or attaches to wc3270.exe and communicates with it through a local REST service:

http://localhost:13270/3270/rest/

The emulator is started with its HTTP service enabled on port 13270. Rapise then sends x3270 actions through the REST API and reads the terminal screen using the PrintText action.

The Term Page Object provides the following main actions:

  • FindOrAttach — starts the included emulator or attaches to an existing instance.
  • SendString — enters a string at the current cursor position.
  • SendInput — sends the supplied text one character at a time.
  • SendCommand — sends an x3270 action such as Enter, Tab, Clear, or PF(3).
  • EnsureText — waits until specified text appears on the screen.
  • Screenshot — adds an image of the terminal window to the Rapise report.

Configuring the Connection

Call Term.FindOrAttach with the terminal address:

Term.FindOrAttach("my-mainframe.example.com:23", false);

Replace the hostname and port with the address of your 3270 server.

The second parameter controls how the emulator is started:

  • Use false to let Rapise start the bundled wc3270.exe when it is not already running.
  • Use true when the terminal emulator has already been started and Rapise should only attach to it.

When Rapise starts the bundled emulator, it automatically enables the REST service on port 13270.

Example 3270 Test

The following example connects to a terminal, enters credentials, and verifies that the main menu is displayed:

function Test()
{
    // Start the bundled emulator and connect to the host.
    Term.FindOrAttach("my-mainframe.example.com:23", false);

    // Wait for the login screen.
    Term.EnsureText("USER ID", 10000, true);

    // Enter the user name and password.
    Term.SendString("MYUSER");
    Term.SendCommand("Tab");
    Term.SendString("MYPASSWORD");
    Term.SendCommand("Enter");

    // Verify that login succeeded.
    Term.EnsureText("MAIN MENU", 10000, true);

    // Add the current terminal window to the report.
    Term.Screenshot("3270 main menu");
}

Do not store production credentials directly in the test. Use Rapise test parameters, environment variables, or another secure credential source.

The value passed to SendCommand is an x3270 action. Common examples include:

Term.SendCommand("Enter");
Term.SendCommand("Tab");
Term.SendCommand("Clear");
Term.SendCommand("PF(3)");
Term.SendCommand("PF(12)");

You can also send another supported x3270 action directly through SendCommand.

Automating a 5250 Terminal

How the 5250 Integration Works

The Term5250 sample connects to a running IBM terminal emulator through EHLLAPI, or Emulator High-Level Language API.

The sample supports the following emulator processes:

  • acslaunch_win-64.exe — IBM iAccess Client Solutions, 64-bit.
  • acslaunch_win-32.exe — IBM iAccess Client Solutions, 32-bit.
  • pcsws.exe — IBM Personal Communications.
  • pcscm.exe — IBM Personal Communications.

EHLLAPI provides access to the terminal presentation space, allowing Rapise to read screen contents, send keys, query the cursor position, search for text, and check the state of the terminal session.

Prerequisites

Before running a 5250 test:

  1. Install IBM iAccess Client Solutions or IBM Personal Communications.
  2. Start the terminal emulator.
  3. Connect the emulator to the IBM i or AS/400 system.
  4. Assign a short name to the terminal session. The default expected session name is A.
  5. Make sure the EHLLAPI DLL is installed.

The default DLL location expected by the sample is:

C:\Program Files (x86)\IBM\EHLLAPI\pcshll32.dll

When the DLL is installed in another folder, specify its location before attaching to the session:

Term5250.SetDllPath("C:\\IBM\\EHLLAPI\\pcshll32.dll");

Alternatively, define the EHLLAPI_DLL environment variable with the complete path to the DLL.

The Page Object uses the Node.js koffi module to load and call the EHLLAPI DLL. If koffi is not available, the current implementation attempts to install it automatically with npm. On an isolated execution machine, npm access may need to be configured in advance.

Example 5250 Test

The following example attaches to session A, logs in, navigates through a menu, and verifies the resulting screen:

function Test()
{
	// Only required when the DLL is not in the default location.
	// Term5250.SetDllPath("C:\\IBM\\EHLLAPI\\pcshll32.dll");

	// Attach to an active terminal session.
	Term5250.FindOrAttach("A", true);

	// Wait for the login screen and enter credentials.
	Term5250.Login("MYUSER", "MYPASSWORD", "Sign On");

	// Verify that the expected screen is displayed.
	Term5250.EnsureText("Main Menu", 10000, true);

	// Select a menu option.
	Term5250.SelectMenuOption("1");

	// Enter text at a specific row and column.
	Term5250.TypeAt(10, 20, "SOME TEXT");

	// Press F3.
	Term5250.PressF(3);

	// Add the current terminal window to the report.
	Term5250.Screenshot("Current 5250 screen");
	Term5250.DisconnectPS();
}

The Term5250 Page Object includes actions for:

  • Reading the complete screen with CopyPS.
  • Reading individual rows with GetScreenRows.
  • Reading text at a specific position with GetTextAt.
  • Entering text with SendString or SendStringEnter.
  • Positioning the cursor with SetCursorPos or TypeAt.
  • Sending F1–F24 with PressF.
  • Waiting for the keyboard to become available with WaitReady.
  • Searching for screen text with SearchPS, WaitForScreen, or EnsureText.
  • Listing available sessions with QuerySessions.
  • Writing the current screen to the Rapise log with DumpScreen.
  • Reading the standard message line with GetMessageLine.

The supplied implementation assumes a standard 24-row by 80-column terminal presentation space.

Supported 5250 Keys

The following keys can be passed to Term5250.SendKey or Term5250.SendCommand:

  • Function keys: F1 through F24, or commands such as PF(3).
  • Navigation: Enter, Tab, BackTab, PageUp, PageDown, Home, and NewLine.
  • Editing: Delete, Insert, EraseEOF, EraseInput, and Clear.
  • System keys: Help, Reset, SysRequest, Attn, and PrintScreen.

For example:

Term5250.SendKey("Enter");
Term5250.SendKey("Tab");
Term5250.SendKey("Clear");
Term5250.SendCommand("PF(12)");

Using the Page Objects in an Existing Framework

You do not need to use the complete sample framework.

After downloading the PowerPack sample, import the required Page Object into your existing Rapise framework:

  • Import PageObjects\Term for 3270 automation.
  • Import PageObjects\Term5250 for 5250 automation.

The 3270 Page Object includes its own x3270 emulator files, so make sure the complete x3270 subfolder is copied during the import.

Once imported, the Page Object actions can be used directly from JavaScript:

Term.EnsureText("READY", 5000, true);

or:

Term5250.EnsureText("Main Menu", 5000, true);

In RVL, select Term or Term5250 in the Object column and then select the required operation in the Action column.

Troubleshooting

Rapise Finds wc3270 but REST Commands Fail

An existing wc3270.exe process may have been started without the HTTP service enabled.

Close the existing emulator and let Term.FindOrAttach start the copy included with the Page Object. Also verify that local port 13270 is not being used by another process or blocked by security software.

The 3270 Test Cannot Find Expected Text

Use:

Term.Screenshot("Unexpected terminal screen");

to capture the terminal window in the report.

You can also send:

var screenText = Term.SendCommand("PrintText(string)");
Log(screenText);

to inspect the complete textual contents returned by the emulator.

No 5250 Emulator Is Found

Confirm that IBM iAccess Client Solutions or IBM Personal Communications is running. The Page Object searches for the supported emulator process names before attempting to connect.

The 5250 Session Cannot Be Connected

Check the short session name assigned by the emulator. The default is A, but another letter may have been assigned.

Available EHLLAPI sessions can be inspected with:

var sessions = Term5250.QuerySessions();
Log(JSON.stringify(sessions));

Then pass the correct session name to:

Term5250.FindOrAttach("B", true);

The EHLLAPI DLL Cannot Be Loaded

Verify the location of pcshll32.dll and configure it explicitly:

Term5250.SetDllPath("C:\\Path\\To\\pcshll32.dll");

Also check the Rapise log for errors related to loading the DLL or installing the koffi Node.js module.

Commands Are Sent While the Terminal Is Busy

5250 terminals may temporarily lock keyboard input while processing a request. Wait until the session is ready before sending the next command:

Term5250.WaitReady(10000);

You can also use WaitForScreen or EnsureText to synchronize the test with a specific terminal screen rather than relying on fixed delays.

Result

Once the appropriate Page Object is configured, Rapise can automate complete green screen workflows, including login, menu navigation, command entry, function-key operations, screen verification, and reporting.

Because Rapise communicates through the terminal emulator API rather than relying only on screen coordinates or image recognition, tests can interact with the textual terminal presentation space and wait for specific application states.