mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/testkit/github_checks.py

@@ -0,0 +1,248 @@
+"""Mobster Checks: `mobster test pr`'s verdict as a GitHub check run. A post never changes the verdict or exit code."""
+
+import json
+import os
+import re
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+
+from . import pr_report
+from .pr import run_git
+
+MODES = ("check", "comment", "off")
+GITHUB_MODES_ERROR = "--github is check, comment or off"
+NAME = "Mobster"
+LABEL = "Mobster Checks"
+API = "https://api.github.com"
+TOKEN_ROUTE = "/api/connectors/github-checks/token"
+REPO = re.compile(r"[A-Za-z0-9-]{1,39}/[A-Za-z0-9._-]{1,100}")
+SHA = re.compile(r"[0-9a-f]{40}")
+REMOTE = re.compile(r"(?:git@github\.com:|ssh://git@github\.com/|https://(?:[^@/\s]+@)?github\.com/)"
+                    r"([A-Za-z0-9-]{1,39}/[A-Za-z0-9._-]{1,100}?)(?:\.git)?/?")
+EARLY_S = 60          # a token this close to its expiry is asked for again
+TIMEOUT_S = 20
+SUMMARY_LIMIT = 65_000  # GitHub refuses a check run's summary over 65,535 characters
+
+
+class Refused(Exception):
+    """Mobster couldn't get a token for the repository: the sentence says why and what to do."""
+
+
+def ask_mobster(repo):
+    """{token, expiresAt, repo} from the running Mobster (connectors/github_app.py). Refused when it gives none."""
+    from ..threads.client import Client, NoService, ServiceError
+    try:
+        return Client.connect(origin="cli").call("POST", TOKEN_ROUTE, {"repo": repo}, timeout=30)
+    except NoService:
+        raise Refused("Open Mobster, so it can post the verdict on GitHub. Then run the checks again.") from None
+    except ServiceError as error:
+        install = error.data.get("installUrl")
+        raise Refused(f"{error} {install}" if isinstance(install, str) else str(error)) from None
+
+
+def repository(root, environ, git=run_git):
+    """owner/name on github.com: GITHUB_REPOSITORY in a GitHub Actions job, else the ``origin`` remote's."""
+    if environ.get("GITHUB_ACTIONS") == "true":
+        repo = environ.get("GITHUB_REPOSITORY", "")
+        return repo if REPO.fullmatch(repo) else None
+    code, url = git(["remote", "get-url", "origin"], root)
+    match = REMOTE.fullmatch(url.strip()) if code == 0 else None
+    return match.group(1) if match else None
+
+
+def pull_request(environ):
+    """(head commit, number) of the pull request a GitHub Actions job runs for, else (None, None)."""
+    if environ.get("GITHUB_ACTIONS") != "true":
+        return None, None
+    try:
+        with open(environ.get("GITHUB_EVENT_PATH", ""), encoding="utf-8") as handle:
+            event = json.load(handle)
+    except (OSError, ValueError):
+        return None, None
+    pull = event.get("pull_request") if isinstance(event, dict) else None
+    if not isinstance(pull, dict):
+        return None, None
+    sha = (pull.get("head") or {}).get("sha") if isinstance(pull.get("head"), dict) else None
+    number = pull.get("number")
+    return (sha if isinstance(sha, str) and SHA.fullmatch(sha) else None,
+            number if isinstance(number, int) else None)
+
+
+def conclusion(result):
+    """success, failure, or neutral when no check covered the PR: mobster test's exit code decides."""
+    if result.exit_code:
+        return "failure"
+    counts = result.pr.get("counts") or {}
+    ran = any(counts.get(key) for key in ("passed", "failed", "needs_review", "couldnt_run"))
+    return "success" if ran else "neutral"
+
+
+def output(pr, artifact_url=None):
+    title = str(pr.get("headline") or "Mobster checks").removeprefix("Mobster checks: ")
+    summary = pr_report.comment(pr, artifact_url=artifact_url).replace(pr_report.MARKER + "\n", "", 1)
+    return {"title": title[:200], "summary": summary[:SUMMARY_LIMIT]}
+
+
+def _seconds(text):
+    try:
+        return datetime.strptime(str(text), "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc).timestamp()
+    except ValueError:
+        return None
+
+
+class Poster:
+    def __init__(self, root, mode="check", progress=None, *, environ=None, git=run_git, mint=ask_mobster,
+                 opener=None, clock=time.time):
+        self.root, self.mode = root, mode if mode in MODES else "check"
+        self.progress = progress or (lambda line: None)
+        self.environ = os.environ if environ is None else environ
+        self.git, self.mint, self.opener, self.clock = git, mint, opener or urllib.request.urlopen, clock
+        self.state = "off" if self.mode == "off" else "ready"   # ready, started, done or off
+        self.repo = self.sha = self.number = self.check_id = None
+        self._token, self._expires = None, 0.0
+
+    @property
+    def actions(self):
+        return self.environ.get("GITHUB_ACTIONS") == "true"
+
+    def say(self, text):
+        self.progress(f"{LABEL}: {text}")
+
+
+    # The installation token stays in memory, asked for again before it expires; nothing here logs or prints it.
+    def _bearer(self):
+        """The token, asked for again when there's none or it's within EARLY_S of expiring. Refused."""
+        if self._token is not None and self.clock() < self._expires - EARLY_S:
+            return self._token
+        self._token = None
+        answer = self.mint(self.repo)
+        answer = answer if isinstance(answer, dict) else {}
+        token, expires, repo = answer.get("token"), _seconds(answer.get("expiresAt")), answer.get("repo")
+        if not isinstance(token, str) or not token or expires is None or self.clock() >= expires - EARLY_S:
+            raise Refused("Mobster's server gave no usable token. Run the checks again.")
+        if isinstance(repo, str) and REPO.fullmatch(repo):
+            self.repo = repo   # GitHub's own spelling, after a rename
+        self._token, self._expires = token, expires
+        return token
+
+    def _github(self, method, path, body=None):
+        token = self._bearer()
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json",
+                   "X-GitHub-Api-Version": "2022-11-28", "User-Agent": "mobster-checks"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        request = urllib.request.Request(f"{API}{path}", data=data, method=method, headers=headers)
+        try:
+            with self.opener(request, timeout=TIMEOUT_S) as response:
+                text = response.read().decode("utf-8")
+        finally:
+            token = headers = request = None  # noqa: F841 -- the token's other references go with this frame
+        return json.loads(text) if text else None
+
+    def _now(self):
+        return datetime.fromtimestamp(self.clock(), timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    def _failed(self, error, doing):
+        """One line for a request that failed: what GitHub or Mobster said, and what to do."""
+        if isinstance(error, Refused):
+            return self.say(f"nothing posted. {error}")
+        if isinstance(error, urllib.error.HTTPError):
+            if error.code == 422 and doing == "start":
+                return self.say(f"nothing posted: GitHub doesn't have {self.sha[:7]} yet. Push it, then run the "
+                                "checks again.")
+            return self.say(f"GitHub refused ({error.code}) when Mobster {doing_words(doing)}. Run the checks again.")
+        return self.say(f"GitHub didn't answer when Mobster {doing_words(doing)}, so Mobster didn't send it again. "
+                        "Run the checks again.")
+
+    def start(self, changes):
+        """The check run "Mobster", in progress on the commit the checks test."""
+        if self.state != "ready":
+            return
+        self.state = "done"
+        repo = repository(self.root, self.environ, self.git)
+        if repo is None:
+            return
+        head, self.number = pull_request(self.environ)
+        sha = head or getattr(changes, "head", None)
+        if not isinstance(sha, str) or not SHA.fullmatch(sha):
+            return
+        self.repo, self.sha = repo, sha
+        if getattr(changes, "uncommitted", False) and head is None:
+            return self.say(f"nothing posted: these checks run on uncommitted changes, so their verdict isn't "
+                            f"{sha[:7]}'s. Commit and push, then run them again.")
+        try:
+            self._bearer()
+            run = self._github("POST", f"/repos/{self.repo}/check-runs", {
+                "name": NAME, "head_sha": sha, "status": "in_progress", "started_at": self._now(),
+                "output": {"title": "Testing the screens this PR changed",
+                           "summary": "Mobster is building the app and running the checks that cover them."}})
+        except (Refused, urllib.error.URLError, OSError, ValueError) as error:
+            return self._failed(error, "start")
+        if not isinstance(run, dict) or not isinstance(run.get("id"), int):
+            return self.say("nothing posted: GitHub answered without a check run.")
+        self.check_id, self.state = run["id"], "started"
+        self.say(f"in progress on {self.repo} at {sha[:7]}")
+
+    def finish(self, result):
+        """The check run completed with the verdict; with ``comment`` (outside GitHub Actions), the one comment."""
+        if self.state != "started":
+            return
+        self.state = "done"
+        artifact_url = details = None
+        if self.actions:
+            from ..devkit.ci import links
+            artifact_url, _ = links("github", self.environ)
+            details = artifact_url
+        verdict = output(result.pr, artifact_url)
+        body = {"status": "completed", "conclusion": conclusion(result), "completed_at": self._now(),
+                "output": verdict, **({"details_url": details} if details else {})}
+        try:
+            self._github("PATCH", f"/repos/{self.repo}/check-runs/{self.check_id}", body)
+        except (Refused, urllib.error.URLError, OSError, ValueError) as error:
+            return self._failed(error, "finish")
+        line = f"posted “{verdict['title']}” on {self.repo} at {self.sha[:7]}"
+        if self.mode == "comment" and not self.actions:
+            line += self._comment(result.pr)
+        self.say(line)
+
+    def abandon(self):
+        """The run stopped before a verdict (an error, ctrl+c): the check run says so instead of staying in progress."""
+        if self.state != "started":
+            return
+        self.state = "done"
+        try:
+            self._github("PATCH", f"/repos/{self.repo}/check-runs/{self.check_id}", {
+                "status": "completed", "conclusion": "cancelled", "completed_at": self._now(),
+                "output": {"title": "Stopped", "summary": "The checks stopped before a verdict. Run them again."}})
+        except (Refused, urllib.error.URLError, OSError, ValueError) as error:
+            self._failed(error, "abandon")
+
+    def _comment(self, pr):
+        try:
+            number = self.number or self._open_pull()
+            if number is None:
+                return f"; no open pull request has {self.sha[:7]} as its head, so there's no comment"
+            from ..devkit.ci import GitHub
+            how, _ = GitHub(self._bearer(), self.repo, API, self.opener).sticky(number, pr_report.comment(pr))
+        except Refused as error:
+            return f"; no comment: {error}"
+        except urllib.error.HTTPError as error:
+            return f"; GitHub answered {error.code} to the comment"
+        except (urllib.error.URLError, OSError, ValueError):
+            return "; GitHub didn't answer about the comment, so Mobster didn't send it again"
+        return f", and {how} the comment on #{number}"
+
+    def _open_pull(self):
+        pulls = self._github("GET", f"/repos/{self.repo}/commits/{self.sha}/pulls") or []
+        for pull in pulls if isinstance(pulls, list) else ():
+            if pull.get("state") == "open" and (pull.get("head") or {}).get("sha") == self.sha:
+                return pull.get("number") if isinstance(pull.get("number"), int) else None
+        return None
+
+
+def doing_words(doing):
+    return {"start": "started the check run", "finish": "posted the verdict",
+            "abandon": "marked the check run stopped"}.get(doing, "posted")

mobile_agent/testkit/gitref.py

@@ -0,0 +1,66 @@
+"""The branch and commit a suite tested: `git {branch, head}` in results.json, JUnit's properties and the Mac app's
+runs by branch.
+
+    checkout(root)        # {"branch": "onboarding-v2", "head": "217873d1…"}, or None outside a git checkout
+
+A CI checkout is usually a detached HEAD; its branch then comes from the CI's own variable (ENV_BRANCHES), the pull
+request's head branch first. Outside a git checkout git never runs, so a Mac without the developer tools never sees
+macOS offer to install them. git runs with no prompt and no optional locks, for at most 3 seconds, and a value that
+isn't a branch name or a commit is left out.
+"""
+
+import os
+import re
+import subprocess
+from pathlib import Path
+
+TIMEOUT = 3
+HEAD = re.compile(r"[0-9a-f]{40}|[0-9a-f]{64}")
+# The CI variables that name the branch a detached checkout is on: GitHub (a pull request's head, then a push), GitLab,
+# Bitrise, Buildkite, CircleCI, Xcode Cloud.
+ENV_BRANCHES = ("GITHUB_HEAD_REF", "GITHUB_REF_NAME", "CI_COMMIT_REF_NAME", "BITRISE_GIT_BRANCH", "BUILDKITE_BRANCH",
+                "CIRCLE_BRANCH", "CI_BRANCH")
+MAX_BRANCH = 255
+
+
+def _repository(root):
+    """Whether ``root`` or a folder above it holds .git (a folder, or a worktree's file)."""
+    try:
+        start = Path(root).resolve()
+    except OSError:
+        return False
+    return any((folder / ".git").exists() for folder in (start, *start.parents))
+
+
+def _run(argv, cwd):
+    env = {**os.environ, "GIT_TERMINAL_PROMPT": "0", "GIT_OPTIONAL_LOCKS": "0"}
+    try:
+        result = subprocess.run(["git", "-c", "core.fsmonitor=false", *argv], cwd=str(cwd), capture_output=True,
+                                timeout=TIMEOUT, stdin=subprocess.DEVNULL, env=env)
+    except (OSError, subprocess.SubprocessError):
+        return 1, ""
+    return result.returncode, result.stdout.decode("utf-8", errors="replace")
+
+
+def _branch(text):
+    text = (text or "").strip()
+    if not text or text == "HEAD" or len(text) > MAX_BRANCH or any(ord(c) < 32 or c == "\x7f" for c in text):
+        return None
+    return text.removeprefix("refs/heads/")
+
+
+def checkout(root, *, env=None, run=None):
+    """{branch, head} of the git checkout ``root`` is in, or None outside one (or when git can't say). ``env`` is
+    os.environ and ``run(argv, cwd)`` git's runner (tests pass fakes)."""
+    if not _repository(root):
+        return None
+    env = os.environ if env is None else env
+    code, out = (run or _run)(["rev-parse", "HEAD", "--abbrev-ref", "HEAD"], root)   # the commit, then the branch
+    lines = out.splitlines() if code == 0 else []
+    head = lines[0].strip() if lines and HEAD.fullmatch(lines[0].strip()) else None
+    branch = _branch(lines[1]) if len(lines) > 1 else None
+    if branch is None and not (env.get("GITHUB_REF_TYPE") and env.get("GITHUB_REF_TYPE") != "branch"):
+        branch = next((value for value in (_branch(env.get(name)) for name in ENV_BRANCHES) if value), None)
+    if branch is None and head is None:
+        return None
+    return {"branch": branch, "head": head}

mobile_agent/testkit/heal_review.py

@@ -0,0 +1,176 @@
+"""Heals waiting for review (replay_core/heal.py writes and settles them), for `review_heals` and the Mac app's Tests
+page, under /api/tests/heals (api_routes owner "testkit").
+
+| Route | Auth | Answer |
+|---|---|---|
+| GET /api/tests/heals[?project=/abs/path] | token | {projects: [{project, root, problem, checks}]} |
+| POST /api/tests/heals {project, action, checks?} | app | {action, settled: [{name, file, steps}]} |
+| GET /api/tests/heals/frame?project=/abs/path&path=.mobster/runs/… | token | the frame, PNG or JPEG |
+
+A check is {name, file, diff, app, ios, device, heals}, and a heal is {step, from, to, why, frames: {before, after},
+run, at}. ``action`` is accept (the healed steps stay) or reject (the recorded steps come back and fail when their
+screen changes again). ``checks`` names check files relative to the project, default every check with a heal waiting. A
+frame is served only when a waiting heal names it. The routes answer 404 tests_page_off until
+MOBSTER_EXPERIMENTAL_TESTS_PAGE=1.
+"""
+
+from pathlib import Path
+
+from ..replay_core import heal as heals
+
+FRAME_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg"}
+FRAME_MAX = 20 * 1024 * 1024
+MAX_CHECKS = 50
+
+
+def pending(root, paths=()):
+    """[(Entry, heal document)] for each check under ``paths`` (default the project's checks) with a heal waiting.
+    DiscoveryError for a path that isn't a check; HealError for a heal file that can't be read."""
+    from .discover import discover
+    found = []
+    for entry in discover(list(paths), root):
+        document = heals.read(entry.path)
+        if document is not None:
+            found.append((entry, document))
+    return found
+
+
+def settle(root, found, action):
+    """Accept or reject each heal in ``found``; [(Entry, steps settled)]."""
+    from ..replay_core.checks import cache_dir_for
+    cache = cache_dir_for(Path(root) / ".mobster" / "runs")
+    settle_one = heals.accept if action == "accept" else heals.reject
+    return [(entry, settle_one(entry.path, cache)) for entry, _ in found]
+
+
+def rows(found):
+    """Each check's heals: the step, what it was, what it became, why, and the frames that show it."""
+    return [{"check": str(entry.path), "file": entry.file, "name": entry.name, "diff": str(heals.heal_file(entry.path)),
+             "heals": [{key: item.get(key) for key in ("step", "from", "to", "why", "frames", "run")}
+                       for item in document["heals"] if isinstance(item, dict)]}
+            for entry, document in found]
+
+
+def _steps(document):
+    return [{"step": item.get("step"), "from": item.get("from"), "to": item.get("to"), "why": item.get("why"),
+             "frames": {name: (item.get("frames") or {}).get(name) for name in ("before", "after")},
+             "run": item.get("run"), "at": item.get("at")}
+            for item in document["heals"] if isinstance(item, dict)]
+
+
+def _relative(path, root):
+    try:
+        return Path(path).resolve().relative_to(Path(root).resolve()).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def project_listing(root):
+    """One project's waiting heals as GET /api/tests/heals answers them, and ``problem``, the sentence for a heal file
+    that can't be read (then none are listed). A project with no checks has none."""
+    from .discover import DiscoveryError
+    problem = None
+    try:
+        found = pending(root)
+    except DiscoveryError:
+        found = []
+    except heals.HealError as error:
+        found, problem = [], f"{error}. Run the check again, or delete the file."
+    checks = []
+    for entry, document in found:
+        app = document.get("app") if isinstance(document.get("app"), dict) else {}
+        checks.append({"name": entry.name, "file": entry.file, "diff": _relative(heals.heal_file(entry.path), root),
+                       "app": app.get("version"), "ios": document.get("ios"), "device": document.get("device"),
+                       "heals": _steps(document)})
+    return {"project": Path(root).name, "root": str(root), "checks": checks, "problem": problem}
+
+
+def _frames(found):
+    return {frame for _, document in found for item in _steps(document) for frame in item["frames"].values() if frame}
+
+
+# -- routes ------------------------------------------------------------------------------------------------------------
+
+def listed(request):
+    from ..api_routes import Response
+    from .register import page_off, project_roots
+    off = page_off()
+    if off is not None:
+        return off
+    roots, bad = project_roots(request)
+    if bad is not None:
+        return bad
+    return Response.json({"projects": [project_listing(root) for root in roots]})
+
+
+def settled(request):
+    from ..api_routes import Response
+    from .discover import DiscoveryError
+    from .register import app_only, page_off, project_roots
+    off = page_off() or app_only(request, "Open Mobster to accept or reject a heal.")
+    if off is not None:
+        return off
+    body = request.body if isinstance(request.body, dict) else {}
+    checks = body.get("checks", [])
+    if set(body) - {"project", "action", "checks"} or not isinstance(body.get("project"), str) \
+            or body.get("action") not in ("accept", "reject") or not isinstance(checks, list) \
+            or len(checks) > MAX_CHECKS or not all(isinstance(item, str) and item and not Path(item).is_absolute()
+                                                     for item in checks):
+        return Response.error("Send project, action (accept or reject) and, if you like, checks: the check files "
+                              "relative to the project.", 400, "bad_request")
+    roots, bad = project_roots(request, body)
+    if bad is not None:
+        return bad
+    root = roots[0]
+    try:
+        found = pending(root)
+    except (DiscoveryError, heals.HealError):
+        found = []
+    if checks:
+        by_file = {entry.file: (entry, document) for entry, document in found}
+        missing = [item for item in checks if item not in by_file]
+        if missing:
+            return Response.error(f"{missing[0]} has no heal waiting for review.", 404, "heal_not_found")
+        found = [by_file[item] for item in checks]
+    try:
+        done = settle(root, found, body["action"])
+    except heals.HealError as error:
+        return Response.error(f"{error}. Run the check again, or delete the file.", 409, "bad_heal")
+    return Response.json({"action": body["action"],
+                          "settled": [{"name": entry.name, "file": entry.file, "steps": steps}
+                                      for entry, steps in done]})
+
+
+def frame(request):
+    from ..api_routes import Response
+    from .discover import DiscoveryError
+    from .register import page_off, project_roots
+    off = page_off()
+    if off is not None:
+        return off
+    wanted = (request.query.get("path") or [None])[0]
+    roots, bad = project_roots(request)
+    if bad is not None:
+        return bad
+    if (request.query.get("project") or [None])[0] is None or not isinstance(wanted, str):
+        return Response.error("Send project and path: a frame a waiting heal names.", 400, "bad_request")
+    root = roots[0]
+    try:
+        named = _frames(pending(root))
+    except (DiscoveryError, heals.HealError):
+        named = set()
+    file = (root / wanted).resolve() if wanted in named else None
+    runs = (root / ".mobster" / "runs").resolve()
+    kind = FRAME_TYPES.get(file.suffix.lower()) if file is not None else None
+    if file is None or kind is None or not file.is_relative_to(runs) or not file.is_file() \
+            or file.stat().st_size > FRAME_MAX:
+        return Response.error("No waiting heal has that frame.", 404, "frame_not_found")
+    return Response.bytes(file.read_bytes(), kind)
+
+
+def register_routes():
+    from ..api_routes import Route, register
+    # POST /api/tests/heals is the editor's route (editor.heals), which hands the app's bodies to ``settled``.
+    for route in (Route("testkit", "GET", "/api/tests/heals", listed, body="none"),
+                  Route("testkit", "GET", "/api/tests/heals/frame", frame, body="none")):
+        register(route)