pantoqa-bridge 0.4.4__py3-none-any.whl

pantoqa_bridge/routes/misc.py

@@ -0,0 +1,74 @@
+import asyncio
+from typing import Any
+
+import aiohttp
+from fastapi import APIRouter
+from packaging import version as pkg_version
+
+from pantoqa_bridge.config import APPIUM_SERVER_URL, PKG_NAME
+from pantoqa_bridge.utils.pkg import get_latest_package_version, get_pkg_version, upgrade_package
+from pantoqa_bridge.utils.process import kill_self_process
+
+route = APIRouter()
+
+_appium_utility_version = get_pkg_version("appium_utility")
+_pkg_version = get_pkg_version(PKG_NAME)
+_lastest_pkg_version: pkg_version.Version | None = None
+
+
+async def _unset_pkg_version(timeout: int):
+  global _lastest_pkg_version
+  await asyncio.sleep(timeout)
+  _lastest_pkg_version = None
+
+
+@route.get("/health", tags=["misc"])
+@route.get("/status", tags=["misc"])
+async def status() -> dict[str, Any]:
+  global _lastest_pkg_version
+  if not _lastest_pkg_version:
+    _lastest_pkg_version = get_latest_package_version(PKG_NAME)
+    asyncio.create_task(_unset_pkg_version(timeout=900))  # unset after 15 minutes
+
+  return {
+    "status": "ok",
+    "version": str(_pkg_version),
+    "lastest_version": str(_lastest_pkg_version),
+    "outdated": _lastest_pkg_version > _pkg_version,
+    "appium_utility_version": str(_appium_utility_version),
+  }
+
+
+@route.get("/upgrade-bridge", tags=["misc"])
+async def update_bridge():
+  curent_pkg_version = get_pkg_version(PKG_NAME)
+  latest_pkg_version = get_latest_package_version(PKG_NAME)
+
+  if latest_pkg_version <= curent_pkg_version:
+    return {
+      "status": "success",
+      "details": "already using the latest version.",
+    }
+
+  upgrade_package(PKG_NAME)
+
+  async def kill_after_delay():
+    await asyncio.sleep(2)
+    kill_self_process()
+
+  asyncio.create_task(kill_after_delay())
+
+  return {
+    "status": "success",
+    "details": "Package upgraded successfully."
+               " Please restart the application to apply the updates.",
+  }
+
+
+@route.get("/appium-status", tags=["misc"])
+async def get_appium_status():
+  async with aiohttp.ClientSession() as session:
+    res = await session.get(f"{APPIUM_SERVER_URL}/status")
+    res.raise_for_status()
+    data = await res.json()
+  return data

pantoqa_bridge/routes/screen_mirror.py

@@ -0,0 +1,75 @@
+import asyncio
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+from pantoqa_bridge.lib.scrcpy import ScrcpyPyClient
+
+route = APIRouter()
+
+
+@route.websocket("/ws/mirror")
+async def ws_endpoint(ws: WebSocket):
+  await ws.accept()
+  streaming: ScreenMirrorOverWS | None = None
+  try:
+    params = ws.query_params
+    max_size = int(params["max_size"]) if params.get("max_size") else None
+    params["device_serial"] if params.get('device_serial') else None
+    streaming = ScreenMirrorOverWS(ws, max_size)
+    await streaming.stream()  # blocking call
+    await streaming.teardown()
+  except WebSocketDisconnect:
+    print("WebSocket disconnected.")
+    if streaming:
+      await streaming.teardown()
+  except Exception as e:
+    print(f"Error in WebSocket endpoint: {e}")
+    if streaming:
+      await streaming.teardown()
+
+
+class ScreenMirrorOverWS:
+
+  def __init__(self, ws: WebSocket, max_size: int | None = None, device_serial: str | None = None):
+    self.ws = ws
+    self.scrcpy: ScrcpyPyClient | None = None
+    self._is_streaming = False
+    self._socket_read_task: asyncio.Task[None] | None = None
+    self.max_size = max_size
+    self.device_serial = device_serial
+
+  async def stream(self):
+    if self._is_streaming:
+      return
+    self._is_streaming = True
+    self.scrcpy = ScrcpyPyClient(on_frame_update=self.on_frame_update,
+                                 max_size=self.max_size,
+                                 device_serial=self.device_serial)
+    await self.scrcpy.push_server()
+    await self.scrcpy.forward_video_socket()
+    await self.scrcpy.start_server()
+    self._socket_read_task = asyncio.create_task(self.scrcpy.read_video_socket())
+    print("Started streaming screen over WebSocket.")
+    await self._socket_read_task  # Blocking call to keep streaming
+
+  async def on_frame_update(self, frame: bytes):
+    await self.ws.send_bytes(frame)
+
+  async def teardown(self):
+    self._is_streaming = False
+
+    if self.scrcpy:
+      print("[teardown]Stopping scrcpy client...")
+      try:
+        await self.scrcpy.stop()
+      finally:
+        self.scrcpy = None
+
+    if self._socket_read_task and not self._socket_read_task.done():
+      print("[teardown]Cancelling socket read task...")
+      try:
+        self._socket_read_task.cancel()
+      finally:
+        self._socket_read_task = None
+
+    print("[teardown]Teardown complete.")

pantoqa_bridge/server.py

@@ -0,0 +1,178 @@
+import os
+import shutil
+import subprocess
+from contextlib import asynccontextmanager
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from pantoqa_bridge.config import (APPIUM_SERVER_HOST, APPIUM_SERVER_PORT, PKG_NAME,
+                                   SCRCPY_SERVER_BIN, SERVER_HOST, SERVER_PORT)
+from pantoqa_bridge.logger import logger
+from pantoqa_bridge.routes.action import router as action_router
+from pantoqa_bridge.routes.adb import router as adb_router
+from pantoqa_bridge.routes.executor import route as executor_route
+from pantoqa_bridge.routes.misc import route as misc_route
+from pantoqa_bridge.routes.screen_mirror import route as screen_mirror_route
+from pantoqa_bridge.utils.misc import ensure_android_home, start_appium_process_sync
+from pantoqa_bridge.utils.pkg import get_latest_package_version, get_pkg_version, upgrade_package
+from pantoqa_bridge.utils.process import (kill_process_sync, kill_self_process,
+                                          wait_for_port_to_alive, watch_process_bg)
+
+
+def create_app() -> FastAPI:
+  logger.info("Checking required tools...")
+  _pre_check_required_tools()
+  appium_pid = start_appium_process_sync()
+
+  @asynccontextmanager
+  async def lifespan(app: FastAPI):
+    await wait_for_port_to_alive(APPIUM_SERVER_PORT, APPIUM_SERVER_HOST, timeout=15)
+
+    def on_exit(pid: int) -> None:
+      logger.info("Appium process exite. Shutting down PantoQA Bridge server...")
+      kill_self_process()
+
+    watch_process_bg(appium_pid, on_exit=on_exit)
+    yield
+    kill_process_sync(appium_pid, timeout=10)
+
+  app = FastAPI(
+    title="PantoAI QA Ext",
+    lifespan=lifespan,
+  )
+
+  # Allow *.getpanto.ai, *.pantomax.co and localhost origins
+  allow_origin_regex = r"(https://(([a-zA-Z0-9-]+\.)*pantomax\.co|([a-zA-Z0-9-]+\.)*getpanto\.ai)|http://localhost(:\d+)?)$"  # noqa: E501
+
+  app.add_middleware(
+    CORSMiddleware,
+    allow_origin_regex=allow_origin_regex,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+  )
+  app.include_router(misc_route)
+  app.include_router(executor_route)
+  app.include_router(action_router)
+  app.include_router(screen_mirror_route)
+  app.include_router(adb_router)
+  return app
+
+
+def start_bridge_server(host=SERVER_HOST, port=SERVER_PORT):
+  try:
+    app = create_app()
+    uvicorn.run(
+      app,
+      host=host,
+      port=port,
+    )
+  except DependencyNotInstalledError as e:
+    logger.error(e)
+  except Exception as e:
+    logger.error(f"Failed to start server: {e}")
+
+
+class DependencyNotInstalledError(Exception):
+  pass
+
+
+def _pre_check_required_tools():
+
+  def _current_package_check():
+    curent_pkg_version = get_pkg_version(PKG_NAME)
+    latest_pkg_version = get_latest_package_version(PKG_NAME)
+    if curent_pkg_version < latest_pkg_version:
+      logger.info(f"[Check] A new version of {PKG_NAME} is available: {latest_pkg_version} "
+                  f"(current: {curent_pkg_version}). Upgrading...")
+      upgrade_package(PKG_NAME)
+      logger.info(f"[Check] {PKG_NAME} upgraded successfully. Please restart.")
+      exit(1)
+    else:
+      logger.info(f"[Check] {PKG_NAME} is up-to-date: {curent_pkg_version}")
+
+  def _install_uiautomator2() -> None:
+    subprocess.check_output(
+      ["appium", "driver", "install", "uiautomator2"],
+      stderr=subprocess.STDOUT,
+      text=True,
+    )
+
+  def _install_appium() -> None:
+    subprocess.check_output(
+      ["npm", "install", "-g", "appium"],
+      stderr=subprocess.STDOUT,
+      text=True,
+    )
+
+  _current_package_check()
+
+  required_tools = [
+    ("node", "node --version", "Node.js", None),
+    ("npm", "npm --version", "npm", None),
+    ("appium", "appium --version", "Appium", _install_appium),
+  ]
+  for cmd, version_cmd, name, install_func in required_tools:
+    if shutil.which(cmd) is None:
+      if not install_func:
+        raise DependencyNotInstalledError(f"{name} is not installed or not found in PATH.")
+      logger.info(f"[Check] {name} is not installed. Installing...")
+      try:
+        install_func()
+        logger.info(f"[Check] {name} installed successfully.")
+      except subprocess.CalledProcessError as e:
+        raise DependencyNotInstalledError(f"Failed to install {name}: {e.output}") from e
+    else:
+      version_output = subprocess.check_output(version_cmd, shell=True, text=True).strip()
+      logger.info(f"[Check] {name} found: {version_output}")
+
+  # Check if uiautomator2 server is installed
+  uiautomator2_check = subprocess.check_output(
+    "appium driver list --installed --json",
+    shell=True,
+    text=True,
+  )
+  if "uiautomator2" in uiautomator2_check:
+    logger.info("[Check] Appium uiautomator2 driver is installed.")
+  else:
+    logger.info("[Check] Appium uiautomator2 driver is not installed. Installing...")
+    try:
+      _install_uiautomator2()
+      logger.info("[Check] Appium uiautomator2 driver installed successfully.")
+    except subprocess.CalledProcessError as e:
+      raise DependencyNotInstalledError(
+        f"Failed to install Appium uiautomator2 driver: {e.output}") from e
+
+  android_home, auto_detected = ensure_android_home()
+  if auto_detected and android_home:
+    os.environ["ANDROID_HOME"] = android_home
+  if android_home:
+    logger.info(
+      f"[Check] ANDROID_HOME: {android_home} {'(auto-detected)' if auto_detected else ''}")
+  else:
+    logger.warning("[Check] Android SDK not found. Please install Android SDK and set ANDROID_HOME"
+                   "environment variable.")
+
+  adb_android_home = os.path.join(android_home, "platform-tools", "adb") if android_home else None
+  if shutil.which("adb"):
+    logger.info(f"[Check] adb found in PATH: {shutil.which('adb')}")
+  elif adb_android_home and os.path.exists(adb_android_home):
+    logger.info(f"[Check] adb found at ANDROID_HOME: {adb_android_home}")
+    os.environ["PATH"] += os.pathsep + os.path.dirname(adb_android_home)
+  else:
+    raise DependencyNotInstalledError("Android SDK not found. "
+                                      "Please install Android SDK "
+                                      "and set ANDROID_HOME or ANDROID_SDK_ROOT "
+                                      "environment variable.")
+
+  if SCRCPY_SERVER_BIN and os.path.exists(SCRCPY_SERVER_BIN):
+    logger.info(f"[Check] scrcpy server binary found at: {SCRCPY_SERVER_BIN}")
+  else:
+    logger.warning(
+      "[Check] scrcpy server binary not found. Screen mirroring may not work properly.")
+
+
+if __name__ == '__main__':
+  start_bridge_server()

pantoqa_bridge/service/uiautomator_action.py

@@ -0,0 +1,102 @@
+import base64
+from io import BytesIO
+
+import uiautomator2 as u2  # type: ignore
+from adbutils import adb  # type: ignore
+
+
+class LocalBridgeService():
+
+  def __init__(self, device_serial: str | None = None):
+    self.uiautomator = u2.connect(device_serial)
+    self.adb = adb.device(device_serial)
+
+  def take_screenshot(self) -> str:
+    image = self.uiautomator.screenshot()
+    buf = BytesIO()
+    image.save(buf, format="PNG")
+    return base64.b64encode(buf.getvalue()).decode("utf-8")
+
+  def click(self, x: int, y: int):
+    self.uiautomator.click(x, y)
+
+  def long_click(self, x: int, y: int):
+    self.uiautomator.long_click(x, y)
+
+  def get_os_version(self) -> str:
+    return str(self.uiautomator.device_info["version"])
+
+  def get_device_model(self) -> str:
+    return self.uiautomator.device_info["model"]
+
+  def device_resolution(self) -> dict:
+    w, h = self.uiautomator.window_size()
+    return {"width": w, "height": h}
+
+  def get_ui_dump(self) -> str:
+    xml = self.uiautomator.dump_hierarchy()
+    return xml
+
+  def get_current_app_activity(self) -> str:
+    activity = self.uiautomator.app_current()
+    return activity['activity']
+
+  def get_main_activity(self, package_name: str) -> str | None:
+    result = self.adb.shell(f"cmd package resolve-activity --brief {package_name}")
+
+    for line in result.splitlines():
+      if line.startswith(package_name + "/"):
+        return line.replace(package_name + "/", "", 1)
+
+    return None
+
+  def get_all_packages(self) -> list[str]:
+    packages = self.uiautomator.app_list()
+    return packages
+
+  def open_app(self, package_name: str, activity_name: str = ".MainActivity"):
+    self.uiautomator.app_start(package_name=package_name)
+
+  def close_keyboard(self):
+    self.uiautomator.hide_keyboard()
+
+  def press_enter(self):
+    self.uiautomator.keyevent("66")
+
+  def go_back(self):
+    self.uiautomator.press("back")
+
+  def is_keyboard_open(self) -> bool:
+    result = self.adb.shell("dumpsys input_method")
+    return "mInputShown=true" in result
+
+  def goto_home(self):
+    self.uiautomator.press("home")
+
+  def clear_all_inputs(self):
+    self.uiautomator.clear_text()
+
+  def backspace(self):
+    self.uiautomator.keyevent("67")
+
+  def input_text(self, text: str):
+    self.uiautomator.send_keys(text)
+
+  def swipe(self, x1: int, y1: int, x2: int, y2: int):
+    self.uiautomator.swipe(x1, y1, x2, y2)
+
+  def long_press(self, x: int, y: int):
+    self.uiautomator.long_click(x, y)
+
+  def get_oem_name(self) -> str:
+    info = self.uiautomator.device_info
+    return info["brand"]
+
+  def get_device_name(self) -> str:
+
+    info = self.uiautomator.device_info
+    return info["model"]
+
+  def get_os_build_version(self) -> str:
+    info = self.uiautomator.device_info
+    return str(info["sdk"])

pantoqa_bridge/tasks/executor.py

@@ -0,0 +1,88 @@
+import abc
+import asyncio
+import importlib
+import importlib.util
+import sys
+import uuid
+from pathlib import Path
+
+from appium import webdriver
+from appium.options.android import UiAutomator2Options
+
+from pantoqa_bridge.config import APPIUM_SERVER_URL, MAESTRO_BIN
+from pantoqa_bridge.logger import logger
+
+
+class QAExecutable(abc.ABC):
+
+  def __init__(self, files: list[str]):
+    self.files = files
+
+  @abc.abstractmethod
+  async def execute(self):
+    ...
+
+
+class MaestroExecutable(QAExecutable):
+
+  def __init__(self, files: list[str], maestro_bin: str | None = None):
+    super().__init__(files)
+    self.maestro_bin = maestro_bin or MAESTRO_BIN
+
+  async def execute(self):
+    yml_files = [f for f in self.files if (f.endswith('.yml') or f.endswith('.yaml'))]
+    if not yml_files:
+      logger.error("No Maestro test files found.")
+      return
+    cmd = [self.maestro_bin, "test"] + yml_files
+    logger.debug(f"Maestro command: {' '.join(cmd)}")
+
+    logger.info(f"Running Maestro: {' '.join(cmd)}")
+    result = await asyncio.create_subprocess_exec(
+      *cmd,
+      stdout=asyncio.subprocess.PIPE,
+      stderr=asyncio.subprocess.STDOUT,
+    )
+
+    if not result.stdout:
+      logger.error("No output from Maestro process.")
+      return
+    async for line in result.stdout:
+      logger.info(f"> {line.decode().strip()}")
+    await result.wait()
+    logger.info(f"Maestro finished with return code: {result.returncode}")
+    return result.returncode
+
+
+class AppiumExecutable(QAExecutable):
+
+  def __init__(self, files: list[str], appium_url: str | None = None):
+    super().__init__(files)
+    options = UiAutomator2Options()
+    options.set_capability("platformName", "Android")
+    options.set_capability("automationName", "UiAutomator2")
+    options.set_capability("deviceName", "Android Device")
+    options.set_capability("noReset", True)
+    options.set_capability("fullReset", False)
+    self.default_wait_in_sec = 20
+    self.options = options
+    self.appium_url = appium_url or APPIUM_SERVER_URL
+
+  async def execute(self):
+    file = self.files[0]
+    filepath = Path(file).resolve()
+    module_name = f"_dynamic_{uuid.uuid4().hex}"
+    spec = importlib.util.spec_from_file_location(module_name, filepath)
+    assert spec, "Spec should not be None"
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)  # type: ignore
+
+    try:
+      with webdriver.Remote(self.appium_url, options=self.options) as driver:
+        driver.implicitly_wait(self.default_wait_in_sec)
+        output = module.main(driver)
+        return output
+    finally:
+      if module_name in sys.modules:
+        del sys.modules[module_name]
+      del module

pantoqa_bridge/utils/misc.py

@@ -0,0 +1,131 @@
+import asyncio
+import functools
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from pantoqa_bridge.config import APPIUM_SERVER_HOST, APPIUM_SERVER_PORT, IS_WINDOWS
+from pantoqa_bridge.logger import logger
+
+
+def find_android_home() -> str | None:
+  """
+  Find ANDROID_HOME path by checking:
+  1. adb location (SDK root is parent of platform-tools)
+  2. Common SDK installation paths
+  Returns the path as a string, or None if not found.
+  """
+
+  if os.environ.get("ANDROID_HOME"):
+    return os.environ["ANDROID_HOME"]
+
+  if os.environ.get("ANDROID_SDK_ROOT"):
+    return os.environ["ANDROID_SDK_ROOT"]
+
+  # Try to find SDK root from adb location
+  adb_path = shutil.which("adb")
+  if adb_path:
+    # adb is in <SDK>/platform-tools/adb, so SDK root is grandparent
+    sdk_root = Path(adb_path).resolve().parent.parent
+    if sdk_root.exists():
+      return str(sdk_root)
+
+  # Try common SDK locations
+  home = Path.home()
+  if IS_WINDOWS:
+    common_paths = [
+      Path(f"{home}/AppData/Local/Android/Sdk"),
+      Path("C:/Android/Sdk"),
+      Path("C:/Android/android-sdk"),
+    ]
+  else:  # Mac/Linux
+    common_paths = [
+      Path(f"{home}/Library/Android/sdk"),
+      Path(f"{home}/Android/Sdk"),
+      Path("/usr/local/android-sdk"),
+    ]
+
+  for sdk_path in common_paths:
+    if sdk_path.exists() and (sdk_path / "platform-tools").exists():
+      return str(sdk_path)
+
+  return None
+
+
+def ensure_android_home() -> tuple[str | None, bool]:
+  """
+  Ensure ANDROID_HOME is set in environment variables.
+  If not set, attempt to auto-detect and set it.
+
+  :return: A tuple containing the ANDROID_HOME path (or None if not found)
+  and a boolean indicating if it was auto-detected and set.
+  :rtype: tuple[str | None, bool]
+  """
+  if os.environ.get("ANDROID_HOME"):
+    return os.environ.get("ANDROID_HOME"), False
+
+  if os.environ.get("ANDROID_SDK_ROOT"):
+    return os.environ.get("ANDROID_SDK_ROOT"), False
+
+  android_home = find_android_home()
+  if not android_home:
+    return None, False
+
+  return android_home, True
+
+
+def _get_appium_cmd() -> str:
+  """Get the appium command path based on the platform."""
+  appium_path = shutil.which("appium")
+  if not appium_path:
+    raise RuntimeError("Appium not found in PATH")
+  return appium_path
+
+
+async def start_appium_process() -> int:
+  cmd = [
+    _get_appium_cmd(),
+    "--port",
+    str(APPIUM_SERVER_PORT),
+    "--address",
+    APPIUM_SERVER_HOST,
+  ]
+  logger.info(f"Starting Appium at http://{APPIUM_SERVER_HOST}:{APPIUM_SERVER_PORT}")
+  result = await asyncio.create_subprocess_exec(
+    *cmd,
+    stdout=asyncio.subprocess.DEVNULL,
+    stderr=asyncio.subprocess.DEVNULL,
+    env=os.environ.copy(),
+  )
+  logger.info(f"Running appium at pid {result.pid}...")
+  return result.pid
+
+
+def start_appium_process_sync() -> int:
+  """Start Appium process synchronously. Works on both Windows and Mac."""
+  cmd = [_get_appium_cmd(), "--port", str(APPIUM_SERVER_PORT), "--address", APPIUM_SERVER_HOST]
+  logger.info(f"Starting Appium at http://{APPIUM_SERVER_HOST}:{APPIUM_SERVER_PORT}")
+
+  # On Windows, we need to avoid PIPE for long-running processes since
+  # unconsumed pipe buffers can cause the process to hang.
+  # Explicitly pass the environment to ensure ANDROID_HOME is inherited.
+  process = subprocess.Popen(
+    cmd,
+    stdout=subprocess.DEVNULL,
+    stderr=subprocess.DEVNULL,
+    start_new_session=True,
+    shell=False,
+    env=os.environ.copy(),
+  )
+  logger.info(f"Running Appium at pid {process.pid}...")
+  return process.pid
+
+
+def make_sync(func):
+
+  @functools.wraps(func)
+  def wrapper(*args, **kwargs):
+    return asyncio.run(func(*args, **kwargs))
+
+  return wrapper

pantoqa_bridge/utils/pkg.py

@@ -0,0 +1,45 @@
+import shutil
+import subprocess
+import sys
+from importlib.metadata import version as importlib_version
+
+from packaging import version as pkg_version
+
+from pantoqa_bridge.logger import logger
+
+
+def get_pkg_version(pkg_name: str) -> pkg_version.Version:
+  return pkg_version.parse(importlib_version(pkg_name))
+
+
+def get_latest_package_version(package_name: str) -> pkg_version.Version:
+  result = subprocess.check_output(
+    [sys.executable, "-m", "pip", "index", "versions", package_name],
+    stderr=subprocess.STDOUT,
+    text=True,
+  )
+
+  if "Available versions:" not in result:
+    raise ValueError(f"Could not fetch versions for package {package_name}")
+
+  versions_str = result.split("Available versions:")[1].strip()
+  latest_version = versions_str.split(",")[0].strip()
+  return pkg_version.parse(latest_version)
+
+
+def upgrade_package(package_name: str) -> None:
+  logger.info(f"Upgrading package {package_name}...")
+  if shutil.which("pipx"):
+    subprocess.check_output(
+      ["pipx", "upgrade", package_name],
+      stderr=subprocess.STDOUT,
+      text=True,
+    )
+  else:
+    subprocess.check_output(
+      [sys.executable, "-m", "pipx", "upgrade", package_name],
+      stderr=subprocess.STDOUT,
+      text=True,
+    )
+
+  logger.info(f"Package {package_name} upgraded successfully.")