crosslocator 0.2.0__tar.gz

crosslocator-0.2.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Robot Framework outputs
+output.xml
+log.html
+report.html

crosslocator-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Becheny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crosslocator-0.2.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: crosslocator
+Version: 0.2.0
+Summary: Define a UI selector once, resolve it on every platform (Android, iOS, iPadOS, Windows, web).
+Project-URL: Homepage, https://github.com/julien-becheny/crosslocator
+Project-URL: Repository, https://github.com/julien-becheny/crosslocator
+Project-URL: Issues, https://github.com/julien-becheny/crosslocator/issues
+Author: Julien Becheny
+License: MIT
+License-File: LICENSE
+Keywords: android,appium,ios,locators,mobile-testing,playwright,robotframework,selectors,test-automation,windows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Robot Framework :: Library
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crosslocator
+
+**Define a UI selector once. Resolve it on every platform.**
+
+Cross-platform test automation means maintaining the same element for Android,
+iOS, iPadOS, Windows and the web. Most teams end up either duplicating selectors
+or scattering `if platform == ...` branches through their page objects.
+
+`crosslocator` lets you declare a selector **once**, per platform, and resolves
+the right one at runtime — from **pure Python (Appium), Robot Framework, or any
+other framework**. It only routes selector *strings*; it never wraps your driver.
+
+```python
+from crosslocator import Locator
+
+ADD_PATIENT = Locator(
+    android="accessibility_id=add_patient",
+    ios="add_patient",
+    windows='//Button[@Name="Add"]',
+    default="id=add",
+)
+
+ADD_PATIENT.for_platform("ios")   # -> "add_patient"
+```
+
+## Installation
+
+```bash
+pip install crosslocator
+```
+
+Zero runtime dependencies.
+
+## Why
+
+- **One source of truth** per element — no duplicated selectors, no platform `if/else`.
+- **Framework-agnostic** — Appium in plain Python, Robot Framework, or anything else.
+- **Sensible fallbacks** — iPad inherits from iOS, and a shared `default` covers the rest.
+- **Typed** and dependency-free.
+
+## Quick start (Python)
+
+```python
+from crosslocator import Locator, set_current_platform
+
+ADD_PATIENT = Locator(
+    android="accessibility_id=add_patient",
+    ios="add_patient",
+    windows='//Button[@Name="Add"]',
+)
+
+set_current_platform("android")   # usually done once, at session start
+ADD_PATIENT.resolve()             # -> "accessibility_id=add_patient"
+```
+
+## Robot Framework
+
+```robotframework
+*** Settings ***
+Library     crosslocator.robot.CrossLocator
+Variables   locators.py        # ADD_PATIENT defined as a Locator here
+
+*** Test Cases ***
+Open Add Patient
+    Set Current Platform    android
+    ${selector}=    Resolve Locator    ${ADD_PATIENT}
+    # -> pass ${selector} to AppiumLibrary / Browser as usual
+```
+
+## How the platform is resolved
+
+`resolve()` determines the current platform in this order:
+
+1. an explicit `set_current_platform(...)`
+2. the `CROSSLOCATOR_PLATFORM` environment variable
+3. a registered provider — typically an Appium session (see below)
+
+## Automatic platform detection (Appium)
+
+Let crosslocator read the platform straight from a live Appium session, so you
+never call `set_current_platform` by hand.
+
+**Python (Appium-Python-Client):**
+
+```python
+from crosslocator import use_appium
+
+use_appium(driver)      # your Appium webdriver
+LOGIN_BUTTON.resolve()  # platform detected from the session capabilities
+```
+
+**Robot Framework (AppiumLibrary):**
+
+```robotframework
+Open Application    ${REMOTE_URL}    platformName=Android    ...
+Use Appium Session
+${selector}=    Resolve Locator    ${LOGIN_BUTTON}
+```
+
+iPad is detected from the session device name and resolves to iPad selectors
+(falling back to iOS when none are defined).
+
+## Fallback rules
+
+- `ipad` → falls back to `ios` when no iPad-specific selector is set
+- any platform → falls back to `default`
+- nothing found → `LocatorNotFound`
+
+## Examples
+
+Runnable examples (no device needed) live in the [`examples/`](examples/) folder —
+a login screen resolved across Android, iOS, iPadOS and Windows, plus a Robot
+Framework suite.
+
+## Roadmap
+
+- **v0.1:** the core `Locator` type, platform resolution, Robot Framework keywords.
+- **v0.2 (current):** automatic platform detection from a live Appium session.
+- **Next:** Playwright/Browser helpers, and declarative loading of whole screens from YAML/dict.
+
+Issues and contributions are welcome.
+
+## License
+
+MIT © 2026 Julien Becheny

crosslocator-0.2.0/README.md

@@ -0,0 +1,125 @@
+# crosslocator
+
+**Define a UI selector once. Resolve it on every platform.**
+
+Cross-platform test automation means maintaining the same element for Android,
+iOS, iPadOS, Windows and the web. Most teams end up either duplicating selectors
+or scattering `if platform == ...` branches through their page objects.
+
+`crosslocator` lets you declare a selector **once**, per platform, and resolves
+the right one at runtime — from **pure Python (Appium), Robot Framework, or any
+other framework**. It only routes selector *strings*; it never wraps your driver.
+
+```python
+from crosslocator import Locator
+
+ADD_PATIENT = Locator(
+    android="accessibility_id=add_patient",
+    ios="add_patient",
+    windows='//Button[@Name="Add"]',
+    default="id=add",
+)
+
+ADD_PATIENT.for_platform("ios")   # -> "add_patient"
+```
+
+## Installation
+
+```bash
+pip install crosslocator
+```
+
+Zero runtime dependencies.
+
+## Why
+
+- **One source of truth** per element — no duplicated selectors, no platform `if/else`.
+- **Framework-agnostic** — Appium in plain Python, Robot Framework, or anything else.
+- **Sensible fallbacks** — iPad inherits from iOS, and a shared `default` covers the rest.
+- **Typed** and dependency-free.
+
+## Quick start (Python)
+
+```python
+from crosslocator import Locator, set_current_platform
+
+ADD_PATIENT = Locator(
+    android="accessibility_id=add_patient",
+    ios="add_patient",
+    windows='//Button[@Name="Add"]',
+)
+
+set_current_platform("android")   # usually done once, at session start
+ADD_PATIENT.resolve()             # -> "accessibility_id=add_patient"
+```
+
+## Robot Framework
+
+```robotframework
+*** Settings ***
+Library     crosslocator.robot.CrossLocator
+Variables   locators.py        # ADD_PATIENT defined as a Locator here
+
+*** Test Cases ***
+Open Add Patient
+    Set Current Platform    android
+    ${selector}=    Resolve Locator    ${ADD_PATIENT}
+    # -> pass ${selector} to AppiumLibrary / Browser as usual
+```
+
+## How the platform is resolved
+
+`resolve()` determines the current platform in this order:
+
+1. an explicit `set_current_platform(...)`
+2. the `CROSSLOCATOR_PLATFORM` environment variable
+3. a registered provider — typically an Appium session (see below)
+
+## Automatic platform detection (Appium)
+
+Let crosslocator read the platform straight from a live Appium session, so you
+never call `set_current_platform` by hand.
+
+**Python (Appium-Python-Client):**
+
+```python
+from crosslocator import use_appium
+
+use_appium(driver)      # your Appium webdriver
+LOGIN_BUTTON.resolve()  # platform detected from the session capabilities
+```
+
+**Robot Framework (AppiumLibrary):**
+
+```robotframework
+Open Application    ${REMOTE_URL}    platformName=Android    ...
+Use Appium Session
+${selector}=    Resolve Locator    ${LOGIN_BUTTON}
+```
+
+iPad is detected from the session device name and resolves to iPad selectors
+(falling back to iOS when none are defined).
+
+## Fallback rules
+
+- `ipad` → falls back to `ios` when no iPad-specific selector is set
+- any platform → falls back to `default`
+- nothing found → `LocatorNotFound`
+
+## Examples
+
+Runnable examples (no device needed) live in the [`examples/`](examples/) folder —
+a login screen resolved across Android, iOS, iPadOS and Windows, plus a Robot
+Framework suite.
+
+## Roadmap
+
+- **v0.1:** the core `Locator` type, platform resolution, Robot Framework keywords.
+- **v0.2 (current):** automatic platform detection from a live Appium session.
+- **Next:** Playwright/Browser helpers, and declarative loading of whole screens from YAML/dict.
+
+Issues and contributions are welcome.
+
+## License
+
+MIT © 2026 Julien Becheny

crosslocator-0.2.0/examples/README.md

@@ -0,0 +1,27 @@
+# Examples
+
+These examples use a generic **login screen** and need no real device. They
+resolve the same locators on several platforms to show what crosslocator does.
+
+## Python
+
+```bash
+cd examples/python
+python demo.py
+```
+
+Prints the same page object resolved for Android, iOS, iPadOS and Windows —
+notice iPad falls back to the iOS selector, and Windows uses the shared default.
+
+## Robot Framework
+
+Requires Robot Framework:
+
+```bash
+pip install robotframework
+robot examples/robot/login.robot
+```
+
+The suite resolves locators for Android, iOS and iPadOS and asserts the expected
+selector strings — a self-contained check that the Robot Framework integration
+works end to end.

crosslocator-0.2.0/examples/python/demo.py

@@ -0,0 +1,30 @@
+"""Resolve the same page object on several platforms.
+
+Run from this folder::
+
+    python demo.py
+
+Notice that iPad falls back to the iOS selector, and Windows uses the shared
+default when no Windows-specific selector applies.
+"""
+from crosslocator import set_current_platform
+
+from locators import LOGIN_BUTTON, PASSWORD_FIELD, USERNAME_FIELD
+
+ELEMENTS = {
+    "Username field": USERNAME_FIELD,
+    "Password field": PASSWORD_FIELD,
+    "Login button": LOGIN_BUTTON,
+}
+
+
+def show_for(platform: str) -> None:
+    set_current_platform(platform)
+    print(f"\n== {platform} ==")
+    for name, locator in ELEMENTS.items():
+        print(f"  {name:16} -> {locator.resolve()}")
+
+
+if __name__ == "__main__":
+    for current in ("android", "ios", "ipad", "windows"):
+        show_for(current)

crosslocator-0.2.0/examples/python/locators.py

@@ -0,0 +1,25 @@
+"""Example page object: a login screen, defined once for every platform.
+
+Each element is declared a single time, with its selector per platform. There
+is no duplication and no `if platform == ...` branching in the test code.
+"""
+from crosslocator import Locator
+
+USERNAME_FIELD = Locator(
+    android="id=com.example:id/username",
+    ios="accessibility_id=username",
+    windows='//Edit[@AutomationId="username"]',
+)
+
+PASSWORD_FIELD = Locator(
+    android="id=com.example:id/password",
+    ios="accessibility_id=password",
+    windows='//Edit[@AutomationId="password"]',
+)
+
+LOGIN_BUTTON = Locator(
+    android="accessibility_id=login",
+    ios="accessibility_id=login",
+    windows='//Button[@Name="Log in"]',
+    default="id=login",
+)

crosslocator-0.2.0/examples/robot/locators.py

@@ -0,0 +1,22 @@
+"""Robot Framework variable file: exposes Locator objects as suite variables.
+
+Imported from login.robot via `Variables   locators.py`. Each name becomes a
+Robot scalar variable, e.g. ${USERNAME_FIELD}.
+"""
+from crosslocator import Locator
+
+USERNAME_FIELD = Locator(
+    android="id=com.example:id/username",
+    ios="accessibility_id=username",
+)
+
+PASSWORD_FIELD = Locator(
+    android="id=com.example:id/password",
+    ios="accessibility_id=password",
+)
+
+LOGIN_BUTTON = Locator(
+    android="accessibility_id=login",
+    ios="accessibility_id=login",
+    default="id=login",
+)

crosslocator-0.2.0/examples/robot/login.robot

@@ -0,0 +1,21 @@
+*** Settings ***
+Library     crosslocator.robot.CrossLocator
+Variables   locators.py
+
+*** Test Cases ***
+Resolve Login Selectors On Android
+    Set Current Platform    android
+    ${username}=    Resolve Locator    ${USERNAME_FIELD}
+    ${login}=       Resolve Locator    ${LOGIN_BUTTON}
+    Should Be Equal    ${username}    id=com.example:id/username
+    Should Be Equal    ${login}       accessibility_id=login
+
+Resolve Login Selectors On iOS
+    Set Current Platform    ios
+    ${username}=    Resolve Locator    ${USERNAME_FIELD}
+    Should Be Equal    ${username}    accessibility_id=username
+
+iPad Falls Back To The iOS Selector
+    Set Current Platform    ipad
+    ${login}=    Resolve Locator    ${LOGIN_BUTTON}
+    Should Be Equal    ${login}    accessibility_id=login

crosslocator-0.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crosslocator"
+version = "0.2.0"
+description = "Define a UI selector once, resolve it on every platform (Android, iOS, iPadOS, Windows, web)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Julien Becheny" }]
+keywords = [
+    "test-automation",
+    "appium",
+    "robotframework",
+    "playwright",
+    "mobile-testing",
+    "android",
+    "ios",
+    "windows",
+    "locators",
+    "selectors",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Framework :: Robot Framework :: Library",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/julien-becheny/crosslocator"
+Repository = "https://github.com/julien-becheny/crosslocator"
+Issues = "https://github.com/julien-becheny/crosslocator/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/crosslocator"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

crosslocator-0.2.0/src/crosslocator/__init__.py

@@ -0,0 +1,29 @@
+"""crosslocator — define a UI selector once, resolve it on every platform."""
+from .appium import use_appium
+from .locator import (
+    CrossLocatorError,
+    Locator,
+    LocatorNotFound,
+    PlatformNotSet,
+)
+from .platform import (
+    Platform,
+    get_current_platform,
+    set_current_platform,
+    set_platform_provider,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Locator",
+    "Platform",
+    "get_current_platform",
+    "set_current_platform",
+    "set_platform_provider",
+    "use_appium",
+    "CrossLocatorError",
+    "LocatorNotFound",
+    "PlatformNotSet",
+    "__version__",
+]

crosslocator-0.2.0/src/crosslocator/appium.py

@@ -0,0 +1,55 @@
+"""Automatic platform detection from a live Appium session.
+
+crosslocator stays framework-agnostic: this module only reads the session
+capabilities and translates them into a :class:`~crosslocator.platform.Platform`.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from .platform import Platform, set_platform_provider
+
+
+def platform_from_capabilities(
+    capabilities: Optional[Mapping[str, Any]],
+) -> Optional[Platform]:
+    """Translate Appium capabilities into a :class:`Platform`.
+
+    Returns ``None`` when the platform cannot be determined.
+    """
+    if not capabilities:
+        return None
+    name = str(
+        capabilities.get("platformName")
+        or capabilities.get("appium:platformName")
+        or ""
+    ).strip().lower()
+    device = str(
+        capabilities.get("deviceName")
+        or capabilities.get("appium:deviceName")
+        or ""
+    ).lower()
+    if name == "android":
+        return Platform.ANDROID
+    if name in ("ios", "iphoneos", "iphone os"):
+        return Platform.IPAD if "ipad" in device else Platform.IOS
+    if name in ("windows", "win"):
+        return Platform.WINDOWS
+    return None
+
+
+def use_appium(driver: Optional[Any]) -> None:
+    """Detect the current platform automatically from an Appium ``driver``.
+
+    Registers a provider that reads ``driver.capabilities`` on each resolution,
+    so you no longer need to call :func:`set_current_platform` by hand. Pass
+    ``None`` to stop using the driver.
+    """
+    if driver is None:
+        set_platform_provider(None)
+        return
+
+    def provider() -> Optional[Platform]:
+        return platform_from_capabilities(getattr(driver, "capabilities", None))
+
+    set_platform_provider(provider)

crosslocator-0.2.0/src/crosslocator/locator.py

@@ -0,0 +1,107 @@
+"""The :class:`Locator` type: define a selector once, resolve it per platform."""
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+from .platform import (
+    Platform,
+    PlatformLike,
+    get_current_platform,
+    normalize_platform,
+)
+
+
+class CrossLocatorError(Exception):
+    """Base class for all crosslocator errors."""
+
+
+class PlatformNotSet(CrossLocatorError):
+    """Raised when a resolution needs the current platform but none is set."""
+
+
+class LocatorNotFound(CrossLocatorError, LookupError):
+    """Raised when no selector is available for the requested platform."""
+
+
+# A platform inherits from the next one in its chain when it has no own selector.
+_FALLBACK_CHAINS: Dict[Platform, tuple] = {
+    Platform.IPAD: (Platform.IPAD, Platform.IOS),
+}
+
+
+class Locator:
+    """A UI selector declared once for several platforms.
+
+    Define a selector per platform plus an optional shared ``default``. At
+    runtime, :meth:`resolve` (or :meth:`for_platform`) returns the right
+    selector string. crosslocator only *routes* strings — it never parses them
+    nor touches your driver.
+    """
+
+    __slots__ = ("_selectors", "_default")
+
+    def __init__(
+        self,
+        *,
+        android: Optional[str] = None,
+        ios: Optional[str] = None,
+        ipad: Optional[str] = None,
+        windows: Optional[str] = None,
+        web: Optional[str] = None,
+        default: Optional[str] = None,
+    ) -> None:
+        self._selectors: Dict[Platform, Optional[str]] = {
+            Platform.ANDROID: android,
+            Platform.IOS: ios,
+            Platform.IPAD: ipad,
+            Platform.WINDOWS: windows,
+            Platform.WEB: web,
+        }
+        self._default = default
+        if default is None and not any(self._selectors.values()):
+            raise ValueError(
+                "A Locator needs at least one platform selector or a default."
+            )
+
+    def for_platform(self, platform: PlatformLike) -> str:
+        """Return the selector for ``platform``, applying fallbacks.
+
+        Resolution order: the platform's own selector, then its fallback chain
+        (e.g. iPad -> iOS), then ``default``. Raises :class:`LocatorNotFound`
+        if nothing matches.
+        """
+        target = normalize_platform(platform)
+        for candidate in _FALLBACK_CHAINS.get(target, (target,)):
+            value = self._selectors.get(candidate)
+            if value is not None:
+                return value
+        if self._default is not None:
+            return self._default
+        raise LocatorNotFound(
+            f"No selector defined for platform {target.value!r} and no default set."
+        )
+
+    def resolve(self) -> str:
+        """Return the selector for the current platform.
+
+        Raises :class:`PlatformNotSet` when the current platform is unknown.
+        """
+        platform = get_current_platform()
+        if platform is None:
+            raise PlatformNotSet(
+                "No current platform set. Use set_current_platform(...) or the "
+                "CROSSLOCATOR_PLATFORM environment variable."
+            )
+        return self.for_platform(platform)
+
+    def __repr__(self) -> str:
+        parts = {p.value: v for p, v in self._selectors.items() if v is not None}
+        if self._default is not None:
+            parts["default"] = self._default
+        inner = ", ".join(f"{k}={v!r}" for k, v in parts.items())
+        return f"Locator({inner})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Locator):
+            return NotImplemented
+        return self._selectors == other._selectors and self._default == other._default

crosslocator-0.2.0/src/crosslocator/platform.py

@@ -0,0 +1,89 @@
+"""Platform identification and current-platform state.
+
+crosslocator resolves selectors against a *current platform*. This module owns
+the small enum of supported platforms, alias normalization, and the resolution
+of the current platform from (in priority order):
+
+1. an explicit value set via :func:`set_current_platform`
+2. the ``CROSSLOCATOR_PLATFORM`` environment variable
+3. a registered provider (e.g. reading a live Appium session)
+"""
+from __future__ import annotations
+
+import os
+from enum import Enum
+from typing import Callable, Optional, Union
+
+
+class Platform(Enum):
+    """A UI platform a selector can target."""
+
+    ANDROID = "android"
+    IOS = "ios"
+    IPAD = "ipad"
+    WINDOWS = "windows"
+    WEB = "web"
+
+
+PlatformLike = Union[Platform, str]
+
+ENV_VAR = "CROSSLOCATOR_PLATFORM"
+
+_ALIASES = {
+    "android": Platform.ANDROID,
+    "ios": Platform.IOS,
+    "iphone": Platform.IOS,
+    "ipad": Platform.IPAD,
+    "ipados": Platform.IPAD,
+    "windows": Platform.WINDOWS,
+    "win": Platform.WINDOWS,
+    "web": Platform.WEB,
+    "browser": Platform.WEB,
+}
+
+_current: Optional[Platform] = None
+_provider: Optional[Callable[[], Optional[PlatformLike]]] = None
+
+
+def normalize_platform(value: PlatformLike) -> Platform:
+    """Return the :class:`Platform` for ``value``, accepting common aliases.
+
+    Raises :class:`ValueError` for unknown platforms.
+    """
+    if isinstance(value, Platform):
+        return value
+    key = str(value).strip().lower()
+    try:
+        return _ALIASES[key]
+    except KeyError:
+        raise ValueError(f"Unknown platform: {value!r}") from None
+
+
+def set_current_platform(value: Optional[PlatformLike]) -> None:
+    """Set (or clear, with ``None``) the platform used to resolve selectors."""
+    global _current
+    _current = None if value is None else normalize_platform(value)
+
+
+def set_platform_provider(
+    provider: Optional[Callable[[], Optional[PlatformLike]]],
+) -> None:
+    """Register a callable returning the current platform (e.g. from Appium).
+
+    Pass ``None`` to unregister.
+    """
+    global _provider
+    _provider = provider
+
+
+def get_current_platform() -> Optional[Platform]:
+    """Resolve the current platform, or ``None`` if it cannot be determined."""
+    if _current is not None:
+        return _current
+    env = os.environ.get(ENV_VAR)
+    if env:
+        return normalize_platform(env)
+    if _provider is not None:
+        result = _provider()
+        return None if result is None else normalize_platform(result)
+    return None

crosslocator-0.2.0/src/crosslocator/robot.py

@@ -0,0 +1,51 @@
+"""Robot Framework integration for crosslocator.
+
+Import in a suite with::
+
+    Library    crosslocator.robot.CrossLocator
+
+Locators are plain Python objects: define them in a Python variable file and
+import them, then resolve them with the keywords below.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .locator import Locator
+from .platform import get_current_platform, set_current_platform
+
+
+class CrossLocator:
+    """Robot Framework library exposing crosslocator as keywords."""
+
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+
+    def set_current_platform(self, platform: str) -> None:
+        """Set the platform used to resolve locators.
+
+        Accepts ``android``, ``ios``, ``ipad``, ``windows`` or ``web``.
+        """
+        set_current_platform(platform)
+
+    def get_current_platform(self) -> str:
+        """Return the current platform name, or an empty string if unset."""
+        platform = get_current_platform()
+        return platform.value if platform is not None else ""
+
+    def resolve_locator(self, locator: Locator, platform: Optional[str] = None) -> str:
+        """Resolve a ``Locator`` to a selector string.
+
+        Uses ``platform`` when given, otherwise the current platform.
+        """
+        if platform:
+            return locator.for_platform(platform)
+        return locator.resolve()
+
+    def use_appium_session(self) -> None:
+        """Auto-detect the platform from the active AppiumLibrary session."""
+        from robot.libraries.BuiltIn import BuiltIn
+
+        from .appium import use_appium
+
+        appium_lib = BuiltIn().get_library_instance("AppiumLibrary")
+        use_appium(appium_lib._current_application())

crosslocator-0.2.0/tests/test_appium.py

@@ -0,0 +1,49 @@
+import pytest
+
+from crosslocator import (
+    Platform,
+    get_current_platform,
+    set_current_platform,
+    use_appium,
+)
+from crosslocator.appium import platform_from_capabilities
+from crosslocator.platform import set_platform_provider
+
+
+class FakeDriver:
+    def __init__(self, capabilities):
+        self.capabilities = capabilities
+
+
+@pytest.mark.parametrize(
+    "caps, expected",
+    [
+        ({"platformName": "Android"}, Platform.ANDROID),
+        ({"platformName": "iOS"}, Platform.IOS),
+        ({"platformName": "iOS", "deviceName": "iPad Pro"}, Platform.IPAD),
+        ({"appium:platformName": "Windows"}, Platform.WINDOWS),
+        ({}, None),
+        (None, None),
+        ({"platformName": "Symbian"}, None),
+    ],
+)
+def test_platform_from_capabilities(caps, expected):
+    assert platform_from_capabilities(caps) is expected
+
+
+def test_use_appium_drives_resolution(monkeypatch):
+    monkeypatch.delenv("CROSSLOCATOR_PLATFORM", raising=False)
+    set_current_platform(None)
+    use_appium(FakeDriver({"platformName": "Android"}))
+    try:
+        assert get_current_platform() is Platform.ANDROID
+    finally:
+        set_platform_provider(None)
+
+
+def test_use_appium_none_clears_provider(monkeypatch):
+    monkeypatch.delenv("CROSSLOCATOR_PLATFORM", raising=False)
+    set_current_platform(None)
+    use_appium(FakeDriver({"platformName": "iOS"}))
+    use_appium(None)
+    assert get_current_platform() is None

crosslocator-0.2.0/tests/test_locator.py

@@ -0,0 +1,56 @@
+import pytest
+
+from crosslocator import Locator, LocatorNotFound, PlatformNotSet, set_current_platform
+
+
+def test_for_platform_returns_specific_selector():
+    loc = Locator(android="id=add", ios="add_btn")
+    assert loc.for_platform("android") == "id=add"
+    assert loc.for_platform("ios") == "add_btn"
+
+
+def test_ipad_falls_back_to_ios():
+    loc = Locator(ios="add_btn")
+    assert loc.for_platform("ipad") == "add_btn"
+
+
+def test_ipad_prefers_its_own_selector():
+    loc = Locator(ios="add_btn", ipad="ipad_add")
+    assert loc.for_platform("ipad") == "ipad_add"
+
+
+def test_default_used_when_platform_missing():
+    loc = Locator(android="id=add", default="id=fallback")
+    assert loc.for_platform("windows") == "id=fallback"
+
+
+def test_missing_selector_raises():
+    loc = Locator(android="id=add")
+    with pytest.raises(LocatorNotFound):
+        loc.for_platform("windows")
+
+
+def test_resolve_uses_current_platform():
+    loc = Locator(android="id=add", ios="add_btn")
+    set_current_platform("ios")
+    try:
+        assert loc.resolve() == "add_btn"
+    finally:
+        set_current_platform(None)
+
+
+def test_resolve_without_platform_raises():
+    loc = Locator(android="id=add")
+    set_current_platform(None)
+    with pytest.raises(PlatformNotSet):
+        loc.resolve()
+
+
+def test_empty_locator_is_rejected():
+    with pytest.raises(ValueError):
+        Locator()
+
+
+def test_repr_is_readable():
+    loc = Locator(android="id=add", default="id=x")
+    assert repr(loc) == "Locator(android='id=add', default='id=x')"

crosslocator-0.2.0/tests/test_platform.py

@@ -0,0 +1,40 @@
+import pytest
+
+from crosslocator import Platform, get_current_platform, set_current_platform
+from crosslocator.platform import ENV_VAR, normalize_platform, set_platform_provider
+
+
+def test_normalize_aliases():
+    assert normalize_platform("Android") is Platform.ANDROID
+    assert normalize_platform("iPadOS") is Platform.IPAD
+    assert normalize_platform("win") is Platform.WINDOWS
+
+
+def test_unknown_platform_raises():
+    with pytest.raises(ValueError):
+        normalize_platform("symbian")
+
+
+def test_explicit_platform_takes_priority(monkeypatch):
+    monkeypatch.setenv(ENV_VAR, "android")
+    set_current_platform("ios")
+    try:
+        assert get_current_platform() is Platform.IOS
+    finally:
+        set_current_platform(None)
+
+
+def test_env_var_used_when_no_explicit(monkeypatch):
+    set_current_platform(None)
+    monkeypatch.setenv(ENV_VAR, "windows")
+    assert get_current_platform() is Platform.WINDOWS
+
+
+def test_provider_used_as_last_resort(monkeypatch):
+    set_current_platform(None)
+    monkeypatch.delenv(ENV_VAR, raising=False)
+    set_platform_provider(lambda: "android")
+    try:
+        assert get_current_platform() is Platform.ANDROID
+    finally:
+        set_platform_provider(None)