SAPFX: Robot Framework libraries for testing SAP

pip install robotframework-sapfx

SAPFX automates SAP tests in Robot Framework through three libraries that share one business vocabulary: the SAP GUI desktop client, SAP Fiori and SAPUI5 apps in the browser, and the OData/RFC API channel. A test reads the same whichever channel it drives, and one run can cross all three (prepare data through the API, drive the screen for what you actually test, check the result through another channel). Because they also write, delete and cross-check their own writes through two channels, the same libraries are heading beyond testing, towards test data, populated databases and controlled loads (see "Beyond testing" below for what is proven and what is not yet).

This repository publishes the library sources, their documentation and the keyword reference. The libraries are distributed on PyPI as robotframework-sapfx.

A fourth package, sapfx_common, holds the pure logic the three share (polling, healing scores, perception diff, human-locator engine, table extraction contract, visual hashing...). Some of its modules are Robot libraries in their own right, documented in their docstrings rather than in the keyword reference: Library sapfx_common.table_csv (also table_json, table_xlsx, table_svg, table_parquet) writes an extraction and reads it back, sapfx_common.table_extract carries the shared Table Extract Should Be Complete guard, sapfx_common.artifacts writes and re-reads deterministic JSON artifacts, and sapfx_common.rap_preview builds the Fiori Elements preview path of a RAP service.

📖 Keyword documentation: one reference page per library, every keyword with its arguments and examples.

Install

pip install robotframework-sapfx            # the three libraries
pip install "robotframework-sapfx[web]"     # + Browser library, for SapFioriLibrary
rfbrowser init                              # one-time: Playwright browsers

Other extras: visual (Pillow, for screen baselines) and parquet (pyarrow, for Parquet exports). Requirements per channel:

• All: Python 3.10 or later, Robot Framework 7.4 or later.
• SapEccLibrary: Windows, SAP GUI for Windows, and scripting enabled on the server (RZ11 sapgui/user_scripting) and on the client. Scripting Should Be Fully Enabled checks both and names the parameter to fix. Pin pywin32 exactly in your environment file: it is the first source of COM breakage.
• SapFioriLibrary: the web extra and rfbrowser init. No SAP system is needed to try it: the public OpenUI5 Demo Kit is a valid target.
• RFC in SapApiLibrary (optional): pyrfc, pinned (pip install pyrfc==3.3.1: SAP archived the project and every PyPI release is yanked, so pip no longer picks one by itself; prebuilt wheels up to Python 3.12 only), and the SAP NW RFC runtime, which a SAP GUI for Windows 8.00 installation usually provides already (component "SAP NWRFC x64 Shared"). Without it, the RFC keywords say so and the rest of the library works.

A free local SAP system to test against (ABAP Platform Trial in Docker), and the SAP-side prerequisites, are described in docs/testing-without-sap.md.

Quick start

SAP GUI (credentials on the command line: robot -v "PASSWORD: Secret:..." suite.robot; the Robot Framework 7.4 typed variable keeps the password out of the logs, even at TRACE level):

*** Settings ***
Library    SapEccLibrary

*** Variables ***
${CONNECTION}    MY SYSTEM
${USER}          DEVELOPER
${PASSWORD}      ${EMPTY}
${GRID}          wnd[0]/usr/cntlGRID1/shellcont/shell

*** Test Cases ***
Read The Clients Table In SE16
    Open Sap Logon
    Connect To Session With Retry
    Open Connection    ${CONNECTION}
    Input Text        wnd[0]/usr/txtRSYST-BNAME    ${USER}
    Input Password    wnd[0]/usr/pwdRSYST-BCODE    ${PASSWORD}
    Send Vkey    0
    Scripting Should Be Fully Enabled
    Use ALV Grid In Data Browser
    Input Text    wnd[0]/usr/ctxtDATABROWSE-TABLENAME    T000
    Send Vkey    0
    Send Vkey    8
    ${rows}=    Read Full Grid    ${GRID}
    Log    ${rows}

In a real project, the SAP element ids live in a resource file of business keywords, and the test cases speak business language only.

SAP Fiori / SAPUI5 (runs as is against the public OpenUI5 Demo Kit):

*** Settings ***
Library    Browser
Library    SapFioriLibrary    ui5_timeout=20s

*** Test Cases ***
Search The API Reference
    New Browser    chromium    headless=True
    New Page       https://sdk.openui5.org/#/api
    Fill Ui5 Input    Button    controlType=SearchField
    ${xpath}=    Get Ui5 Xpath    controlType=SearchField
    Log    ${xpath}
    [Teardown]    Close Browser

OData (a SAP Gateway service, here the EPM demo shop of the ABAP trial):

*** Settings ***
Library    SapApiLibrary

*** Variables ***
${PASSWORD}    ${EMPTY}

*** Test Cases ***
Count The Products
    Open Api Session    http://localhost:50000    user=DEVELOPER
    ...                 password=${PASSWORD}    sap_client=001
    ${count}=    Get Odata Count    /sap/opu/odata/sap/SEPMRA_SHOP/Products
    Should Be True    ${count} > 0
    ${first}=    Get Odata Entities    /sap/opu/odata/sap/SEPMRA_SHOP/Products    top=3
    Length Should Be    ${first}    3
    [Teardown]    Close All Api Sessions

What the libraries bring

• Real synchronisation, never fixed sleeps: Wait Until Busy Done, Wait Until Element Present (SAP GUI), Wait For Ui5 Idle (network, busy indicators and a continuous quiet period, on UI5 and non-UI5 pages).
• Locale-independent assertions: Run Transaction judges the status-bar message type, never its translated text; Get Status Message Identity reads class, type and number; Ui5 Should Have No Messages Of Type does the same on the web. Dates and numbers are typed in the user's own format (Input Date, Input Number, Fill Ui5 Date), and a screen's display or change mode is read from a field (Element Should Be Changeable), never from its translated title.
• Tables read as data: ALV grids by column title (Read Grid, Read Full Grid, Get Grid Column Titles), table controls, trees, classic ABAP lists, UI5 tables and SAP GUI for HTML grids; one extraction contract for all channels, which refuses a partial reading instead of passing it for a complete one, and five export formats (CSV, JSON Lines, XLSX, SVG, Parquet).
• Human locators (SAP GUI): Fill Field By Label, Click Button By Label, Read Field By Label, by visible label and geometry; an ambiguity is always reported with its candidates, never resolved by a silent first match.
• Five resolution engines on the web: UI5 role and hierarchical xpath (//Table//Button[@text='Edit']), sid for SAP GUI for HTML, wc for UI5 Web Components pages without a classic runtime, and dom (ARIA role and accessible name) for the non-SAP parts of hybrid pages; nested iframes of launchpads through a frame stack; Get Page Composition says which technology lives where.
• Locator healing, never silent: failures list the closest ids on screen, scored; Resolve Element With Healing and Resolve Ui5 With Fallback repair a stale locator with a logged warning and an optional telemetry journal.
• Screen perception for debugging and AI agents: Get Screen Signature, Get Screen Map (numbered actionable targets), Get Ui5 Page Tree, diff mode, annotated screenshots.
• Visual assertions where the Scripting API sees nothing (opaque shells, charts): perceptual-hash baselines per screen, per element or per tile.
• Preflights that name their remedy: scripting on server and client, workstation security posture, Gateway activation, RFC channel availability; and the ABAP server's security configuration read over RFC (profile parameters judged on their return code, drift against a committed reference).
• The API channel as a data platform: full OData CRUD with CSRF, $batch, server-driven paging, $metadata perception with human labels, a test-data factory that cleans up after itself, BAPIs judged by message type and refusals asserted by message identifier, RFC table reads, background jobs and their spool, outbound IDocs (create, wait on the status code, link to the inbound IDoc by its TID), change documents.
• Several SAP GUI sessions by alias in one suite, SAP Fiori launchpad navigation by intent and login through an identity provider, tile counters read as numbers (Get Flp Tile Counter), and identity readings (release, kernel, client; over HTTP alone with Get Abap Software Components) that prove which system a test is really talking to.

Teams that test UI5 apps with JavaScript tooling will know wdi5, the reference outside Robot Framework. SAPFX does not replace it: its scope is SAP test automation in Robot Framework, where the desktop client, the API channel and Fiori share one vocabulary, one runner and one report.

Beyond testing

The libraries were built to test SAP, and that stays their core. What makes a test trustworthy (write a record through one channel, read it back through another, independent one, delete it, and confirm it is gone) also works outside a test. Three uses follow from it:

• Test data sets: creating complete, consistent data sets, identifiable as test data, to feed test campaigns.
• Populating databases for performance testing: filling empty or incomplete SAP databases before a load campaign.
• Configuration and migration loads: loading complex business data into a target environment, and cross-checking the load through a second channel, for instance in an ECC to S/4HANA migration.

To be precise about where this stands: writing, deleting and cross-checking through two channels are validated live on SAP development systems, never on a customer system. The three uses themselves are a direction, not delivered features. There is no data-set generator in the libraries yet, no volume or load time has been measured, and no migration has been run. The angle for migrations is scripted loading plus cross-checking, not replacing SAP's own load and migration tools.

Documentation

Every document exists in English and in French (*.fr.md). They were written alongside the libraries in the maintainer's workbench: when they mention a business resource layer (resources/), Robot suites (tests/robot/), recorders or test agents, they describe that workbench, which is not part of this repository.

Layout

src/SapEccLibrary/      SAP GUI for Windows (COM); _vendor/ holds the upstream
                        library verbatim, keywords/ one mixin per capability
src/SapFioriLibrary/    Fiori / UI5 / Web Components / SAP GUI for HTML
                        (Browser library); injected JavaScript in *.js.tpl
src/SapApiLibrary/      OData v2/v4 and optional RFC / BAPI
src/sapfx_common/       shared pure logic
docs/                   library documentation (EN/FR), docs/libdoc/ = keyword pages

Issues

Bug reports and suggestions are welcome as GitHub issues.

License

Apache 2.0. Includes vendored code from robotframework-sapguilibrary, locator engines ported from playwright-sap and techniques adapted from RoboSAPiens and playwright-praman; see LICENSE and NOTICE.

Trademarks

SAP, SAP ECC, SAP S/4HANA, SAP Fiori, SAP BTP, SAP HANA, SAP NetWeaver, SAP GUI, SAPUI5, ABAP and the other SAP products and services mentioned are trademarks or registered trademarks of SAP SE or its affiliates in Germany and in other countries. SAPFX is an independent open-source project, not affiliated with, sponsored or endorsed by SAP SE.