Metadata-Version: 2.4
Name: robotframework-velo-sapgui
Version: 0.5.0
Summary: Robot Framework keyword library for SAP GUI automation (Java and Windows)
Author-email: Velo <legal@velo.com>
License: Copyright (c) 2026 Velo. All rights reserved.
        
        PROPRIETARY SOFTWARE LICENSE
        
        This software and its source code, documentation, and associated files
        (collectively, the "Software") are the exclusive property of Velo and are
        protected by copyright law and international treaties.
        
        GRANT OF LICENSE
        
        Velo grants you a limited, non-exclusive, non-transferable, non-sublicensable
        license to use the Software solely for your internal business purposes,
        strictly in accordance with any agreement entered into with Velo.
        
        RESTRICTIONS
        
        You may not, and you may not permit any third party to:
        
          1. Copy, modify, adapt, translate, or create derivative works of the Software;
          2. Reverse engineer, disassemble, decompile, or otherwise attempt to derive
             the source code of the Software;
          3. Sell, sublicense, rent, lease, transfer, or otherwise make the Software
             available to any third party;
          4. Remove or alter any proprietary notices, labels, or marks on the Software;
          5. Use the Software for any purpose other than as expressly permitted
             under this license.
        
        NO WARRANTY
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL VELO BE
        LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF
        THE SOFTWARE.
        
        TERMINATION
        
        This license is effective until terminated. It will terminate automatically
        if you fail to comply with any of its terms. Upon termination, you must
        immediately cease all use of the Software and destroy any copies in your
        possession.
        
        GOVERNING LAW
        
        This license shall be governed by and construed in accordance with applicable
        law. Any disputes arising under this license shall be subject to the exclusive
        jurisdiction of the competent courts.
        
        For licensing inquiries, contact: legal@velo.com
Project-URL: Homepage, https://github.com/velo-org/robotframework-velo-sapgui
Project-URL: Repository, https://github.com/velo-org/robotframework-velo-sapgui
Project-URL: Bug Tracker, https://github.com/velo-org/robotframework-velo-sapgui/issues
Project-URL: Changelog, https://github.com/velo-org/robotframework-velo-sapgui/blob/main/CHANGELOG.md
Keywords: robotframework,SAP,SAP GUI,automation,sapgui,py4j,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Framework :: Robot Framework
Classifier: Framework :: Robot Framework :: Library
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Acceptance
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: Other/Proprietary License
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: robotframework<8,>=6.1
Requires-Dist: py4j<1,>=0.10.9
Requires-Dist: pywin32>=306; sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: pyarmor>=8; extra == "dev"
Dynamic: license-file

# robotframework-velo-sapgui

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

## Contents

- [Installation](#installation)
- [Quick start](#quick-start)
- [Library setup](#library-setup)
- [Locators](#locators)
- [Keyword reference](#keyword-reference)
- [Prerequisites & errors](#prerequisites--errors)

## Installation

```bash
pip install robotframework-velo-sapgui

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

## Quick start

```robotframework
*** 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:

```robotframework
Library    VeloSapguiLibrary
```

Override only when needed:

```robotframework
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. |

```robotframework
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`) |

```robotframework
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 |

```robotframework
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 |

```robotframework
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 |

```robotframework
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 |

```robotframework
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 |

```robotframework
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 |

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

#### Select Tab

Select a `GuiTab` page.

```robotframework
Select Tab    Sales
Select Tab    Item Overview
```

#### Select Menu Path

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

```robotframework
Select Menu Path    System/Status
```

#### Type Grid Cell / Get Grid Cell

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

```robotframework
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 `/`.

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

#### Type Textedit / Get Textedit

Multiline `GuiTextedit` control (not a dynpro `GuiTextField`).

```robotframework
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 |

```robotframework
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 |

```robotframework
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`.

```robotframework
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 |

```robotframework
${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]` |

```robotframework
${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` |

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

#### Print Elements

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

```robotframework
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 |

```robotframework
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.

```robotframework
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) |

```robotframework
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 |

```robotframework
[Teardown]    Cleanup
Cleanup    close_app=False
```

#### Close Application

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

```robotframework
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`.

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

Or enable automatically:

```robotframework
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](CHANGELOG.md).
