@qubiqlabs/mobiflow 0.9.0 → 1.0.0

package/src/mobiflow/cloud/__init__.py

@@ -0,0 +1,28 @@
+"""Cloud device labs: BrowserStack App Automate + TestMu (HyperExecute) for Maestro."""
+
+from __future__ import annotations
+
+from mobiflow.cloud.base import (
+    CloudCredentials,
+    CloudProvider,
+    CloudRunRequest,
+    CloudRunResult,
+    is_cloud_provider,
+    normalize_provider,
+    resolve_credentials,
+    zip_maestro_suite,
+)
+from mobiflow.cloud.runner import cloud_readiness, run_on_cloud
+
+__all__ = [
+    "CloudCredentials",
+    "CloudProvider",
+    "CloudRunRequest",
+    "CloudRunResult",
+    "cloud_readiness",
+    "is_cloud_provider",
+    "normalize_provider",
+    "resolve_credentials",
+    "run_on_cloud",
+    "zip_maestro_suite",
+]

package/src/mobiflow/cloud/base.py

@@ -0,0 +1,272 @@
+"""Shared types and helpers for cloud Maestro runners."""
+
+from __future__ import annotations
+
+import io
+import os
+import zipfile
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class CloudProvider(str, Enum):
+    LOCAL = "local"
+    BROWSERSTACK = "browserstack"
+    TESTMU = "testmu"
+    MAESTRO = "maestro"
+
+
+_PROVIDER_ALIASES = {
+    "local": CloudProvider.LOCAL,
+    "none": CloudProvider.LOCAL,
+    "": CloudProvider.LOCAL,
+    "browserstack": CloudProvider.BROWSERSTACK,
+    "bs": CloudProvider.BROWSERSTACK,
+    "bstack": CloudProvider.BROWSERSTACK,
+    "testmu": CloudProvider.TESTMU,
+    "testmuai": CloudProvider.TESTMU,
+    "testmu-ai": CloudProvider.TESTMU,
+    "lambdatest": CloudProvider.TESTMU,
+    "lt": CloudProvider.TESTMU,
+    "maestro": CloudProvider.MAESTRO,
+    "maestro-cloud": CloudProvider.MAESTRO,
+    "maestro_cloud": CloudProvider.MAESTRO,
+    "maestrocloud": CloudProvider.MAESTRO,
+}
+
+
+def normalize_provider(value: str | None) -> CloudProvider:
+    key = (value or "local").strip().lower().replace("_", "-")
+    if key not in _PROVIDER_ALIASES:
+        raise ValueError(
+            f"Unknown device.provider {value!r}. "
+            "Use: local | browserstack | testmu | maestro"
+        )
+    return _PROVIDER_ALIASES[key]
+
+
+def is_cloud_provider(value: str | CloudProvider | None) -> bool:
+    if isinstance(value, CloudProvider):
+        return value in (
+            CloudProvider.BROWSERSTACK,
+            CloudProvider.TESTMU,
+            CloudProvider.MAESTRO,
+        )
+    try:
+        return normalize_provider(value) in (
+            CloudProvider.BROWSERSTACK,
+            CloudProvider.TESTMU,
+            CloudProvider.MAESTRO,
+        )
+    except ValueError:
+        return False
+
+
+@dataclass
+class CloudCredentials:
+    username: str
+    access_key: str
+    username_env: str
+    access_key_env: str
+
+
+def default_credential_env_names(provider: CloudProvider) -> tuple[str, str]:
+    if provider == CloudProvider.BROWSERSTACK:
+        return "BROWSERSTACK_USERNAME", "BROWSERSTACK_ACCESS_KEY"
+    if provider == CloudProvider.TESTMU:
+        # Prefer TestMu names; fall back to legacy LambdaTest names at resolve time.
+        return "TESTMU_USERNAME", "TESTMU_ACCESS_KEY"
+    if provider == CloudProvider.MAESTRO:
+        # Maestro Cloud uses a single API key (stored in access_key slot).
+        return "MAESTRO_CLOUD_API_KEY", "MAESTRO_CLOUD_API_KEY"
+    return "", ""
+
+
+def resolve_credentials(
+    provider: CloudProvider,
+    *,
+    username_env: str = "",
+    access_key_env: str = "",
+) -> CloudCredentials:
+    user_env, key_env = default_credential_env_names(provider)
+    if (username_env or "").strip():
+        user_env = username_env.strip()
+    if (access_key_env or "").strip():
+        key_env = access_key_env.strip()
+
+    username = os.environ.get(user_env, "").strip()
+    access_key = os.environ.get(key_env, "").strip()
+
+    # Maestro Cloud: single API key (also accept MAESTRO_API_KEY)
+    if provider == CloudProvider.MAESTRO:
+        for alt in ("MAESTRO_CLOUD_API_KEY", "MAESTRO_API_KEY", "MAESTRO_CLOUD_KEY"):
+            val = os.environ.get(alt, "").strip()
+            if val:
+                return CloudCredentials(
+                    username=val,
+                    access_key=val,
+                    username_env=alt,
+                    access_key_env=alt,
+                )
+        raise ValueError(
+            "Cloud credentials missing for maestro. "
+            "Export $MAESTRO_CLOUD_API_KEY (or $MAESTRO_API_KEY)."
+        )
+
+    # TestMu rebrand: also accept LT_* when TESTMU_* unset
+    if provider == CloudProvider.TESTMU:
+        if not username:
+            for alt in ("LT_USERNAME", "LAMBDATEST_USERNAME"):
+                username = os.environ.get(alt, "").strip()
+                if username:
+                    user_env = alt
+                    break
+        if not access_key:
+            for alt in ("LT_ACCESS_KEY", "LAMBDATEST_ACCESS_KEY"):
+                access_key = os.environ.get(alt, "").strip()
+                if access_key:
+                    key_env = alt
+                    break
+
+    if not username or not access_key:
+        raise ValueError(
+            f"Cloud credentials missing for {provider.value}. "
+            f"Export ${user_env} and ${key_env}"
+            + (
+                " (or LT_USERNAME / LT_ACCESS_KEY)."
+                if provider == CloudProvider.TESTMU
+                else "."
+            )
+        )
+    return CloudCredentials(
+        username=username,
+        access_key=access_key,
+        username_env=user_env,
+        access_key_env=key_env,
+    )
+
+
+@dataclass
+class CloudRunRequest:
+    provider: CloudProvider
+    platform: str  # android | ios
+    flow_yaml: str
+    scripts: dict[str, str] = field(default_factory=dict)
+    devices: list[str] = field(default_factory=list)
+    app_path: str = ""
+    app_url: str = ""  # bs://… or lt://…
+    project: str = "MobiFlow"
+    build_name: str = ""
+    real_mobile: bool = True
+    username_env: str = ""
+    access_key_env: str = ""
+    timeout_s: int = 1800
+    poll_interval_s: float = 15.0
+    local: bool = False  # BrowserStack local testing flag
+    flow_name: str = "flow.yaml"
+
+
+@dataclass
+class CloudRunResult:
+    ok: bool
+    provider: str
+    build_id: str = ""
+    status: str = ""
+    dashboard_url: str = ""
+    app_url: str = ""
+    test_suite_url: str = ""
+    stdout: str = ""
+    stderr: str = ""
+    error: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+    media_urls: list[dict[str, str]] = field(default_factory=list)
+    media_files: list[str] = field(default_factory=list)
+    media_dir: str = ""
+    video_url: str = ""
+
+    def as_run_dict(self) -> dict[str, Any]:
+        video = self.video_url
+        if not video:
+            for item in self.media_urls:
+                if item.get("kind") == "video" and item.get("url"):
+                    video = item["url"]
+                    break
+        return {
+            "ok": self.ok,
+            "returncode": 0 if self.ok else 1,
+            "stdout": self.stdout,
+            "stderr": self.stderr or (self.error or ""),
+            "error": None if self.ok else (self.error or "cloud_run_failed"),
+            "provider": self.provider,
+            "build_id": self.build_id,
+            "status": self.status,
+            "dashboard_url": self.dashboard_url,
+            "app_url": self.app_url,
+            "test_suite_url": self.test_suite_url,
+            "raw": self.raw,
+            "media_urls": self.media_urls,
+            "media_files": self.media_files,
+            "media_dir": self.media_dir,
+            "video_url": video,
+        }
+
+
+def zip_maestro_suite(
+    flow_yaml: str,
+    scripts: dict[str, str] | None = None,
+    *,
+    flow_name: str = "flow.yaml",
+    folder_name: str = "tests",
+) -> bytes:
+    """Zip Maestro flows for BrowserStack (parent folder required)."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr(f"{folder_name}/{flow_name}", flow_yaml)
+        for rel, body in (scripts or {}).items():
+            # Keep scripts under the same parent folder
+            clean = rel.replace("\\", "/").lstrip("/")
+            zf.writestr(f"{folder_name}/{clean}", body)
+    return buf.getvalue()
+
+
+def write_suite_dir(
+    root: Path,
+    flow_yaml: str,
+    scripts: dict[str, str] | None = None,
+    *,
+    flow_name: str = "flow.yaml",
+) -> Path:
+    """Write flow + scripts under root; return path to the flow file."""
+    root.mkdir(parents=True, exist_ok=True)
+    flow_path = root / flow_name
+    flow_path.write_text(flow_yaml, encoding="utf-8")
+    for rel, body in (scripts or {}).items():
+        sp = root / rel
+        sp.parent.mkdir(parents=True, exist_ok=True)
+        sp.write_text(body, encoding="utf-8")
+    return flow_path
+
+
+def devices_from_config(
+    device_id: str | None,
+    *,
+    platform: str,
+    provider: CloudProvider,
+) -> list[str]:
+    """Resolve cloud device list from device_id (comma-separated OK)."""
+    raw = (device_id or "").strip()
+    if raw:
+        parts = [p.strip() for p in raw.split(",") if p.strip()]
+        if parts:
+            return parts
+    # Sensible defaults for smoke / first-run
+    if provider == CloudProvider.BROWSERSTACK:
+        if (platform or "").lower() == "ios":
+            return ["iPhone 15-17.0"]
+        return ["Google Pixel 7-13.0"]
+    # TestMu HyperExecute device strings
+    if (platform or "").lower() == "ios":
+        return ["iPhone 15"]
+    return ["Pixel 6-14"]

package/src/mobiflow/cloud/browserstack.py

@@ -0,0 +1,330 @@
+"""BrowserStack App Automate Maestro REST client."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from mobiflow.cloud.base import (
+    CloudCredentials,
+    CloudRunRequest,
+    CloudRunResult,
+    resolve_credentials,
+    zip_maestro_suite,
+)
+
+logger = logging.getLogger(__name__)
+
+ProgressFn = Callable[[str], None] | None
+
+API_BASE = "https://api-cloud.browserstack.com/app-automate"
+UPLOAD_APP = f"{API_BASE}/upload"
+UPLOAD_SUITE = f"{API_BASE}/maestro/v2/test-suite"
+BUILD_ANDROID = f"{API_BASE}/maestro/v2/android/build"
+BUILD_IOS = f"{API_BASE}/maestro/v2/ios/build"
+BUILD_STATUS = f"{API_BASE}/maestro/v2/builds/{{build_id}}"
+
+_TERMINAL_OK = {"passed", "completed", "success"}
+_TERMINAL_FAIL = {
+    "failed",
+    "error",
+    "timeout",
+    "timedout",
+    "skipped",
+    "stopped",
+    "cancelled",
+    "canceled",
+}
+
+
+def _auth(creds: CloudCredentials) -> tuple[str, str]:
+    return (creds.username, creds.access_key)
+
+
+def _dashboard_url(build_id: str) -> str:
+    return f"https://app-automate.browserstack.com/dashboard/v2/builds/{build_id}"
+
+
+async def upload_app(
+    client: httpx.AsyncClient,
+    creds: CloudCredentials,
+    app_path: Path,
+    *,
+    custom_id: str = "mobiflow-app",
+) -> str:
+    if not app_path.is_file():
+        raise FileNotFoundError(f"App not found: {app_path}")
+    data = {"custom_id": custom_id}
+    files = {"file": (app_path.name, app_path.read_bytes())}
+    resp = await client.post(
+        UPLOAD_APP, auth=_auth(creds), data=data, files=files, timeout=600.0
+    )
+    resp.raise_for_status()
+    payload = resp.json()
+    url = payload.get("app_url") or payload.get("appUrl")
+    if not url:
+        raise RuntimeError(f"BrowserStack app upload missing app_url: {payload}")
+    return str(url)
+
+
+async def upload_test_suite(
+    client: httpx.AsyncClient,
+    creds: CloudCredentials,
+    zip_bytes: bytes,
+    *,
+    custom_id: str = "mobiflow-suite",
+) -> str:
+    files = {"file": ("maestro_tests.zip", zip_bytes, "application/zip")}
+    data = {"custom_id": custom_id}
+    resp = await client.post(
+        UPLOAD_SUITE, auth=_auth(creds), data=data, files=files, timeout=300.0
+    )
+    resp.raise_for_status()
+    payload = resp.json()
+    url = (
+        payload.get("test_suite_url")
+        or payload.get("testSuiteUrl")
+        or payload.get("test_url")
+    )
+    if not url:
+        raise RuntimeError(f"BrowserStack suite upload missing test_suite_url: {payload}")
+    return str(url)
+
+
+async def start_build(
+    client: httpx.AsyncClient,
+    creds: CloudCredentials,
+    *,
+    platform: str,
+    app_url: str,
+    test_suite_url: str,
+    devices: list[str],
+    project: str,
+    execute: list[str],
+    build_name: str = "",
+    local: bool = False,
+) -> str:
+    plat = (platform or "android").lower()
+    endpoint = BUILD_IOS if plat == "ios" else BUILD_ANDROID
+    body: dict[str, Any] = {
+        "app": app_url,
+        "testSuite": test_suite_url,
+        "devices": devices,
+        "project": project or "MobiFlow",
+        "execute": execute,
+        "deviceLogs": True,
+        "debugscreenshots": True,
+    }
+    if build_name:
+        body["customBuildName"] = build_name
+    if local:
+        body["local"] = "true"
+    resp = await client.post(
+        endpoint,
+        auth=_auth(creds),
+        headers={"Content-Type": "application/json"},
+        content=json.dumps(body),
+        timeout=120.0,
+    )
+    resp.raise_for_status()
+    payload = resp.json()
+    build_id = payload.get("build_id") or payload.get("buildId") or payload.get("id")
+    if not build_id:
+        raise RuntimeError(f"BrowserStack build start missing build_id: {payload}")
+    return str(build_id)
+
+
+async def get_build_status(
+    client: httpx.AsyncClient,
+    creds: CloudCredentials,
+    build_id: str,
+) -> dict[str, Any]:
+    resp = await client.get(
+        BUILD_STATUS.format(build_id=build_id),
+        auth=_auth(creds),
+        timeout=60.0,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+def _status_is_terminal(status: str) -> bool:
+    s = (status or "").strip().lower()
+    return s in _TERMINAL_OK or s in _TERMINAL_FAIL or s in {"done", "finished"}
+
+
+def _status_ok(status: str) -> bool:
+    return (status or "").strip().lower() in _TERMINAL_OK | {"done", "finished"}
+
+
+async def poll_build(
+    client: httpx.AsyncClient,
+    creds: CloudCredentials,
+    build_id: str,
+    *,
+    timeout_s: float,
+    poll_interval_s: float,
+    progress: ProgressFn = None,
+) -> dict[str, Any]:
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout_s
+    last: dict[str, Any] = {}
+    while True:
+        last = await get_build_status(client, creds, build_id)
+        status = str(last.get("status") or "")
+        if progress:
+            progress(f"BrowserStack build {build_id[:12]}… status={status}")
+        if _status_is_terminal(status):
+            return last
+        if loop.time() >= deadline:
+            last["_mobiflow_error"] = "timeout"
+            return last
+        await asyncio.sleep(max(2.0, poll_interval_s))
+
+
+async def run_browserstack(
+    request: CloudRunRequest,
+    *,
+    progress: ProgressFn = None,
+    artifact_dir: Path | None = None,
+) -> CloudRunResult:
+    creds = resolve_credentials(
+        request.provider,
+        username_env=request.username_env,
+        access_key_env=request.access_key_env,
+    )
+    devices = list(request.devices)
+    if not devices:
+        return CloudRunResult(
+            ok=False,
+            provider="browserstack",
+            error="no_devices",
+            stderr="device.device_id (cloud device name) is required for BrowserStack",
+        )
+
+    app_url = (request.app_url or "").strip()
+    flow_name = request.flow_name or "flow.yaml"
+
+    async with httpx.AsyncClient() as client:
+        if not app_url:
+            if not request.app_path:
+                return CloudRunResult(
+                    ok=False,
+                    provider="browserstack",
+                    error="app_missing",
+                    stderr=(
+                        "Set device.app_path (.apk/.ipa) or device.app_url (bs://…) "
+                        "for BrowserStack."
+                    ),
+                )
+            if progress:
+                progress(f"Uploading app to BrowserStack: {request.app_path}")
+            app_url = await upload_app(client, creds, Path(request.app_path))
+            if progress:
+                progress(f"App uploaded → {app_url}")
+
+        if progress:
+            progress("Uploading Maestro test suite to BrowserStack…")
+        zip_bytes = zip_maestro_suite(
+            request.flow_yaml,
+            request.scripts,
+            flow_name=flow_name,
+        )
+        suite_url = await upload_test_suite(client, creds, zip_bytes)
+        if progress:
+            progress(f"Test suite uploaded → {suite_url}")
+
+        if progress:
+            progress(f"Starting BrowserStack Maestro build on {devices}…")
+        build_id = await start_build(
+            client,
+            creds,
+            platform=request.platform,
+            app_url=app_url,
+            test_suite_url=suite_url,
+            devices=devices,
+            project=request.project,
+            execute=[flow_name],
+            build_name=request.build_name,
+            local=request.local,
+        )
+        dash = _dashboard_url(build_id)
+        if progress:
+            progress(f"Build started id={build_id} · {dash}")
+
+        final = await poll_build(
+            client,
+            creds,
+            build_id,
+            timeout_s=float(request.timeout_s),
+            poll_interval_s=request.poll_interval_s,
+            progress=progress,
+        )
+
+    status = str(final.get("status") or "")
+    ok = _status_ok(status) and not final.get("_mobiflow_error")
+    err = None
+    if final.get("_mobiflow_error") == "timeout":
+        err = "timeout"
+        ok = False
+    elif not ok:
+        err = f"build_{status or 'failed'}"
+
+    summary = json.dumps(
+        {
+            "build_id": build_id,
+            "status": status,
+            "devices": final.get("devices"),
+            "dashboard": dash,
+        },
+        indent=2,
+    )
+    media_urls: list[dict[str, str]] = []
+    media_files: list[str] = []
+    media_dir = ""
+    video_url = ""
+    if artifact_dir is not None and build_id:
+        try:
+            from mobiflow.cloud.media import pull_browserstack_media
+
+            media_dest = Path(artifact_dir) / "cloud"
+            media_index = await pull_browserstack_media(
+                creds,
+                build_id,
+                final,
+                media_dest,
+                progress=progress,
+            )
+            media_urls = list(media_index.get("urls") or [])
+            media_files = list(media_index.get("files") or [])
+            media_dir = str(media_dest)
+            for item in media_urls:
+                if item.get("kind") == "video":
+                    video_url = item.get("url") or ""
+                    break
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("BrowserStack media pull failed: %s", exc)
+
+    return CloudRunResult(
+        ok=ok,
+        provider="browserstack",
+        build_id=build_id,
+        status=status,
+        dashboard_url=dash,
+        app_url=app_url,
+        test_suite_url=suite_url,
+        stdout=summary,
+        stderr="" if ok else summary,
+        error=err,
+        raw=final,
+        media_urls=media_urls,
+        media_files=media_files,
+        media_dir=media_dir,
+        video_url=video_url,
+    )