abap2UI5 headless frontend

abap2UI5 - headless frontend

Test abap2UI5 apps in ABAP. No browser, no UI5, no HTTP.

An abap2UI5 app is a class. Its whole conversation with the outside world is one JSON request in, one JSON response out — the frontend sends the model delta and an event id, the backend sends back view-lifecycle actions, a model and follow-up actions. That is the entire contract.

This repo takes that contract seriously and plays the other side of it in ABAP. z2ui5_cl_frontend_simulator builds the same request the UI5 frontend builds, hands it to z2ui5_cl_ui5_handler, and replays the response the way the frontend does — all in the same session, in the same call stack, in a plain ABAP Unit test.

DATA(sim) = z2ui5_cl_frontend_simulator=>start( `Z2UI5_CL_FRONTEND_SIM_EXAMPLE` ).

sim->set_value( name = `MV_NAME` value = `World` ).
sim->click( `GREET` ).

cl_abap_unit_assert=>assert_equals( exp = `Hello World!`
                                    act = sim->get_message( ) ).

That is a full user session: typed a name, pressed a button, read the result back. It runs in milliseconds, needs no server, no browser driver and no network, and it fails with an ABAP stack trace pointing at your app.

Why

Testing abap2UI5 apps is currently all-or-nothing. You either unit-test the pieces around the app — which skips the part where the app actually talks to the framework — or you drive a real browser with Playwright/Selenium, which is slow, flaky, needs a deployed system, and breaks whenever the layout moves. There is nothing in between.

The simulator is the in-between. It exercises the real framework: the real main( ) dispatch, the real event handling, the real model serialisation, the real draft handling. Only the browser is missing — and the browser was never the part with your bugs in it.

Apps are addressed by the names their author already wrote. MV_NAME is the bound attribute (client->_bind( mv_name )), GREET is the event id (client->_event( 'GREET' )). No CSS selectors, no control ids, no XPath. A test does not break when someone swaps a VBox for a Grid, because a user pressing "Greet" does not care either. The rendered XML is still there via get_view( ) when you do want to assert on it.

The bigger idea

If the frontend contract can be served from ABAP, the browser is not the only possible frontend — it is just the first one.

A headless module that speaks this protocol is the seam where other frontends attach: SAP GUI, a console renderer, a REST facade, a batch driver that replays recorded sessions — or an AI agent. The agent addon exposes abap2UI5 apps over an ABAP-native MCP endpoint and uses this simulator as its engine: every MCP call is one HTTP request, so it starts an app, resume( )s the session in the next request, and builds its screen snapshot from get_layers( ), get_messages( ), get_actions( ) and get_events( ).

See ROADMAP.md for where it goes from here.

API

Driving the app

layer is optional everywhere: an edit goes into, and an event is fired from, the topmost open layer unless another one is named.

The setters, close_layer( ), click( ) and set_check_events( ) return the instance, so a whole session fits in one statement:

DATA(msg) = z2ui5_cl_frontend_simulator=>start( `Z2UI5_CL_FRONTEND_SIM_EXAMPLE`
    )->set_value( name  = `MV_NAME`
                  value = `World`
    )->click( `GREET`
    )->get_message( ).

Typed edits

The browser does not send text only: a CheckBox writes a boolean into its model, a MultiComboBox an array of keys, a StepInput a number. set_json( path json ) queues exactly such a value; set_value( ), set_bool( ), set_cell( ), set_row( ) and select_row( ) are shorthands for it, so every edit takes the same way:

sim->set_bool( `MV_ACTIVE`
    )->set_json( path = `MT_KEY`
                 json = `["A","C"]`
    )->set_value( name  = `MS_ORDER/NAME`
                  value = `Max`
    )->select_row( table  = `MT_ROW`
                   row    = 2
                   column = `SELKZ`
    )->click( `SAVE` ).

• An edit goes into the model of its layer — the own copy of an open popup or popover, else the MAIN model the nested views share — and travels with the next event of that layer. An event of another layer leaves it pending; closing its layer drops it. This is the frontend's rule (View1 _pickModelForRoundtrip).
• The delta is the frontend's (Lib.buildDeltaFromPaths), built from the layer's model with every edit applied: a table cell (/TAB/1/COL, nested /TAB/1/SUB/0/COL) goes out as a row delta TAB.__delta.1.COL, every other path — a scalar, a structure field, an array element, a cell of a table inside a structure — as the whole top-level attribute. A whole value queued next to a delta of the same attribute wins, a later edit of a path replaces the earlier one.
• Model paths count rows from 0, as the frontend records them (/MS_ORDER/T_POS/1/QTY is the second position). set_cell( ), set_row( ) and select_row( ) take ABAP's 1-based row.
• What went out stays in the layer's model, as in the browser — the backend leaves an unchanged model out of its response, so get_value( ) reads the sent value back afterwards. A pending edit is not visible there.
• get_request_json( ) shows the request as it went out, the delta included.

Reading the screen

Layers

The frontend has five view slots, and the simulator keeps them the same way:

• MAIN — the page. A new main view is a new screen: it takes the nested views, the popup and the popover down with it.
• NEST, NEST2 — nested views inserted into a control of the main view (anchor_id). They own no model; get_layers( ) reports the main model they inherit.
• POPUP, POPOVER — standalone, on top of the page, each with its own copy of the model. A popover remembers the control it opens by (anchor_id). Both die when the response names another app.

A response's model is pushed into every open layer that belongs to the app that answered — exactly the frontend's rule, so a popup of a called app does not see the caller's model.

A layer the browser closes on its own — _event_client( cs_event-popup_close ) — is closed with close_layer( ): no roundtrip, the backend is not told, the layer and the unsent edits of its model are gone, and get_state( ) no longer carries it.

Event validation

check_event_exists( ) and get_events( ) read the event wires (.eB(['NAME',...])) out of the active layer: an open popover, else an open popup — dialogs are modal — else the main view with its nested views. With set_check_events( ) on, click( ) refuses an event the user could not reach and names the ones they could. A click( ) that names the MAIN layer while a popup is open is refused as well — a dialog is modal. It is a check on the view XML, not on a control tree: visibility and enablement are not evaluated, and events raised by timers or keyboard shortcuts are not wired in a view.

get_ids( ) and check_id_exists( ) read the id="..." attributes of the same layers the same way - only the ids the app wrote into its view, the backend generates none. They are what the journey recorder of abap2UI5's developer tools (Ctrl+F12, Roundtrips > Journey) asserts with: it records a click-through in the browser and exports an ABAP Unit test that replays it on this simulator, checking the ids and events the recorded screens showed.

Resuming a session

Every start( ) / click( ) is one roundtrip, and the draft id is the whole backend state of a draft-based app — which is what lets a session continue in another request, another work process:

" request 1
DATA(sim) = z2ui5_cl_frontend_simulator=>start( `Z2UI5_CL_FRONTEND_SIM_LAYERS` ).
sim->click( `POPUP_OPEN` ).
DATA(id)    = sim->get_id( ).
DATA(state) = sim->get_state( ).

" request 2
sim = z2ui5_cl_frontend_simulator=>resume( id = id state = state ).
sim->set_value( name = `MV_POPUP_TEXT` value = `Bea` )->click( `POPUP_CONFIRM` ).

What resume( ) does and does not do:

• It sends what the browser sends. No roundtrip happens on resume( ); the next click( ) posts the draft id, the pending delta and the event, and the backend restores the app from the draft. Nothing else is needed on the backend side.
• The view comes from state. The backend does not keep view XML — the browser does. Pass the get_state( ) string of the previous request and the layers (XML and model per layer) are back. A state that belongs to another draft id is refused.
• Without state the instance knows the app class and the model from the draft, but no view and no layer: get_value( ) works, get_view( ) is empty, and set_check_events( ) would refuse every event.
• refresh = abap_true re-requests the view with the request a browser reload sends for a routed app (#/app/<class>/<draft>): the app runs check_on_navigated( ) and, written the canonical way, displays its main view again. A popup is back only if the app re-opens it there. The restore mints a new draft id.
• Sticky apps cannot be resumed. A stateful session (client->set_session_stateful( )) keeps the app in the handler, not in a draft — the id it reports has no draft behind it, and resume( ) raises. Within one instance a sticky app works normally (is_sticky( ) tells).
• The draft must still exist and belong to the current user — the draft service binds drafts to their creator and expires them after a few hours.

Each start( ) / click( ) is exactly one roundtrip. Sticky apps keep their handler between roundtrips, draft-based apps chain their state through the persisted id — the same distinction z2ui5_cl_ui5_http_handler=>_http_post makes, so what you test is what runs in production.

Contents

The simulator's own unit tests live in z2ui5_cl_frontend_simulator.clas.testclasses.abap and drive both example apps and the form app. They double as the usage documentation:

• ltcl_frontend_simulator (RISK LEVEL HARMLESS) installs an in-memory draft store through the core's store seam (z2ui5_cl_ui5_srv_draft=>set_instance), so even the draft path writes nothing to the database.
• ltcl_frontend_simulator_db (RISK LEVEL DANGEROUS) runs against the real store — Z2UI5_T_01 and its commits — including the rollback bracket the framework puts around main( ) in the draft path, and deletes every draft it created in teardown.

Installation

Install with abapGit. Requires abap2UI5 in the same system, at a version that speaks wire protocol 2 (S_FRONT.S_ACTION) — a response that names another protocol is refused with PROTOCOL_MISMATCH. Runs on ABAP Standard, ABAP Cloud and — via the downport in CI — 7.02.

The simulator works on the core's engine (z2ui5_cl_ui5_handler and the draft service), which is not part of abap2UI5's released API in src/02 — a core change there can require a change here.

Current scope

Covered: the main view, nested views, popup and popover with their models, messages with severity, follow-up actions, the browser-history intent, typed edits (booleans, arrays, numbers, structures with tables) with the frontend's delta per layer model, table row deltas including nested tables, row selection, closing a layer in the browser, sticky and draft sessions, app-to-app navigation, resuming a session across requests, and an opt-in check that an event is wired in the active layer.

Not covered yet: an injectable frontend CONFIG (device, UI5 version, focus, scroll), a control tree with visibility and enablement, and set_value( ) validation against the bound paths. ROADMAP.md has the plan and the order.

Contributing

See CONTRIBUTING.md. Every change must leave abaplint at zero issues.

License

MIT — see LICENSE.