robotframework-velo-sapgui 0.2.2__tar.gz

robotframework_velo_sapgui-0.2.2/LICENSE

@@ -0,0 +1,49 @@
+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

robotframework_velo_sapgui-0.2.2/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: robotframework-velo-sapgui
+Version: 0.2.2
+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"
+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    SapLibrary    client=auto` or export `VELO_SAP_CLIENT=java|windows|auto`.
+
+## Architecture
+
+```
+.robot suite
+    │
+    └─► SapLibrary (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    SapLibrary    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

robotframework_velo_sapgui-0.2.2/README.md

@@ -0,0 +1,93 @@
+# 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    SapLibrary    client=auto` or export `VELO_SAP_CLIENT=java|windows|auto`.
+
+## Architecture
+
+```
+.robot suite
+    │
+    └─► SapLibrary (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    SapLibrary    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

robotframework_velo_sapgui-0.2.2/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=70,<81", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "robotframework-velo-sapgui"
+version = "0.2.2"
+description = "Robot Framework keyword library for SAP GUI automation (Java and Windows)"
+readme = { file = "README.md", content-type = "text/markdown" }
+license = { file = "LICENSE" }
+authors = [{ name = "Velo", email = "legal@velo.com" }]
+keywords = ["robotframework", "SAP", "SAP GUI", "automation", "sapgui", "py4j", "testing"]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Framework :: Robot Framework",
+    "Framework :: Robot Framework :: Library",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Testing :: Acceptance",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: Other/Proprietary License",
+    "Typing :: Typed",
+]
+dependencies = [
+    "robotframework>=6.1,<8",
+    "py4j>=0.10.9,<1",
+    "pywin32>=306; sys_platform == 'win32'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov",
+    "ruff>=0.4",
+    "mypy>=1.10",
+    "build>=1.2",
+    "twine>=5",
+]
+
+[project.urls]
+Homepage = "https://github.com/velo-org/robotframework-velo-sapgui"
+Repository = "https://github.com/velo-org/robotframework-velo-sapgui"
+"Bug Tracker" = "https://github.com/velo-org/robotframework-velo-sapgui/issues"
+Changelog = "https://github.com/velo-org/robotframework-velo-sapgui/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+SapLibrary = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=SapLibrary --cov-report=term-missing"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true
+warn_return_any = false

robotframework_velo_sapgui-0.2.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

robotframework_velo_sapgui-0.2.2/src/SapLibrary/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from SapLibrary.exceptions import SapConnectionError, SapKeywordError, SapLibraryError
+
+try:
+    __version__ = version("robotframework-velo-sapgui")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = [
+    "SapLibrary",
+    "SapLibraryError",
+    "SapConnectionError",
+    "SapKeywordError",
+    "__version__",
+]
+
+
+def __getattr__(name: str) -> object:
+    if name == "SapLibrary":
+        from SapLibrary.library import SapLibrary
+
+        globals()["SapLibrary"] = SapLibrary
+        return SapLibrary
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

robotframework_velo_sapgui-0.2.2/src/SapLibrary/backends/__init__.py

@@ -0,0 +1,5 @@
+"""SAP automation backends (Java gateway and Windows COM)."""
+
+from SapLibrary.backends.base import SapAutomationBackend, resolve_client
+
+__all__ = ["SapAutomationBackend", "resolve_client"]

robotframework_velo_sapgui-0.2.2/src/SapLibrary/backends/base.py

@@ -0,0 +1,70 @@
+"""Backend interface for SAP GUI automation (Java gateway or Windows COM)."""
+
+from __future__ import annotations
+
+import os
+import sys
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+def resolve_client(client: str | None = None) -> str:
+    """Resolve SAP client type: ``auto``, ``java``, or ``windows``."""
+    raw = (client or os.getenv("VELO_SAP_CLIENT") or "auto").strip().lower()
+    if raw not in ("auto", "java", "windows"):
+        raise ValueError(f"Invalid SAP client '{client}'. Expected auto, java, or windows.")
+    if raw == "auto":
+        return "windows" if sys.platform == "win32" else "java"
+    if raw == "windows" and sys.platform != "win32":
+        raise RuntimeError(
+            "SAP GUI for Windows backend requires a Windows host. "
+            "Use client=java or VELO_SAP_CLIENT=java for Docker/Java execution."
+        )
+    return raw
+
+
+class BackendResponse:
+    """Minimal response object compatible with Java StepResponse accessors."""
+
+    def __init__(self, success: bool, message: str = "", result: Any = None) -> None:
+        self._success = success
+        self._message = message
+        self._result = result
+
+    def isSuccessful(self) -> bool:
+        return self._success
+
+    def getMessage(self) -> str:
+        return self._message
+
+    def getResult(self) -> Any:
+        return self._result
+
+
+class SapAutomationBackend(ABC):
+    """Abstract SAP automation backend."""
+
+    @abstractmethod
+    def ensure_connected(self) -> None:
+        """Open backend resources if needed."""
+
+    @abstractmethod
+    def call(self, method: str, *args: Any) -> Any:
+        """Invoke a facade method by name."""
+
+    @abstractmethod
+    def start_event_capture(self) -> None:
+        """Begin scripting event capture."""
+
+    @abstractmethod
+    def stop_event_capture(self) -> str | None:
+        """Stop event capture and return output path."""
+
+    @abstractmethod
+    def cleanup(self, close_app: bool = True, stop_recording: bool = True) -> str:
+        """Release backend resources."""
+
+    @property
+    @abstractmethod
+    def client_name(self) -> str:
+        """Backend identifier (``java`` or ``windows``)."""

robotframework_velo_sapgui-0.2.2/src/SapLibrary/backends/event_capture.py

@@ -0,0 +1,78 @@
+"""Normalized scripting event log (events.jsonl) shared by Java and Windows backends."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from threading import Lock
+from typing import Any
+
+
+class EventCaptureWriter:
+    """Append-only JSONL writer for SAP GUI scripting interaction events."""
+
+    def __init__(self, output_path: Path | None = None) -> None:
+        results_dir = os.environ.get("RESULTS_DIR", "/results")
+        default_path = Path(results_dir) / "events.jsonl"
+        env_path = os.environ.get("VELO_EVENTS_PATH")
+        self._path = Path(output_path or env_path or default_path)
+        self._active = False
+        self._lock = Lock()
+        self._events: list[dict[str, Any]] = []
+
+    @property
+    def is_active(self) -> bool:
+        return self._active
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def start(self) -> None:
+        with self._lock:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._events = []
+            self._active = True
+
+    def record(
+        self,
+        action: str,
+        *,
+        element_id: str = "",
+        name: str = "",
+        element_type: str = "",
+        value: str = "",
+        screen_context: str = "",
+        source: str = "",
+    ) -> None:
+        if not self._active:
+            return
+        event = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "action": action,
+            "element_id": element_id,
+            "name": name,
+            "type": element_type,
+            "value": value,
+            "screen_context": screen_context,
+            "source": source,
+        }
+        with self._lock:
+            self._events.append(event)
+
+    def stop(self) -> str:
+        with self._lock:
+            if not self._active:
+                return str(self._path)
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            with self._path.open("w", encoding="utf-8") as handle:
+                for event in self._events:
+                    handle.write(json.dumps(event, ensure_ascii=False) + "\n")
+            self._active = False
+            return str(self._path)
+
+    def get_events(self) -> list[dict[str, Any]]:
+        with self._lock:
+            return list(self._events)