Metadata-Version: 2.4
Name: robotframework-velo-sapgui
Version: 0.2.4
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** on Java (py4j) and Windows (COM Scripting).

## Backends

| Backend | Platform | Prerequisites |
|---|---|---|
| `java` | Linux Docker / Mac via Docker | SAP GUI for Java + `sapgui-engine` gateway on port 8081 |
| `windows` | Native Windows laptop | Customer-installed SAP GUI for Windows + scripting enabled |
| `auto` | Default | `windows` on win32, `java` elsewhere |

Set `Library    VeloSapguiLibrary    client=auto` or export `VELO_SAP_CLIENT=java|windows|auto`.

## Architecture

```
.robot suite
    │
    └─► VeloSapguiLibrary (Python)
              │
              ├─► JavaGatewayBackend ── py4j ──► sapgui-engine ──► SAP GUI for Java
              │
              └─► WindowsScriptingBackend ── COM ──► SAP GUI for Windows
```

Connection is **lazy** — resources are opened on the first keyword.

## Installation

```bash
pip install robotframework-velo-sapgui

# Windows COM backend
pip install "robotframework-velo-sapgui[windows]"
```

## Usage

```robotframework
*** Settings ***
Library    VeloSapguiLibrary    client=auto    port=8081    recording=True

*** Test Cases ***
Create Sales Order
    Connect             /H/my-sap-host/S/3200
    Type                User        MY_USER
    Type                Password    ${PASSWORD}
    Press Enter
    Open Transaction    VA01
    [Teardown]          Cleanup
```

Credentials and connection strings live **in each suite** so multi-role SAP flows can switch users within one test.

## Scripting event capture

`recording=True` captures SAP scripting **interaction events** (not video) to `events.jsonl` under `$RESULTS_DIR`:

```json
{"timestamp": "...", "action": "Type", "element_id": "...", "name": "User", "type": "", "value": "MY_USER", "screen_context": "...", "source": "automation"}
```

Optional keywords: `Start Event Capture`, `Stop Event Capture`, `Get Captured Events`.

Video MP4 for cloud runs is produced by the execution container (`entrypoint.sh`), not this library.

## Library arguments

| Argument | Default | Description |
|---|---|---|
| `client` | `auto` | SAP client backend: `auto`, `java`, or `windows` |
| `port` | `8081` | Java gateway port (`java` backend only) |
| `recording` | `False` | Start scripting event capture on first connect |

## Environment variables

| Variable | Description |
|---|---|
| `VELO_SAP_CLIENT` | Override `client` library argument |
| `RESULTS_DIR` | Output directory for screenshots and `events.jsonl` |
| `VELO_EVENTS_PATH` | Override path for event capture file |

## SAP prerequisites

- Server: `sapgui/user_scripting = TRUE`
- Client: SAP GUI scripting enabled
- Optional: `sapgui/user_scripting_disable_recording = 0` (avoid recorder dialog during event capture)

## Error handling

- `SapConnectionError` — backend not reachable or scripting disabled
- `SapKeywordError` — SAP action failed; message included in RF output
