Add browser arguments option (#138)

Ref #137

This change adds `--browser-args` option to the CLI, then passes a list of arguments to the browser launch function.

The argument can be included multiple times to list multiple arguments.

This enables users to pass flags to the browser, such as `--font-render-hinting=none`, `--disable-gpu`, etc.

These flags can have an effect on how screenshots are captured across different platforms.

Detailed reason here: #137

docs/authentication.md

@@ -49,6 +49,7 @@ Usage: shot-scraper auth [OPTIONS] URL CONTEXT_FILE
 Options:
   -b, --browser [chromium|firefox|webkit|chrome|chrome-beta]
                                   Which browser to use
+  -B, --browser-args TEXT         Additional arguments to pass to the browser
   --user-agent TEXT               User-Agent header to use
   --devtools                      Open browser DevTools
   --log-console                   Write console.log() to stderr

docs/html.md

@@ -64,6 +64,7 @@ Options:
   --log-console                   Write console.log() to stderr
   -b, --browser [chromium|firefox|webkit|chrome|chrome-beta]
                                   Which browser to use
+  -B, --browser-args TEXT         Additional arguments to pass to the browser
   --user-agent TEXT               User-Agent header to use
   --fail                          Fail with an error code if a page returns an
                                   HTTP error

docs/javascript.md

@@ -210,6 +210,7 @@ Options:
   -r, --raw                       Output JSON strings as raw text
   -b, --browser [chromium|firefox|webkit|chrome|chrome-beta]
                                   Which browser to use
+  -B, --browser-args TEXT         Additional arguments to pass to the browser
   --user-agent TEXT               User-Agent header to use
   --reduced-motion                Emulate 'prefers-reduced-motion' media feature
   --log-console                   Write console.log() to stderr

docs/multi.md

@@ -136,6 +136,7 @@ Options:
   -o, --output TEXT               Just take shots matching these output files
   -b, --browser [chromium|firefox|webkit|chrome|chrome-beta]
                                   Which browser to use
+  -B, --browser-args TEXT         Additional arguments to pass to the browser
   --user-agent TEXT               User-Agent header to use
   --reduced-motion                Emulate 'prefers-reduced-motion' media feature
   --log-console                   Write console.log() to stderr

docs/screenshots.md

@@ -160,6 +160,20 @@ The output looks like this:
 ```
 Note that the `size` field here will be the size of the response in bytes, but in some circumstances this will not be available and it will be returned as `"size": null`.
 
+## Browser arguments
+
+Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](https://peter.sh/experiments/chromium-command-line-switches/).
+
+For example, to remove font render hinting:
+
+    shot-scraper https://simonwillison.net/ -o no-hinting.png \
+      --height 800 --browser-args "--font-render-hinting=none"
+
+To add multiple arguments, add `--browser-args` for each argument:
+
+    shot-scraper https://simonwillison.net/ -o no-hinting-no-gpu.png \
+      --height 800 --browser-args "--font-render-hinting=none" --browser-args "--disable-gpu"
+
 ## Taking screenshots of local HTML files
 
 You can pass the path to an HTML file on disk to take a screenshot of that rendered file:
@@ -312,6 +326,7 @@ Options:
   --log-console                   Write console.log() to stderr
   -b, --browser [chromium|firefox|webkit|chrome|chrome-beta]
                                   Which browser to use
+  -B, --browser-args TEXT         Additional arguments to pass to the browser
   --user-agent TEXT               User-Agent header to use
   --reduced-motion                Emulate 'prefers-reduced-motion' media feature
   --fail                          Fail with an error code if a page returns an

shot_scraper/cli.py

@@ -31,6 +31,16 @@ def browser_option(fn):
     return fn
 
 
+def browser_args_option(fn):
+    click.option(
+        "--browser-args",
+        "-B",
+        multiple=True,
+        help="Additional arguments to pass to the browser",
+    )(fn)
+    return fn
+
+
 def user_agent_option(fn):
     click.option("--user-agent", help="User-Agent header to use")(fn)
     return fn
@@ -202,6 +212,7 @@ def cli():
 )
 @log_console_option
 @browser_option
+@browser_args_option
 @user_agent_option
 @reduced_motion_option
 @skip_fail_options
@@ -231,6 +242,7 @@ def shot(
     log_requests,
     log_console,
     browser,
+    browser_args,
     user_agent,
     reduced_motion,
     skip,
@@ -296,6 +308,7 @@ def shot(
             devtools=devtools,
             retina=retina,
             browser=browser,
+            browser_args=browser_args,
             user_agent=user_agent,
             timeout=timeout,
             reduced_motion=reduced_motion,
@@ -348,14 +361,15 @@ def _browser_context(
     devtools=False,
     retina=False,
     browser="chromium",
+    browser_args=None,
     user_agent=None,
     timeout=None,
     reduced_motion=False,
     bypass_csp=False,
     auth_username=None,
     auth_password=None,
 ):
-    browser_kwargs = dict(headless=not interactive, devtools=devtools)
+    browser_kwargs = dict(headless=not interactive, devtools=devtools, args=browser_args)
     if browser == "chromium":
         browser_obj = p.chromium.launch(**browser_kwargs)
     elif browser == "firefox":
@@ -421,6 +435,7 @@ def _browser_context(
     multiple=True,
 )
 @browser_option
+@browser_args_option
 @user_agent_option
 @reduced_motion_option
 @log_console_option
@@ -436,6 +451,7 @@ def multi(
     noclobber,
     outputs,
     browser,
+    browser_args,
     user_agent,
     reduced_motion,
     log_console,
@@ -471,6 +487,7 @@ def multi(
             auth,
             retina=retina,
             browser=browser,
+            browser_args=browser_args,
             user_agent=user_agent,
             timeout=timeout,
             reduced_motion=reduced_motion,
@@ -601,6 +618,7 @@ def accessibility(
     help="Output JSON strings as raw text",
 )
 @browser_option
+@browser_args_option
 @user_agent_option
 @reduced_motion_option
 @log_console_option
@@ -615,6 +633,7 @@ def javascript(
     output,
     raw,
     browser,
+    browser_args,
     user_agent,
     reduced_motion,
     log_console,
@@ -657,6 +676,7 @@ def javascript(
             p,
             auth,
             browser=browser,
+            browser_args=browser_args,
             user_agent=user_agent,
             reduced_motion=reduced_motion,
             bypass_csp=bypass_csp,
@@ -838,6 +858,7 @@ def pdf(
 )
 @log_console_option
 @browser_option
+@browser_args_option
 @user_agent_option
 @skip_fail_options
 @bypass_csp_option
@@ -852,6 +873,7 @@ def html(
     wait,
     log_console,
     browser,
+    browser_args,
     user_agent,
     skip,
     fail,
@@ -879,6 +901,7 @@ def html(
             p,
             auth,
             browser=browser,
+            browser_args=browser_args,
             user_agent=user_agent,
             bypass_csp=bypass_csp,
             auth_username=auth_username,
@@ -943,10 +966,11 @@ def install(browser):
     type=click.Path(file_okay=True, writable=True, dir_okay=False, allow_dash=True),
 )
 @browser_option
+@browser_args_option
 @user_agent_option
 @click.option("--devtools", is_flag=True, help="Open browser DevTools")
 @log_console_option
-def auth(url, context_file, browser, user_agent, devtools, log_console):
+def auth(url, context_file, browser, browser_args, user_agent, devtools, log_console):
     """
     Open a browser so user can manually authenticate with the specified site,
     then save the resulting authentication context to a file.
@@ -962,6 +986,7 @@ def auth(url, context_file, browser, user_agent, devtools, log_console):
             interactive=True,
             devtools=devtools,
             browser=browser,
+            browser_args=browser_args,
             user_agent=user_agent,
         )
         context = browser_obj.new_context()

tests/run_examples.sh

@@ -79,6 +79,13 @@ shot-scraper 'https://www.whatismybrowser.com/detect/what-is-my-user-agent/' \
   -o examples/whatismybrowser-firefox.png -h 400 -w 800 -b firefox
 shot-scraper 'https://www.whatismybrowser.com/detect/what-is-my-user-agent/' \
   -o examples/whatismybrowser-webkit.png -h 400 -w 800 -b webkit
+# Default font-render-hinting
+shot-scraper https://shot-scraper.datasette.io/en/stable/screenshots.html \
+  -w 800 -h 600 -o examples/font-hinting-default.png
+# Add browser argument for font-render-hinting
+shot-scraper https://shot-scraper.datasette.io/en/stable/screenshots.html \
+  -w 800 -h 600 -o examples/font-hinting-none.png \
+  --browser-args "--font-render-hinting=none"
 # --wait-for
 echo '<html>
 <body><h1>Here it comes...</h1>