TN3270
xk6-tn3270 adds 3270 terminal emulation to k6. It implements RFC 1576 and RFC 2355
in Go, so it needs no s3270 or x3270 process. Each VU gets
its own emulator and TCP socket.
Scripts
| Script | Target | Executor | Measures |
|---|---|---|---|
simbank-logon.js |
SimBank | 1 iteration | Connect, sign on, reach the menu |
simbank-browse.js |
SimBank | ramping-vus |
Account enquiry under a ramp |
simbank-transfer.js |
SimBank | constant-arrival-rate |
A write transaction |
cics-transaction.js |
Your CICS region | ramping-arrival-rate |
CESN, your transaction, CESF |
tso-logon.js |
TSO | constant-arrival-rate |
Logon and logoff |
Get a binary with the extension
The extension is not in the k6 registry, so automatic extension resolution does
not cover it. Download k6-z-3270 from
releases, or build one:
xk6 build v1.6.1 --with github.com/msradam/xk6-tn3270@v0.1.0
Confirm the extension is present:
$ ./k6 version
k6 v1.6.1 (go1.25.12, linux/amd64)
Extensions:
github.com/msradam/xk6-tn3270 v0.1.0, k6/x/tn3270 [js]
See install for the s390x archives.
Run against SimBank
Galasa SimBank is the sample 3270 application from the Galasa test framework. It runs in a JVM on a laptop and presents a logon screen, a menu, an account enquiry, and a funds transfer. The SimBank scripts are written against it.
Start the server:
git clone https://github.com/galasa-dev/simplatform.git
cd simplatform && ./build-locally.sh && ./run-locally.sh --server
Run the smoke test:
k6 run -e TN3270_HOST=localhost -e TN3270_PORT=2023 \
scripts/tn3270/simbank-logon.js
environments/simbank/README.md lists the ports and the seeded accounts.
Field boundaries
3270 fields are fixed width. Typing into a field advances the cursor into the next unprotected field only when the field is filled exactly. A seven-character user id in an eight-character field does not advance, so the script has to tab:
session.type('IBMUSER'); // 7 characters in an 8-character field
session.tab(); // required, the cursor did not advance
session.type('SYS1');
session.enter();
On the transfer screen both account fields are nine characters and both are filled exactly, so no tab is needed:
session.type(fromAccount); // 9 of 9, the cursor advances on its own
session.type(toAccount);
session.type('10.00');
session.enter();
A script that assumes the wrong behaviour works against one emulator and types
into the wrong field on another. scripts/lib/tn3270.js provides fillFields(),
which tabs only between fields that are not exactly filled.
Close sessions in a finally block
A 3270 gateway allocates a terminal per session. If a check throws and the session is never disconnected, the socket stays open until the VU iteration ends, which appears as an exhausted terminal pool rather than as a k6 error.
scripts/lib/tn3270.js provides withSession(), and every TN3270 sample uses it:
export function withSession(fn, options = {}) {
const session = openSession(options);
try {
return fn(session);
} finally {
session.disconnect();
}
}
Wait on the screen, not the clock
waitForField() blocks until the keyboard unlocks and an input field exists,
which is the signal that the host is ready for input. A fixed sleep() either
wastes time or reads the previous screen.
Two composite methods combine an action with the wait:
session.sendCommand('BANK', true); // type, enter, waitForField
session.sendPF(1, true); // PF1, waitForField
tn3270_wait_timeouts counts the waits that expired. A wait timeout means the
expected screen never arrived, so every check after it asserts against the wrong
screen. Hold it at zero:
thresholds: {
tn3270_wait_timeouts: ['count == 0'],
tn3270_connect_duration: ['p(95) < 5000'],
}
Set the ramp and think time
Terminal pools are finite in a way that HTTP connection pools are not. The browse script ramps over a minute rather than starting at full VU count, so the measurement reflects the application rather than pool exhaustion:
stages: [
{ duration: '1m', target: 10 },
{ duration: '2m', target: 10 },
{ duration: '30s', target: 0 },
],
gracefulRampDown: '30s',
Think time defaults to 3 seconds in simbank-browse.js. Set TN3270_THINK_TIME=0
to measure maximum protocol throughput instead of a workload.
Run a CICS transaction
cics-transaction.js is generic. It signs on with CESN, runs the transaction
named in CICS_TRAN, checks the screen for CICS_EXPECT, and signs off with
CESF LOGOFF. All three transactions are IBM-documented.
k6 run \
-e TN3270_HOST=cics.example.com -e TN3270_PORT=23 \
-e TN3270_USER=TESTID -e TN3270_PASSWORD="$PASSWORD" \
-e CICS_TRAN=MYTX -e CICS_EXPECT='ENQUIRY COMPLETE' \
-e CICS_TPS=5 \
scripts/tn3270/cics-transaction.js
setup() fails if either CICS_TRAN or CICS_EXPECT is unset.
Abends are counted separately from protocol failures by matching the terminal messages CICS sends:
if (screen.includes('DFHAC2206') || screen.includes('DFHAC2001')) {
transactionAbends.add(1);
}
Point it at a read-only enquiry before anything that changes state.
Run TSO logons
tso-logon.js verifies that TSO accepts a logon, which confirms that the system
is up and RACF is answering. Each logon allocates a TSO address space, so the
script uses a low arrival rate. A burst reaches MAXUSERS before it stresses
anything else.
k6 run \
-e TN3270_HOST=tso.example.com -e TN3270_PORT=23 \
-e TN3270_USER=TESTID -e TN3270_PASSWORD="$PASSWORD" \
-e TSO_APPLID=TSO -e TSO_LOGONS_PER_MINUTE=6 \
scripts/tn3270/tso-logon.js
A single RACF user id cannot be logged on twice. If several VUs share one, TSO
returns IKJ56425I and the failure rate reflects the shared id rather than the
system. The script logs a warning when it sees that message. Give each VU its own
id, or keep the rate low enough that logons do not overlap.
Connect with TLS
Set TN3270_TLS=true to have scripts/lib/tn3270.js use TLS. For client
certificates or a private CA, call the extension directly:
session.connectTLSWithOptions('mainframe.example.com', 992, {
caCert: open('/etc/ssl/internal-ca.pem'),
clientCert: open('/etc/ssl/client.pem'),
clientKey: open('/etc/ssl/client.key'),
minVersion: '1.3',
});
caCert, clientCert, and clientKey accept an inline PEM string or a path. The
cipher list is restricted to AEAD suites with forward secrecy; CBC, RC4, and
non-PFS RSA suites cannot be selected.
Metrics
| Metric | Type | Description |
|---|---|---|
tn3270_connect_duration |
Trend (ms) | Connect and negotiate |
tn3270_send_duration |
Trend (ms) | Time to send an AID |
tn3270_wait_duration |
Trend (ms) | Time spent in waitForField and waitForText |
tn3270_session_duration |
Trend (ms) | Connect to disconnect |
tn3270_wait_timeouts |
Counter | Waits that expired |
tn3270_errors |
Counter | Protocol and connection errors |
tn3270_screens |
Counter | Screens received |
tn3270_aids_sent |
Counter | AID keys sent |
tn3270_bytes_in, tn3270_bytes_out |
Counter (bytes) | Traffic |
Error codes
Errors thrown to JavaScript carry a stable code field. Branch on the code rather
than the message text:
try {
session.connect(host, port, 5);
} catch (err) {
if (err.code === 'connect_timeout') {
// retry
}
}
Codes: invalid_argument, not_connected, connect_failed, connect_timeout,
tls_handshake, negotiation_failed, wait_timeout, host_closed,
protocol_error, init_context, protected_field, screenshot_failed.
For the full method reference, see xk6-tn3270.