shotbox 0.3.0__py3-none-any.whl

shotbox/__init__.py

@@ -0,0 +1,10 @@
+"""shotbox, from Python: `Session` starts a sealed session, `here()` is the
+display of the `shotbox run` a script is inside, and both are a `Screen`, to
+wait on, drive and take pictures of. See shotbox/screen.py."""
+
+__version__ = "0.3.0"
+
+from .screen import Screen, SessionError, here  # noqa: E402
+from .session import Session  # noqa: E402
+
+__all__ = ["Screen", "Session", "SessionError", "here", "__version__"]

shotbox/__main__.py

@@ -0,0 +1,390 @@
+"""shotbox: reproducible screenshots of real programs, in a sealed session.
+
+    shotbox shoot OUT.png [options] -- COMMAND...   run it, wait, take the picture
+    shotbox run [options] -- COMMAND...             run it in a sealed session
+    shotbox term [options] -- COMMAND...            a terminal to take pictures of
+    shotbox wait window|port|file|ready|stable ARG  (inside a session) wait for it
+    shotbox capture OUT.png [--window RE]           (inside a session) take a picture
+    shotbox key CHORD...                            (inside a session) press keys
+    shotbox type TEXT                               (inside a session) type text
+    shotbox click X Y [--window RE]                 (inside a session) click there
+    shotbox move X Y [--window RE]                  (inside a session) point there
+    shotbox drag X1 Y1 X2 Y2 [--window RE]          (inside a session) drag
+    shotbox park                                    (inside a session) pointer out of the way
+    shotbox compare A.png B.png [--diff D.png]      how many pixels differ
+    shotbox compare REFDIR NEWDIR [NAME...]         the same, picture by picture
+
+`shotbox COMMAND --help` for each one's options.
+"""
+
+import argparse
+import os
+import sys
+import time
+from pathlib import Path
+
+from . import term, x, xtest
+from .screen import Screen, SessionError
+from .session import Session
+
+
+def size(s):
+    w, h = s.lower().split("x")
+    return int(w), int(h)
+
+
+def session_options(p):
+    g = p.add_argument_group("the session")
+    g.add_argument("--screen", type=size, default=(1280, 800), metavar="WxH",
+                   help="the display's size (1280x800)")
+    g.add_argument("--desktop", action="store_true",
+                   help="real GSettings (dconf) and the system's D-Bus services, "
+                        "for desktop shells; the default is in-memory settings "
+                        "and nothing activatable")
+    g.add_argument("--system-bus", action="store_true", help="a stand-in system bus too")
+    g.add_argument("--seed", metavar="DIR", help="start the scratch home as a copy of DIR")
+    g.add_argument("--env", action="append", default=[], metavar="NAME=VALUE",
+                   help="set a variable inside (repeatable)")
+    g.add_argument("--pass", dest="passthrough", action="append", default=[], metavar="NAME",
+                   help="let a variable through from outside (repeatable)")
+    g.add_argument("--keep", action="store_true", help="keep the scratch dir, and say where")
+    g.add_argument("--wayland", action="store_true",
+                   help="a Wayland session, under a headless sway, rather than X11 on "
+                        "Xvfb (docs/wayland.md)")
+    g.add_argument("--xwayland", action="store_true",
+                   help="a Wayland session with Xwayland in it too, for X clients")
+
+
+def make_session(a):
+    env = dict(e.split("=", 1) for e in a.env)
+    return Session(size=a.screen, desktop=a.desktop, system_bus=a.system_bus,
+                   seed=a.seed, keep=a.keep, env=env, passthrough=a.passthrough,
+                   wayland=a.wayland, xwayland=a.xwayland)
+
+
+def self_command():
+    """How to run this shotbox again, from inside a session: this checkout's
+    bin/shotbox, or else this Python's shotbox module, as installed."""
+    here = Path(__file__).resolve().parent.parent / "bin" / "shotbox"
+    return [sys.executable, str(here)] if here.exists() else [sys.executable, "-m", "shotbox"]
+
+
+def split(argv):
+    """Options, and the command after --."""
+    if "--" in argv:
+        i = argv.index("--")
+        return argv[:i], argv[i + 1:]
+    return argv, []
+
+
+def command(cmd, p):
+    if not cmd:
+        p.error("no command given, after --")
+    return cmd
+
+
+def cmd_run(argv):
+    p = argparse.ArgumentParser(prog="shotbox run",
+                                description="Run a command in a sealed session: its own X display, "
+                                            "D-Bus and home, and none of yours.")
+    session_options(p)
+    opts, cmd = split(argv)
+    a = p.parse_args(opts)
+    cmd = command(cmd, p)
+    with make_session(a) as s:
+        return s.run(cmd)
+
+
+def tail(path, n=30):
+    try:
+        lines = Path(path).read_text(errors="replace").splitlines()
+    except OSError:
+        return "(no output)"
+    return "\n".join(lines[-n:]) or "(no output)"
+
+
+def cmd_shoot(argv):
+    p = argparse.ArgumentParser(
+        prog="shotbox shoot",
+        description="Start a command in a sealed session, wait until it's ready, "
+                    "take a screenshot, and stop it.")
+    p.add_argument("out", help="the PNG to write")
+    p.add_argument("--window", metavar="RE",
+                   help="take this window (its title, a regex matched in full, "
+                        "or app=RE for its app id) "
+                        "instead of the whole display; also waits for it")
+    p.add_argument("--crop", metavar="WxH+X+Y",
+                   help="then crop to this; without it, to what the program "
+                        "wrote to $SHOTBOX_SCRATCH/crop, if it did (as "
+                        "`shotbox term --crop` does)")
+    p.add_argument("--wait", action="append", default=[], metavar="WHAT",
+                   help="wait for window:RE, port:N, file:PATH, ready (the "
+                        "program touched $SHOTBOX_SCRATCH/ready, as `shotbox "
+                        "term` does after its steps), or stable[:SECS] (the "
+                        "--window, or the display, unchanged for SECS, 0.5); "
+                        "repeatable, in order")
+    p.add_argument("--settle", type=float, default=0.3, metavar="SECS",
+                   help="then wait this long for the last paint (0.3)")
+    p.add_argument("--park", action="store_true",
+                   help="move the pointer out of the way before the picture")
+    p.add_argument("--timeout", type=float, default=30, metavar="SECS",
+                   help="give up on a wait after this long (30)")
+    p.add_argument("--log", metavar="FILE", help="keep the command's output here")
+    p.add_argument("--failed", metavar="FILE",
+                   help="if it fails, a picture of the screen goes here "
+                        "(OUT's name with -failed, beside it)")
+    session_options(p)
+    opts, cmd = split(argv)
+    a = p.parse_args(opts)
+    cmd = command(cmd, p)
+    waits = list(a.wait)
+    if a.window and not any(w.startswith("window:") for w in waits):
+        waits.insert(0, "window:" + a.window)
+    if not waits and not a.settle:
+        p.error("nothing to wait for: give --window, --wait or --settle")
+
+    with make_session(a) as s:
+        s.failed = a.failed or str(Path(a.out).with_name(Path(a.out).stem + "-failed.png"))
+        log = a.log or str(s.scratch / "command.log")
+        proc = s.spawn(cmd, log=log)
+        try:
+            for spec in waits:
+                kind, _, arg = spec.partition(":")
+                s.until(*s.test(kind, arg, window=a.window), a.timeout, alive=proc)
+            time.sleep(a.settle)
+            if proc.poll() is not None:
+                s.fail(f"the program exited (status {proc.returncode}) "
+                       "before the picture was taken")
+            if a.window and not s.backend.find_window(s.env, a.window):
+                s.fail(f"the window {a.window!r} went away")
+            crop = a.crop
+            if not crop and (s.scratch / "crop").exists():
+                crop = (s.scratch / "crop").read_text().strip()
+            s.capture(a.out, window=a.window, crop=crop, park=a.park)
+        except SessionError as e:
+            sys.stderr.write(f"shotbox: {e}\n--- {' '.join(cmd)} said ---\n{tail(log)}\n")
+            return 1
+    print(a.out)
+    return 0
+
+
+def inside():
+    """The display of the session this runs in."""
+    if not os.environ.get("SHOTBOX_SCRATCH"):
+        raise SystemExit("shotbox: this only works inside `shotbox run`")
+    return Screen()
+
+
+def cmd_wait(argv):
+    p = argparse.ArgumentParser(prog="shotbox wait",
+                                description="Inside `shotbox run`: wait for a window, "
+                                            "a port, a file, the ready file, or the "
+                                            "screen to stop changing.")
+    p.add_argument("kind", choices=("window", "port", "file", "ready", "stable"))
+    p.add_argument("arg", nargs="?", default="",
+                   help="the window's title (a regex; app=RE for its app id), the "
+                        "port, the file; for "
+                        "stable, how long it must hold still (0.5)")
+    p.add_argument("--window", metavar="RE",
+                   help="for stable: watch this window rather than the display")
+    p.add_argument("--timeout", type=float, default=30)
+    p.add_argument("--failed", metavar="FILE",
+                   help="if it gives up, a picture of the screen goes here "
+                        "($SHOTBOX_FAILED)")
+    a = p.parse_args(argv)
+    screen = inside()
+    screen.failed = a.failed or screen.failed
+    screen.until(*screen.test(a.kind, a.arg, window=a.window), a.timeout)
+    return 0
+
+
+def cmd_capture(argv):
+    p = argparse.ArgumentParser(prog="shotbox capture",
+                                description="Inside `shotbox run`: screenshot the display "
+                                            "or one window.")
+    p.add_argument("out")
+    p.add_argument("--window", metavar="RE")
+    p.add_argument("--crop", metavar="WxH+X+Y")
+    p.add_argument("--park", action="store_true",
+                   help="move the pointer out of the way first, as `shotbox park`")
+    a = p.parse_args(argv)
+    inside().capture(a.out, window=a.window, crop=a.crop, park=a.park)
+    return 0
+
+
+def cmd_key(argv):
+    p = argparse.ArgumentParser(prog="shotbox key",
+                                description="Inside `shotbox run`: press and release each "
+                                            "chord in turn, e.g. ctrl+comma, Return, "
+                                            "alt+shift+Tab.")
+    p.add_argument("chords", nargs="+", metavar="CHORD")
+    a = p.parse_args(argv)
+    inside().key(*a.chords)
+    return 0
+
+
+def cmd_type(argv):
+    p = argparse.ArgumentParser(prog="shotbox type",
+                                description="Inside `shotbox run`: type text into whatever "
+                                            "has the keyboard focus.")
+    p.add_argument("text")
+    a = p.parse_args(argv)
+    inside().type(a.text)
+    return 0
+
+
+def pointer_command(name, what):
+    def cmd(argv):
+        p = argparse.ArgumentParser(prog=f"shotbox {name}",
+                                    description=f"Inside `shotbox run`: {what}.")
+        p.add_argument("x", type=int)
+        p.add_argument("y", type=int)
+        p.add_argument("--window", metavar="RE",
+                       help="X and Y are inside this window rather than the screen")
+        if name == "click":
+            p.add_argument("--button", type=int, default=1, help="1 left, 2 middle, 3 right")
+            p.add_argument("--double", action="store_true", help="click twice")
+        a = p.parse_args(argv)
+        if name == "click":
+            inside().click(a.x, a.y, window=a.window, button=a.button, double=a.double)
+        else:
+            inside().move(a.x, a.y, window=a.window)
+        return 0
+    return cmd
+
+
+def cmd_drag(argv):
+    p = argparse.ArgumentParser(prog="shotbox drag",
+                                description="Inside `shotbox run`: press at X1 Y1, move to "
+                                            "X2 Y2, release: a divider, a slider, a drop.")
+    for n in ("x1", "y1", "x2", "y2"):
+        p.add_argument(n, type=int)
+    p.add_argument("--window", metavar="RE",
+                   help="the points are inside this window rather than the screen")
+    p.add_argument("--button", type=int, default=1)
+    a = p.parse_args(argv)
+    inside().drag(a.x1, a.y1, a.x2, a.y2, window=a.window, button=a.button)
+    return 0
+
+
+def cmd_park(argv):
+    p = argparse.ArgumentParser(prog="shotbox park",
+                                description="Inside `shotbox run`: move the pointer to the "
+                                            "screen's bottom-right corner, off whatever it "
+                                            "was hovering, and wait (up to --settle) for "
+                                            "the repaint.")
+    p.add_argument("--settle", type=float, default=2.0, metavar="SECS",
+                   help="wait at most this long for the display to hold still (2)")
+    a = p.parse_args(argv)
+    inside().park(settle=a.settle)
+    return 0
+
+
+def per_name(values, name, default):
+    """--fuzz and --max: the last NAME=VALUE for this picture, else the last
+    plain VALUE, else the default."""
+    named = [v.split("=", 1)[1] for v in values if v.split("=", 1)[0] == name and "=" in v]
+    plain = [v for v in values if "=" not in v]
+    return (named or plain or [default])[-1]
+
+
+def cmd_compare(argv):
+    p = argparse.ArgumentParser(prog="shotbox compare",
+                                description="Count the pixels that differ between two "
+                                            "images; fail if more than --max do. Given "
+                                            "two directories, compare each picture in "
+                                            "the first (or each NAME) with the one of "
+                                            "the same name in the second.")
+    p.add_argument("a", help="an image, or a directory of the pictures as they should be")
+    p.add_argument("b", help="an image, or a directory of fresh pictures")
+    p.add_argument("names", nargs="*", metavar="NAME",
+                   help="with directories: just these (NAME or NAME.png)")
+    p.add_argument("--diff", metavar="OUT",
+                   help="write the differences, marked in red; with directories, "
+                        "OUT is a directory, and each picture that fails gets NAME-diff.png")
+    p.add_argument("--fuzz", action="append", default=[], metavar="[NAME=]PCT",
+                   help="colors this close count as the same (0%%); NAME=PCT for one "
+                        "picture (repeatable)")
+    p.add_argument("--max", action="append", default=[], metavar="[NAME=]N",
+                   help="pixels allowed to differ (0); NAME=N for one picture (repeatable)")
+    a = p.parse_args(argv)
+    def fuzz(name):
+        return per_name(a.fuzz, name, "0%")
+
+    def most(name):
+        return int(per_name(a.max, name, 0))
+
+    dirs = Path(a.a).is_dir(), Path(a.b).is_dir()
+    if dirs[0] != dirs[1]:
+        p.error("compare two images, or two directories")
+    if not dirs[0]:
+        if a.names:
+            p.error("NAMEs go with two directories")
+        missing = [f for f in (a.a, a.b) if not Path(f).exists()]
+        if missing:
+            sys.stderr.write(f"shotbox: no {' or '.join(missing)}\n")
+            return 2
+        try:
+            n = x.compare(a.a, a.b, diff=a.diff, fuzz=fuzz(None))
+        except ValueError as e:
+            sys.stderr.write(f"shotbox: {e}\n")
+            return 2
+        print(f"{n} pixels differ")
+        return 0 if n <= most(None) else 1
+
+    names = [n.removesuffix(".png") for n in a.names] or sorted(
+        f.stem for f in Path(a.a).glob("*.png"))
+    if not names:
+        sys.stderr.write(f"shotbox: no pictures in {a.a}\n")
+        return 2
+    if a.diff:
+        Path(a.diff).mkdir(parents=True, exist_ok=True)
+    bad = []
+    for name in names:
+        ref, new = Path(a.a) / f"{name}.png", Path(a.b) / f"{name}.png"
+        missing = [str(f) for f in (ref, new) if not f.exists()]
+        if missing:
+            print(f"{name}: no {' or '.join(missing)}")
+            bad.append(name)
+            continue
+        diff = Path(a.diff) / f"{name}-diff.png" if a.diff else None
+        try:
+            n = x.compare(ref, new, fuzz=fuzz(name))
+        except ValueError as e:
+            print(f"{name}: {e}")
+            bad.append(name)
+            continue
+        if n > most(name):
+            if diff:
+                x.compare(ref, new, diff=diff, fuzz=fuzz(name))
+            print(f"{name}: {n} pixels differ" + (f"; see {diff}" if diff else ""))
+            bad.append(name)
+        else:
+            print(f"{name}: {'the same' if n == 0 else f'{n} pixels differ, allowed'}")
+    if bad:
+        print(f"differ: {', '.join(bad)}")
+        return 1
+    return 0
+
+
+COMMANDS = {"run": cmd_run, "shoot": cmd_shoot, "term": term.main, "wait": cmd_wait,
+            "capture": cmd_capture, "compare": cmd_compare, "key": cmd_key,
+            "type": cmd_type, "click": pointer_command("click", "move the pointer and click"),
+            "move": pointer_command("move", "move the pointer, for a hover"),
+            "drag": cmd_drag, "park": cmd_park}
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    if not argv or argv[0] in ("-h", "--help") or argv[0] not in COMMANDS:
+        sys.stdout.write(__doc__.lstrip())
+        return 0 if not argv or argv[0] in ("-h", "--help") else 2
+    try:
+        return COMMANDS[argv[0]](argv[1:])
+    except (SessionError, xtest.XError) as e:
+        sys.stderr.write(f"shotbox: {e}\n")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

shotbox/screen.py

@@ -0,0 +1,206 @@
+"""A session's display, from Python: waiting on it, driving it, and taking
+pictures of it. What the `shotbox wait`, `capture`, `key`, `click` and
+friends commands do, without a process for each step.
+
+Inside `shotbox run`, the display is the one in the environment:
+
+    import shotbox
+    screen = shotbox.here()
+    screen.wait_window("Text Editor")
+    screen.click(40, 60, window="Text Editor")
+    screen.wait_stable(window="Text Editor")
+    screen.capture("editor.png", window="Text Editor", park=True)
+
+A Session is a Screen too, for a script that starts its own.
+
+Anything that fails raises SessionError, saying what. With `failed` set (or
+$SHOTBOX_FAILED), a failure first leaves a picture of the screen there.
+"""
+
+import os
+import time
+from pathlib import Path
+
+from . import wl, wlinput, x, xtest
+
+
+class SessionError(RuntimeError):
+    pass
+
+
+def wait_for(what, test, timeout, interval=0.1, alive=None):
+    """Poll `test()` until it returns something true, or fail saying what."""
+    end = time.monotonic() + timeout
+    while True:
+        got = test()
+        if got:
+            return got
+        if alive is not None and alive.poll() is not None:
+            raise SessionError(f"gave up waiting for {what}: the program exited "
+                               f"(status {alive.returncode})")
+        if time.monotonic() > end:
+            raise SessionError(f"gave up waiting for {what} after {timeout:g}s")
+        time.sleep(interval)
+
+
+class Screen:
+    """The display in `env` (DISPLAY, XAUTHORITY and SHOTBOX_SCRATCH; the
+    process's own environment by default)."""
+
+    def __init__(self, env=None, failed=None):
+        self.env = dict(os.environ if env is None else env)
+        self.failed = failed or self.env.get("SHOTBOX_FAILED")
+        self._x = None
+
+    # --- failing --------------------------------------------------------------
+
+    def fail(self, message):
+        """Raise SessionError(message), first taking a picture of the screen
+        to `failed` if it's set, and saying where."""
+        if self.failed and x.try_capture(self.env, self.failed, self.backend):
+            message += f"; the screen then: {self.failed}"
+        raise SessionError(message)
+
+    def until(self, what, test, timeout=30, alive=None):
+        """Poll `test()` until it returns something true, and return that;
+        or fail, saying it gave up waiting for `what`. With `alive` (a
+        process), fail sooner if it exits."""
+        try:
+            return wait_for(what, test, timeout, alive=alive)
+        except SessionError as e:
+            self.fail(str(e))
+
+    # --- waiting --------------------------------------------------------------
+
+    def test(self, kind, arg="", window=None):
+        """What to say, and what to poll, for a wait: window (a regex for
+        its title, or app=RE for its app id), port,
+        file, ready, or stable (seconds; `window` to watch just that one)."""
+        if kind == "window":
+            return f"a {x.matcher(arg)[1]}", lambda: self.backend.find_window(self.env, arg)
+        if kind == "port":
+            return f"port {arg}", lambda: x.port_open(int(arg))
+        if kind == "file":
+            return f"{arg} to exist", lambda: Path(arg).exists()
+        if kind == "ready":
+            ready = Path(self.env["SHOTBOX_SCRATCH"]) / "ready"
+            return "the program to say it's ready", ready.exists
+        if kind == "stable":
+            quiet = float(arg) if arg else 0.5
+            where = f"the window {window!r}" if window else "the display"
+            return (f"{where} to hold still for {quiet:g}s",
+                    x.Still(self.env, window, quiet, self.backend))
+        raise SessionError(f"don't know how to wait for {kind!r} "
+                           "(window, port, file, ready or stable)")
+
+    def wait_window(self, name, timeout=30):
+        """Wait for a viewable window whose title matches `name` (a regex,
+        matched in full), or, with app=RE, whose app id does; its (id, name,
+        width, height, x, y)."""
+        return self.until(*self.test("window", name), timeout)
+
+    def wait_port(self, port, timeout=30):
+        self.until(*self.test("port", port), timeout)
+
+    def wait_file(self, path, timeout=30):
+        self.until(*self.test("file", path), timeout)
+
+    def wait_ready(self, timeout=30):
+        """Wait for $SHOTBOX_SCRATCH/ready, which `shotbox term` writes."""
+        self.until(*self.test("ready"), timeout)
+
+    def wait_stable(self, seconds=0.5, window=None, timeout=30):
+        """Wait until the display, or the window named `window`, has looked
+        the same for `seconds`: for the paint after a click, a panel sliding
+        in, a toast going away."""
+        self.until(*self.test("stable", seconds, window), timeout)
+
+    # --- windows and pictures -------------------------------------------------
+
+    def window(self, name):
+        """The window `name` asks for (a title regex, or app=RE), or fail."""
+        w = self.backend.find_window(self.env, name)
+        if not w:
+            self.fail(f"no {x.matcher(name)[1]}")
+        return w
+
+    def capture(self, out, window=None, crop=None, park=False):
+        """A picture of the display, or of the window named `window`, to
+        `out` (a PNG), then cropped (WxH+X+Y). With `park`, the pointer
+        goes out of the way first, so nothing shows its hover."""
+        if park:
+            self.park()
+        self.backend.capture(self.env, out, window=self.window(window) if window else None,
+                             crop=crop)
+        return Path(out)
+
+    # --- input ----------------------------------------------------------------
+
+    @property
+    def wayland(self):
+        """Whether this is a Wayland session (under sway) rather than X11."""
+        return bool(self.env.get("SWAYSOCK"))
+
+    @property
+    def backend(self):
+        """The module that finds windows and takes pictures: wl or x."""
+        return wl if self.wayland else x
+
+    @property
+    def xt(self):
+        """The input connection, opened on first use and kept: XTEST on
+        X11, a virtual keyboard and pointer on Wayland."""
+        if self._x is None:
+            self._x = (wlinput if self.wayland else xtest).Display(self.env)
+        return self._x
+
+    def _at(self, px, py, window):
+        if not window:
+            return px, py
+        w = self.window(window)
+        return w[4] + px, w[5] + py
+
+    def key(self, *chords):
+        """Press and release each chord in turn: ctrl+comma, Return,
+        alt+shift+Tab."""
+        for c in chords:
+            self.xt.chord(c)
+
+    def type(self, text):
+        """Type ASCII text into whatever has the keyboard focus."""
+        self.xt.type(text)
+
+    def move(self, px, py, window=None):
+        """Move the pointer to X, Y on the screen, or inside `window`."""
+        self.xt.move(*self._at(px, py, window))
+
+    def click(self, px, py, window=None, button=1, double=False):
+        self.xt.click(*self._at(px, py, window), button=button, count=2 if double else 1)
+
+    def drag(self, x1, y1, x2, y2, window=None, button=1):
+        dx, dy = self._at(0, 0, window)
+        self.xt.drag(x1 + dx, y1 + dy, x2 + dx, y2 + dy, button=button)
+
+    def park(self, settle=2.0):
+        """Move the pointer to the screen's bottom-right corner, off whatever
+        it was hovering, then wait up to `settle` seconds for the display to
+        hold still, for the repaint. A display that keeps changing (a video,
+        a spinner) isn't a failure here: it's taken as it is."""
+        self.xt.move(self.xt.width - 1, self.xt.height - 1)
+        if settle:
+            try:
+                wait_for("", x.Still(self.env, quiet=0.3, backend=self.backend), settle)
+            except SessionError:
+                pass
+
+    def close(self):
+        if self._x is not None:
+            self._x.close()
+            self._x = None
+
+
+def here():
+    """The display of the `shotbox run` this is inside."""
+    if not os.environ.get("SHOTBOX_SCRATCH"):
+        raise SessionError("not inside a shotbox session")
+    return Screen()