feat!: replace --headless with --display

setup.cfg

@@ -23,7 +23,7 @@ install_requires =
     bugsy
     cryptography
     cssbeautifier
-    ffpuppet >= 0.13.1
+    ffpuppet >= 0.16.0
     FuzzManager
     jsbeautifier
     lithium-reducer >= 3.0.0

src/grizzly/args.py

@@ -103,25 +103,23 @@ def __init__(self) -> None:
         self.launcher_grp.add_argument(
             "-e",
             "--extension",
-            help="DEPRECATED. Install an extension. Specify the path to the xpi or the"
-            " directory containing the unpacked extension.",
+            help="DEPRECATED: Use '--asset' instead. Install an extension. Specify the "
+            "path to the xpi or the directory containing the unpacked extension.",
+        )
+        display_modes = ["default", "headless"]
+        if system().startswith("Linux"):
+            display_modes.append("xvfb")
+        self.launcher_grp.add_argument(
+            "--display",
+            choices=display_modes,
+            default="headless" if self.is_headless() else "default",
+            help="Display mode.",
         )
         self.launcher_grp.add_argument(
             "--display-launch-failures",
             action="store_true",
             help="Output launch failure logs to console. (default: %(default)s)",
         )
-        headless_choices = ["default"]
-        if system().startswith("Linux"):
-            headless_choices.append("xvfb")
-        self.launcher_grp.add_argument(
-            "--headless",
-            choices=headless_choices,
-            const="default",
-            default="default" if self.is_headless() else None,
-            nargs="?",
-            help="Headless mode. 'default' uses browser's built-in headless mode.",
-        )
         self.launcher_grp.add_argument(
             "--launch-attempts",
             type=int,
@@ -170,7 +168,9 @@ def __init__(self) -> None:
             "(default: %(default)s)",
         )
         self.launcher_grp.add_argument(
-            "-p", "--prefs", help="DEPRECATED. prefs.js file to use"
+            "-p",
+            "--prefs",
+            help="DEPRECATED: Use '--asset' instead. Specify prefs.js file to use",
         )
         self.launcher_grp.add_argument(
             "--relaunch",
@@ -217,7 +217,9 @@ def __init__(self) -> None:
         )
         if system().startswith("Linux"):
             self.launcher_grp.add_argument(
-                "--xvfb", action="store_true", help="DEPRECATED. Use Xvfb."
+                "--xvfb",
+                action="store_true",
+                help="DEPRECATED: Use '--display' instead. Use Xvfb.",
             )
         else:
             self.parser.set_defaults(xvfb=False)
@@ -368,7 +370,7 @@ def sanity_check(self, args: Namespace) -> None:
                 self.parser.error("--tool cannot contain whitespace")
 
         if args.xvfb:  # pragma: no cover
-            args.headless = "xvfb"
+            args.display = "xvfb"
 
 
 class GrizzlyArgs(CommonArgs):

src/grizzly/main.py

@@ -50,9 +50,8 @@ def main(args: Namespace) -> int:
 
     LOG.info("Starting Grizzly (%d)", getpid())
     LOG.debug("grizzly-framework version: %s", package_version("grizzly-framework"))
-
-    if args.headless:
-        LOG.info("Running browser headless (%s)", args.headless)
+    if args.display != "default":
+        LOG.info("Browser display mode: %s", args.display)
     if args.ignore:
         LOG.info("Ignoring: %s", ", ".join(args.ignore))
     if args.pernosco:
@@ -97,7 +96,7 @@ def main(args: Namespace) -> int:
                 args.log_limit,
                 args.memory,
                 certs=certs,
-                headless=args.headless,
+                display_mode=args.display,
                 pernosco=args.pernosco,
                 rr=args.rr,
                 valgrind=args.valgrind,

src/grizzly/reduce/core.py

@@ -769,9 +769,8 @@ def main(cls, args: Namespace | None = None) -> int:
 
         LOG.info("Starting Grizzly Reduce")
         LOG.debug("grizzly-framework version: %s", package_version("grizzly-framework"))
-
-        if args.headless:
-            LOG.info("Running browser headless (%s)", args.headless)
+        if args.display != "default":
+            LOG.info("Browser display mode: %s", args.display)
         if args.ignore:
             LOG.info("Ignoring: %s", ", ".join(args.ignore))
         if args.pernosco:
@@ -826,7 +825,7 @@ def main(cls, args: Namespace | None = None) -> int:
                 args.log_limit,
                 args.memory,
                 certs=certs,
-                headless=args.headless,
+                display_mode=args.display,
                 pernosco=args.pernosco,
                 rr=args.rr,
                 valgrind=args.valgrind,

src/grizzly/replay/replay.py

@@ -615,9 +615,8 @@ def main(cls, args: Namespace | None = None) -> int:
 
         LOG.info("Starting Grizzly Replay")
         LOG.debug("grizzly-framework version: %s", package_version("grizzly-framework"))
-
-        if args.headless:
-            LOG.info("Running browser headless (%s)", args.headless)
+        if args.display != "default":
+            LOG.info("Browser display mode: %s", args.display)
         if args.ignore:
             LOG.info("Ignoring: %s", ", ".join(args.ignore))
         if args.pernosco:
@@ -669,7 +668,7 @@ def main(cls, args: Namespace | None = None) -> int:
                 args.log_limit,
                 args.memory,
                 certs=certs,
-                headless=args.headless,
+                display_mode=args.display,
                 pernosco=args.pernosco,
                 rr=args.rr,
                 valgrind=args.valgrind,

src/grizzly/target/puppet_target.py

@@ -9,20 +9,22 @@
 from platform import system
 from signal import SIGABRT
 from tempfile import TemporaryDirectory, mkdtemp
-from typing import Any, Optional, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from ffpuppet import BrowserTimeoutError, Debugger, FFPuppet, LaunchError, Reason
+from ffpuppet.display import DisplayMode
 from ffpuppet.helpers import certutil_available, certutil_find
 from ffpuppet.sanitizer_util import SanitizerOptions
 from prefpicker import PrefPicker
 
-from sapphire import CertificateBundle
-
 from ..common.report import Report
 from ..common.utils import grz_tmp, package_version
 from .target import Result, Target, TargetLaunchError, TargetLaunchTimeout
 from .target_monitor import TargetMonitor
 
+if TYPE_CHECKING:
+    from sapphire import CertificateBundle
+
 __all__ = ("PuppetTarget",)
 __author__ = "Tyson Smith"
 __credits__ = ["Tyson Smith", "Jesse Schwartzentruber"]
@@ -92,11 +94,14 @@ def __init__(
         launch_timeout: int,
         log_limit: int,
         memory_limit: int,
+        certs: CertificateBundle | None = None,
+        display_mode: str = "default",
+        pernosco: bool = False,
+        rr: bool = False,
+        valgrind: bool = False,
         **kwds: dict[str, Any],
     ) -> None:
         LOG.debug("ffpuppet version: %s", package_version("ffpuppet"))
-        # Optional is required for Python 3.9
-        certs = cast(Optional[CertificateBundle], kwds.pop("certs", None))
         # only pass certs to FFPuppet if certutil is available
         # otherwise certs can't be used
         if certs and not certutil_available(certutil_find(binary)):
@@ -114,21 +119,21 @@ def __init__(
 
         # TODO: clean up handling debuggers
         self._debugger = Debugger.NONE
-        if kwds.pop("pernosco", False):
+        if pernosco:
             self._debugger = Debugger.PERNOSCO
-        if kwds.pop("rr", False):
+        if rr:
             self._debugger = Debugger.RR
-        if kwds.pop("valgrind", False):
+        if valgrind:
+            # TODO: replace use_valgrind with something debugger generic
             self.use_valgrind = True
             self._debugger = Debugger.VALGRIND
         self._extension: Path | None = None
         self._prefs: Path | None = None
 
-        # create Puppet object
+        # create FFPuppet object
         self._puppet = FFPuppet(
             debugger=self._debugger,
-            # Optional is required for Python 3.9
-            headless=cast(Optional[str], kwds.pop("headless", None)),
+            display_mode=DisplayMode[display_mode.upper()],
             working_path=str(grz_tmp("target")),
         )
         if kwds:
@@ -247,7 +252,7 @@ def dump_coverage(self, timeout: int = 15) -> None:
 
     def launch(self, location: str) -> None:
         # setup environment
-        env_mod = dict(self.environ)
+        env_mod: dict[str, str | None] = dict(self.environ)
         # do not allow network connections to non local endpoints
         env_mod["MOZ_DISABLE_NONLOCAL_CONNECTIONS"] = "1"
         # we always want the browser to exit when a crash is detected
@@ -261,8 +266,7 @@ def launch(self, location: str) -> None:
                 memory_limit=self.memory_limit,
                 prefs_js=self._prefs,
                 extension=[self._extension] if self._extension else None,
-                # Optional is required for Python 3.9
-                env_mod=cast(dict[str, Optional[str]], env_mod),
+                env_mod=env_mod,
                 cert_files=[self.certs.root] if self.certs else None,
             )
         except LaunchError as exc:

src/grizzly/test_main.py

@@ -33,8 +33,8 @@
         (0, ["--smoke-test"]),
         # ignore something
         (0, ["--ignore", "timeout"]),
-        # headless
-        (0, ["--headless"]),
+        # non-default display
+        (0, ["--display", "headless"]),
         # verbose mode
         (0, ["--verbose"]),
     ],