tapwright 1.2.0__tar.gz → 1.3.0__tar.gz

{tapwright-1.2.0/tapwright.egg-info → tapwright-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tapwright
-Version: 1.2.0
+Version: 1.3.0
 Summary: Let LLM agents test apps on your real iPhone, from Windows, Linux or macOS. No Mac needed.
 Author: bo5amis
 License-Expression: MIT
@@ -177,7 +177,9 @@ repository too.
 | `viewer` | opens the live view in a browser on this computer, for you (the agent never gets the link: its key could approve a held-back touch) |
 | `run` | several steps in one call, each with an optional check (`"expect": {"text": "Saved"}`); stops at the first that fails and answers once |
 | `record`, `replay` | save what the agent does as a script, and run it again; `tapwright replay FILE --apps ID` runs it in CI with no agent (exit code, `--junit`) |
+| `logs`, `crash` | the app's own log (level, grep, since) and its crash reports, read from the phone; a failed `run` step adds the log lines from that step, and a call the app crashed in ends with a note |
 | `audit` | an accessibility check of the screen, by Apple's own XCTest audit: low contrast, tap targets under 44x44 pt, missing labels, clipped text, text that doesn't scale, wrong traits, duplicate ids; each issue names the element and the fix |
+| `performance` | memory, CPU and frame rate of the app's own process while it waits, around a tap, or from a cold start to the first settled screen (`launch`); `run` and scripts can hold it to limits with `expect.under` |
 | `compare_screen` | visual regression: the first call saves the screen as a reference picture, later calls answer `Matches` or `Differs` with where it changed and a picture with the changes in red; `threshold` and `ignore` (a clock, an ad) tune it, and the status bar is never compared |
 | `filmstrip` | several frames from the live stream in one numbered picture, for animations and loading states; `tap` first taps and films what it sets off |
 

{tapwright-1.2.0 → tapwright-1.3.0}/README.md

@@ -140,7 +140,9 @@ repository too.
 | `viewer` | opens the live view in a browser on this computer, for you (the agent never gets the link: its key could approve a held-back touch) |
 | `run` | several steps in one call, each with an optional check (`"expect": {"text": "Saved"}`); stops at the first that fails and answers once |
 | `record`, `replay` | save what the agent does as a script, and run it again; `tapwright replay FILE --apps ID` runs it in CI with no agent (exit code, `--junit`) |
+| `logs`, `crash` | the app's own log (level, grep, since) and its crash reports, read from the phone; a failed `run` step adds the log lines from that step, and a call the app crashed in ends with a note |
 | `audit` | an accessibility check of the screen, by Apple's own XCTest audit: low contrast, tap targets under 44x44 pt, missing labels, clipped text, text that doesn't scale, wrong traits, duplicate ids; each issue names the element and the fix |
+| `performance` | memory, CPU and frame rate of the app's own process while it waits, around a tap, or from a cold start to the first settled screen (`launch`); `run` and scripts can hold it to limits with `expect.under` |
 | `compare_screen` | visual regression: the first call saves the screen as a reference picture, later calls answer `Matches` or `Differs` with where it changed and a picture with the changes in red; `threshold` and `ignore` (a clock, an ad) tune it, and the status bar is never compared |
 | `filmstrip` | several frames from the live stream in one numbered picture, for animations and loading states; `tap` first taps and films what it sets off |
 

{tapwright-1.2.0 → tapwright-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tapwright"
-version = "1.2.0"
+version = "1.3.0"
 description = "Let LLM agents test apps on your real iPhone, from Windows, Linux or macOS. No Mac needed."
 readme = "README.md"
 requires-python = ">=3.10"

{tapwright-1.2.0 → tapwright-1.3.0}/tapwright/__init__.py

@@ -1,2 +1,2 @@
 """tapwright: let LLM agents test apps on your real iPhone."""
-__version__ = "1.2.0"
+__version__ = "1.3.0"

tapwright-1.3.0/tapwright/aio.py

@@ -0,0 +1,56 @@
+"""Waiting that is safe to cancel, for daemon.py and device.py alike."""
+from __future__ import annotations
+
+import asyncio
+from typing import Awaitable, TypeVar
+
+_T = TypeVar("_T")
+
+
+def _retrieved(task: asyncio.Future) -> None:
+    """A finished child's error is read, so it is never logged as `never retrieved`."""
+    if not task.cancelled():
+        task.exception()
+
+
+async def _join(inner: asyncio.Future) -> None:
+    """Cancel the child and wait until it has ended (its own cleanup included), whatever it ended with. A cancel of
+    the caller during the wait is kept, not acted on: the child is still waited for (it is not cancelled again, which
+    would cut its cleanup short), and the cancel is raised once it has ended."""
+    inner.cancel()
+    cancelled = False
+    while not inner.done():
+        try:
+            await asyncio.wait({inner})
+        except asyncio.CancelledError:
+            cancelled = True  # (the child was cancelled once already: its cleanup is not cut short by this)
+    _retrieved(inner)
+    if cancelled:
+        raise asyncio.CancelledError
+
+
+async def wait_for(awaitable: Awaitable[_T], seconds: float) -> _T:
+    """`asyncio.wait_for`, except that
+    - a cancel of the caller is never lost (before Python 3.12, wait_for gives its result and drops the cancel when
+      the two come in the same loop turn, and a loop that waits for something again then never ends: found in
+      `_watch_logs`, which `supervise` cancels), and
+    - the child is always cancelled and joined before this returns or raises, and its error is always retrieved
+      (cleanup of a DVT session that is still running must not outlive the caller)."""
+    inner = asyncio.ensure_future(awaitable)
+    try:
+        done, _ = await asyncio.wait({inner}, timeout=seconds)
+    except BaseException:  # the caller was cancelled (or the loop is closing)
+        await _join_quietly(inner)
+        raise
+    if not done:
+        await _join(inner)
+        raise asyncio.TimeoutError
+    return inner.result()
+
+
+async def _join_quietly(inner: asyncio.Future) -> None:
+    """_join for a caller that is being cancelled: the cancel is already on its way, and stays."""
+    try:
+        await _join(inner)
+    except asyncio.CancelledError:
+        pass

{tapwright-1.2.0 → tapwright-1.3.0}/tapwright/batch.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
-from . import compare, ui
+from . import compare, performance, ui
 from . import shot as shotlib
 from .control import Refused
 
@@ -13,7 +13,7 @@ MAX_STEPS = 50
 BATCH_LIMIT = 120.0  # seconds a whole batch may take
 EXPECT_DEFAULT, EXPECT_MIN, EXPECT_MAX = 2.0, 0.5, 30.0
 STEP_TOOLS = ("tap", "long_press", "type_text", "scroll", "toggle", "back", "swipe", "open_url", "wait", "wait_for",
-              "alert", "press_button", "rotate", "open_app", "close_app", "compare_screen")
+              "alert", "press_button", "rotate", "open_app", "close_app", "compare_screen", "performance")
 EXPECT_KINDS = ("text", "id", "label")
 FORMAT, VERSION = "agent-tools-script", 1
 
@@ -32,14 +32,14 @@ def check_steps(steps: object, *, script: bool = False) -> list[dict]:
         if step["tool"] not in STEP_TOOLS:
             raise Refused("bad_params", f"step {n}: {step['tool']!r} can't be a step; a step is one of "
                                         f"{', '.join(STEP_TOOLS)}")
-        target = step.get("target")
+        target = step.get("tap") if step["tool"] == "performance" else step.get("target")
         if script and isinstance(target, dict) and "ref" in target:
             raise Refused("bad_params", f"step {n}: a script can't use refs (they don't outlive a session); use the "
                                         "element's id, label or text")
         if step["tool"] == "compare_screen":
             check_compare_step(step, n, script)
         if "expect" in step:
-            check_expect(step["expect"], n, script)
+            check_expect(step["expect"], n, script, step["tool"])
     return steps
 
 
@@ -65,9 +65,18 @@ def _no_refs(ignore: object, n: int, script: bool) -> None:
                                     "the element's id, label or text")
 
 
-def check_expect(expect: object, n: int, script: bool = False) -> None:
+def check_expect(expect: object, n: int, script: bool = False, tool: str = "") -> None:
     if not isinstance(expect, dict):
         raise Refused("bad_params", f"step {n}: expect must be an object, like {{\"text\": \"Saved\"}}")
+    if "under" in expect or tool == "performance":
+        # a performance step is checked against limits, and only a performance step has them
+        if tool != "performance" or set(expect) != {"under"}:
+            raise Refused("bad_params", f"step {n}: {performance.UNDER_ONLY}")
+        try:
+            performance.check_under(expect["under"])
+        except ValueError as e:
+            raise Refused("bad_params", f"step {n}: {e}") from None
+        return
     given = [k for k in EXPECT_KINDS if expect.get(k) is not None]
     matches = expect.get("matches") is not None
     if len(given) > 1 or (not given and not matches):
@@ -101,7 +110,7 @@ def args_of(step: dict) -> dict:
     """The tool call a step makes: its parameters without `tool` and `expect`, and without an answer of its own
     (the batch answers once)."""
     args = {k: v for k, v in step.items() if k not in ("tool", "expect", "route", "secure", "look", "screenshot")}
-    if step["tool"] != "close_app":
+    if step["tool"] not in ("close_app", "performance"):  # (a measurement has no list to show)
         args["look"] = False
     return args
 
@@ -125,6 +134,7 @@ def summary(step: dict) -> str:
     extra = {"scroll": step.get("to") or step.get("direction") or "down", "wait": step.get("seconds"),
              "open_app": step.get("app"), "close_app": step.get("app"), "open_url": step.get("url"),
              "alert": step.get("action"), "press_button": step.get("name"), "rotate": step.get("to"),
+             "performance": "launch" if step.get("launch") else step.get("seconds"),
              "compare_screen": json.dumps(step["name"], ensure_ascii=False) if isinstance(step.get("name"), str) else None,
              "wait_for": next((json.dumps(step[k], ensure_ascii=False) for k in EXPECT_KINDS if step.get(k)), None)}
     shown = extra.get(tool)

{tapwright-1.2.0 → tapwright-1.3.0}/tapwright/cli.py

@@ -36,7 +36,7 @@ import sys
 import time
 from pathlib import Path
 
-from . import store
+from . import diagnostics, store
 from .repair import Phone, run_fixes
 
 
@@ -508,7 +508,13 @@ def replay(a) -> int:
         except client.DaemonError as e:
             print(f"{f}: Error {e.code}: {e}")
             kind = "error" if e.code in START_CODES and not str(e).startswith("Ran ") else "failed"
-            results.append((f, kind, f"{e.code}: {e}", time.monotonic() - began))
+            message = f"{e.code}: {e}"
+            if str(e).startswith("Ran ") and any(ln.startswith("Note: " + diagnostics.CRASHED) for ln in str(e).splitlines()):
+                # the app crashed: its report is pulled next to the script and named (AGENT-TOOLS §15.4)
+                if saved := pull_crash_beside(path):
+                    message += "\n" + diagnostics.FAILURE_CRASH_FILE.format(path=saved)
+                    print(f"{f}: {diagnostics.FAILURE_CRASH_FILE.format(path=saved)}")
+            results.append((f, kind, message, time.monotonic() - began))
             continue
         print(f"{f}: {answer.get('text', '')}")
         results.append((f, "ok", "", time.monotonic() - began))
@@ -518,6 +524,26 @@ def replay(a) -> int:
     return 2 if "error" in kinds else 1 if "failed" in kinds else 0
 
 
+def pull_crash_beside(script: str) -> str | None:
+    """The app's newest crash report (the daemon's `crash` with pull), copied to
+    `<script dir>/<script name>.diff/<script name>.crash.ips`; its path, or None when there is none to copy."""
+    import re
+    import shutil
+    from . import client
+    try:
+        text = client.call("crash", {"pull": True}, "cli-replay", timeout=60.0).get("text", "")
+        saved = re.search(r"^Saved: (.+)$", text, re.M)
+        if saved is None:
+            return None
+        path = Path(script)
+        target = path.parent / f"{path.stem}.diff" / f"{path.stem}.crash.ips"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(saved.group(1), target)
+        return str(target)
+    except (client.DaemonError, OSError):
+        return None
+
+
 def write_junit(out: str, results: list[tuple[str, str, str, float]]) -> None:
     """One <testcase> per script; a stop is a <failure>, a script that couldn't start an <error>."""
     from xml.etree import ElementTree as ET
@@ -531,6 +557,8 @@ def write_junit(out: str, results: list[tuple[str, str, str, float]]) -> None:
         if kind != "ok":
             node = ET.SubElement(case, "failure" if kind == "failed" else "error", message=message.splitlines()[0])
             node.text = message
+            if output := diagnostics.junit_output(message):  # the app's log lines and crash, for whoever reads the report
+                ET.SubElement(case, "system-out").text = output
     Path(out).parent.mkdir(parents=True, exist_ok=True)
     ET.ElementTree(suite).write(out, encoding="utf-8", xml_declaration=True)