k6-z Grafana k6 on IBM z/OS

z/OSMF · TN3270 · ZOAU · s390x

k6-z

k6-z is a set of Grafana k6 test scripts and prebuilt binaries for load testing IBM z/OS. It covers the four interfaces a z/OS system exposes to a test driver, and it ships k6 binaries for s390x, which upstream k6 does not publish.

What you can test

Surface Transport Extension required Scripts
z/OSMF REST HTTPS None scripts/zosmf/
TN3270 TCP (RFC 1576, RFC 2355) xk6-tn3270 scripts/tn3270/
ZOAU over SSH SSH xk6-ssh scripts/ssh/
ZOAU on the host Local process xk6-exec scripts/exec/

Start with z/OSMF. It needs no extension, so any k6 binary can run those scripts.

Why k6 for z/OS

For a comparison with WSim, TPNS, and JMeter, see From JMeter and TPNS.

Requirements

To run You need
The z/OSMF scripts Any k6 binary, and a z/OSMF server you can reach
The TN3270 scripts A binary built with xk6-tn3270
The ZOAU scripts A binary built with xk6-ssh or xk6-exec, and ZOAU installed on the host
The mock server Python 3.9 or later
Building from source Go 1.25 or later

Get started

The repository includes a mock z/OSMF server, so you can run the z/OSMF scripts without a mainframe.

  1. Clone the repository and build both binaries.

    git clone https://github.com/msradam/k6-z.git
    cd k6-z
    make build
    
  2. Start the mock server. It listens on port 10443 and answers the same request shapes as z/OSMF.

    python3 tools/mock-zosmf.py &
    
  3. Run a script against it. This one submits JCL, polls the job until it reaches the output queue, reads its spool, and purges it.

    ZOSMF_URL=http://127.0.0.1:10443 ZOS_USER=IBMUSER ZOS_PASSWORD=mock \
      ./dist/k6-z run scripts/zosmf/job-submit.js
    

k6 prints a summary with the thresholds the script declares, including zos_job_turnaround.

Run against a z/OS system

Run the smoke test first. It calls GET /zosmf/info and verifies that the host answers, that the credentials authenticate, and that TLS negotiates. Its checks threshold uses abortOnFail, so a bad password stops the run at the first iteration.

./dist/k6-z run \
  -e ZOSMF_URL=https://zosmf.example.com \
  -e ZOS_USER=IBMUSER \
  -e ZOS_PASSWORD="$ZOS_PASSWORD" \
  scripts/zosmf/info.js

If your z/OSMF uses a certificate your load generator does not trust, add -e ZOS_TLS_INSECURE=true to confirm connectivity, then fix the trust store.

Every setting comes from an environment variable. See configuration for the full list.

Next steps

Sources

The z/OSMF scripts use the documented z/OSMF REST services. The ZOAU scripts use display and read commands from IBM’s zoau-samples. The TN3270 scripts target Galasa SimBank.

The scripts are starting points. The numbers they produce depend on your LPAR, your workload, and where the load generator runs, so they are not comparable across installations.