robotframework-velo-sapgui

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

Contents

• Installation
• Quick start
• Library setup
• Locators
• Keyword reference
• Generating keyword documentation
• 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. Cleanup is safe as a test teardown (closes SAP, keeps the Java gateway) or as 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.

By default, friendly locators, Press Key, Screenshot, and Print Elements target the SAP active window (so modal dialogs like wnd[1] work without hard-coding the index). If the control is not on that window, other session windows are tried next. An absolute sap_id that includes wnd[n] always wins.

Use Print Elements while developing to inspect the preferred window.

Window targeting

Keyword	Description
Select Window	Sticky override: ACTIVE (default), MAIN / 0, 1 / wnd[1], or a full window id
Clear Window	Clear override (same as Select Window ACTIVE)

Still pinned to the main window by design: window_state after Connect, Open Transaction (ok-code field), and Select Menu Path (main menubar).

# Modal opens as the active window — no wnd[1] needed:
Click    Continue
Press Enter

# Explicitly pin to the main frame while a modal is up:
Select Window    0
Type             Sold-to Party    1000
Clear Window

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	—	NI route, e.g. /H/host/S/3200 or /H/router/S/3299/H/host/S/3200. /S/ defaults to 3299. Hop password: /W/pass or legacy /P/pass on the next hop. Optional conn= prefix is stripped.
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
Connect    /H/router/W/pass/H/10.0.1.55/S/3200    SystemId=S4H

SNC query parameters (&sncon=true&sncqop=9&manualLogin=true&systemName=SID) are supported on SAP GUI for Java / Velo cloud only. The Windows COM OpenConnection backend does not apply them.

Open Transaction

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

Always uses the main window ok-code field (wnd[0]).

Open Transaction    VA01

Select Window

Pin subsequent locate / key / screenshot calls to a specific window.

Argument	Default	Description
specifier	ACTIVE	ACTIVE, MAIN/0, 1/wnd[1], or full window id

Select Window    1
Select Window    ACTIVE

Clear Window

Clear a sticky override and follow the SAP active window again.

Clear Window

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

Set Checkbox / Check / Uncheck

Set a GuiCheckBox state.

Argument	Default	Description
locator	—	Checkbox label / name
selected	True	Desired state (Set Checkbox only)
sap_id		Optional technical id

Check          Express delivery
Uncheck        Express delivery
Set Checkbox   Express delivery    False

Select Radio Button

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

Select Radio Button    Standard Order

Select Combo Box

Select a GuiComboBox entry by key, value/text, or index.

Argument	Default	Description
locator	—	Combo box label / name
value	—	Key, display text, or index
by	key	key, value / text, or index
sap_id		Optional technical id

Select Combo Box    Sales Document Type    OR
Select Combo Box    Sales Document Type    Standard Order    by=value

Select Tab

Select a GuiTab page.

Select Tab    Sales
Select Tab    Item Overview

Select Menu Path

Walk the main menubar (GuiMenubar / GuiMenu). Separators: /, ;, >.

Select Menu Path    System/Status

Type Grid Cell / Get Grid Cell

Interact with a GuiGridView (ALV). Distinct from Type Cell (GuiTableControl).

Type Grid Cell    0    MATNR    NS0002
${val}=    Get Grid Cell    0    MATNR

Expand / Collapse / Select Tree Node

Operate on a GuiTree. Pass a node key, or a path containing /.

Expand Tree Node     000001
Select Tree Node     Materials/Finished
Collapse Tree Node   000001

Type Textedit / Get Textedit

Multiline GuiTextedit control (not a dynpro GuiTextField).

Type Textedit    Long text    Hello from Velo
${text}=    Get Textedit

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

Get Session Info

Read a GuiSessionInfo property from the active session.

Argument	Description
attribute	e.g. User, Client, Transaction, Program, SystemName

${user}=    Get Session Info    User
${tcode}=   Get Session Info    Transaction

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

Close the SAP application and stop recording. Safe as a per-test teardown: the Java gateway stays up so the next Connect in the same suite can reopen SAP.

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.

Generating keyword documentation

The keyword reference above is maintained by hand, but the library is fully documented in code (@keyword docstrings, argument types, and the reST-formatted class/__init__ docs), so you can also generate a browsable HTML page with Robot Framework's libdoc tool — useful after changing a keyword's signature or docstring, or for offline reference.

pip install -e ".[dev]"        # installs robotframework + docutils (reST renderer)
scripts/gen_libdoc.sh          # writes docs/VeloSapguiLibrary.html

Equivalent, if you'd rather not use the helper script:

python -m robot.libdoc VeloSapguiLibrary docs/VeloSapguiLibrary.html

libdoc also supports .xml (libspec, for IDE integrations) and .json output — just change the output file's extension. Pass --version to stamp a specific release, e.g. python -m robot.libdoc --version 0.6.2 VeloSapguiLibrary docs/VeloSapguiLibrary.html.

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
• SNC (sncon=true) → Java/cloud backend only; logon is still user/password (manualLogin=true)

Changelog

See CHANGELOG.md.