robotframework-velo-sapgui

Robot Framework keyword library for SAP GUI automation (Java and Windows).

Contents

• Installation
• Quick start
• Library setup
• Locators
• Keyword reference
• Prerequisites & errors

Installation

pip install robotframework-velo-sapgui

# Native Windows COM backend (includes pywin32)
pip install "robotframework-velo-sapgui[windows]"

Quick start

*** Settings ***
Library    VeloSapguiLibrary
Suite Teardown    Cleanup

*** Test Cases ***
Create Sales Order
    Connect             /H/my-sap-host/S/3200    SystemId=S4H
    Type                User                     ${SAP_USER}
    Type                Password                 ${SAP_PASSWORD}
    Press Enter
    Open Transaction    VA01
    Type                Sales Document Type      or
    Type Cell           Material                 0    NS0002
    Press Key           Ctrl+S
    Click               Continue
    Verify              Status Bar    MessageType    Contains    S
    ${order}=           Get Status Bar    MessageParameter[1]
    Screenshot          order_saved.png    PNG
    Log                 Order number: ${order}

Put credentials and connection strings in the suite (or variables) so multi-role flows can switch users within one test.

Library setup

Defaults are remote-safe (Velo / Java containers). Most suites need no import args:

Library    VeloSapguiLibrary

Override only when needed:

Library    VeloSapguiLibrary    screenshot_log=file    window_state=normal
Library    VeloSapguiLibrary    gateway_port=9090      # Java only, non-default port

Configuration knobs

Precedence: Library import → environment variable → built-in default.

Argument	Env	Default	Description
client	VELO_SAP_CLIENT	auto	Backend: auto, java, or windows. auto → Windows on win32, Java elsewhere.
gateway_port	VELO_GATEWAY_PORT or GATEWAY_PORT	8081	Java py4j gateway port (ignored on Windows). port= is a deprecated alias.
recording	VELO_RECORDING	False	Start scripting event capture on first connect (events.jsonl).
screenshot_log	VELO_SCREENSHOT_LOG	embed	How screenshots appear in log.html: embed (base64), file (relative img), none.
window_state	VELO_WINDOW_STATE	maximized	Applied after Connect: maximized or normal.

Other env	Description
RESULTS_DIR	Output directory for screenshots and events.jsonl
VELO_EVENTS_PATH	Override path for the events file

Backend	When	Needs
java	Docker / Linux / remote Velo	SAP GUI for Java + sapgui-engine on gateway_port
windows	Native Windows	SAP GUI for Windows + scripting enabled

Scope is SUITE — one connection is shared across tests. Call Cleanup in suite teardown.

Architecture: .robot → VeloSapguiLibrary → Java gateway (py4j) or Windows COM scripting.

Locators

Most interaction keywords take:

Argument	Required	Description
locator	usually yes	Friendly label, field name, or tooltip text (e.g. User, Sold-to Party)
sap_id	no	Technical SAP id fallback (e.g. wnd[0]/usr/txtRSYST-BNAME)

Java resolves labels via name, tooltip, visible text, and label→input sibling pairing.
Windows matches primarily on element Name (plus sap_id). Prefer sap_id when labels differ across clients.

Use Print Elements while developing to inspect the current screen.

Keyword reference

Robot Framework turns snake_case methods into title-case keywords (open_transaction → Open Transaction).

Connection & navigation

Connect

Connect to SAP with a logon connection string.

Argument	Default	Description
connection_string	—	e.g. /H/host/S/3200 or /H/router/S/3299/H/host/S/3200
system_id		SID (e.g. S4H). Use for SAP router / headless trust classification.

Connect    /H/my-sap-host/S/3200
Connect    /H/34.1.2.3/S/3299/H/10.0.9.1/S/3200    SystemId=S4H

Open Transaction

Argument	Description
transaction_name	Transaction code (e.g. VA01, SE38, /nex)

Open Transaction    VA01

Input

Type

Type text into a field.

Argument	Default	Description
locator	—	Friendly field label / name
text	—	Value to enter
sap_id		Optional technical id

Type    User        MY_USER
Type    Password    ${PASSWORD}
Type    Sold-to Party    17100003    sap_id=wnd[0]/usr/ctxtKUAGV-KUNNR

Type Cell

Type into a table cell (first visible table control).

Argument	Description
column_name	Column header / tooltip
row_index	Zero-based row (string or int)
text	Value to enter

Type Cell    Material         0    NS0002
Type Cell    Order Quantity   0    1

Interaction

Click

Click a button (or button-like control).

Argument	Default	Description
locator	—	Button label / name
sap_id		Optional technical id

Click    Continue

Press Enter

Press Enter (VKey 0), optionally scoped to an element.

Argument	Default	Description
locator		Optional element scope
sap_id		Optional technical id

Press Enter

Press Ctrl S

Press Ctrl+S (Save). Prefer this over Press Key Ctrl+S on Java.

Argument	Default	Description
locator		Optional element scope
sap_id		Optional technical id

Press Ctrl S

Press Key

Press a virtual key by name.

Argument	Default	Description
key	—	Key name (see below)
locator		Optional element / window scope
sap_id		Optional technical id

Common keys: ENTER, F1–F12, CTRL+S, CTRL+C, CTRL+V, SHIFT+F3, PAGEUP, PAGEDOWN.

Press Key    Ctrl+S
Press Key    F3

Introspection

Store

Read an attribute from an element. Returns the value.

Argument	Default	Description
locator	—	Element label / name
attribute	—	e.g. text, tooltip, messageType, messageParameter[1]
sap_id		Optional technical id

${value}=    Store    User    text

Get Status Bar

Read an attribute from the status bar (shortcut for Store sbar …).

Argument	Description
attribute	e.g. text, MessageType, MessageParameter[1]

${order}=    Get Status Bar    MessageParameter[1]
${msg}=      Get Status Bar    text

Print Elements

Dump the visible element tree (for suite development). Returns the dump string.

Print Elements

Verification

Verify

Assert an element attribute against an expected value.

Argument	Default	Description
locator	—	Element label (Status Bar → status bar)
attribute	—	Attribute to check
operator	—	equals, contains, or doesNotContain
expected_value	—	Expected value
sap_id		Optional technical id

Verify    Status Bar    MessageType    Contains    S
Verify    User          text           Equals      MY_USER

Screenshots

Screenshot

Capture the SAP GUI window and embed the image in the Robot log.

• Windows: SAP GUI Scripting HardCopy (supports optional element crop).
• Java: tries hardCopy / HardCopy; if the JS bridge does not expose them (common), falls back to OS scrot (full display). Element crop is not available in that fallback.

Argument	Default	Description
name	—	File name or absolute path
type	PNG	BMP, JPG, PNG, GIF, TIFF, or 0–4 (ignored by Java OS fallback)
locator		Optional element to crop (Windows / scripting only)
sap_id		Optional technical id

Relative name values go under ${OUTPUT DIR} or RESULTS_DIR. Returns the absolute path. By default the image is inlined in log.html as base64 (screenshot_log=embed) so it displays in Velo without a separate PNG artifact. Use screenshot_log=file for relative <img src> links when PNGs sit next to the log.

Screenshot    login.png    PNG
Screenshot    user.png     PNG    User
Screenshot    user.png     type=PNG    locator=User    sap_id=wnd[0]/usr/txtRSYST-BNAME

Take Screenshot

Direct OS-level capture (scrot on Linux, window capture on Windows). Prefer Screenshot, which uses scripting when available and falls back to OS capture on Java.

Argument	Default	Description
filename	auto	e.g. login.png (.png appended if missing)

Take Screenshot    failure.png

Lifecycle & event capture

Cleanup

Suite teardown helper: stop recording and/or close the app, release resources.

Argument	Default	Description
close_app	True	Close the SAP application
stop_recording	True	Stop event capture

[Teardown]    Cleanup
Cleanup    close_app=False

Close Application

Close the current SAP application session without the full cleanup helper.

Close Application

Start Event Capture / Stop Event Capture / Get Captured Events

Manual control when recording=False. Events are scripting interactions (not video), written to events.jsonl.

Start Event Capture
# … steps …
${path}=      Stop Event Capture
@{events}=    Get Captured Events

Or enable automatically:

Library    VeloSapguiLibrary    recording=True

Video MP4 for cloud runs is produced by the execution container, not this library.

Prerequisites & errors

SAP

• Server: sapgui/user_scripting = TRUE
• Client: scripting enabled
• Optional: sapgui/user_scripting_disable_recording = 0 (avoids recorder dialog during capture)

Errors

Exception	Typical cause
SapConnectionError	Gateway down, SAP GUI missing, or scripting disabled
SapKeywordError	Action failed or element not found (message includes details)

Tips

• Element not found → try Print Elements, then add sap_id
• Java vs Windows label differences → pass sap_id as fallback
• Router / headless trust dialog → pass SystemId on Connect

Changelog

See CHANGELOG.md.