Home

Awesome

Beachpatrol: Browser's End-user Automation CLI Hub. Potentialize All Tasks Regarding Online Life.

<p align="center"> <img src="https://github.com/sebastiancarlos/beachpatrol/assets/88276600/49fbdf4f-eeec-42f8-a0aa-dd1c1c6c1617"> </p>

Essential software should be fully automatable. Web browsers aren't. Let's change that.

Introduction

Beachpatrol is a CLI tool to replace and automate your everyday web browser.

https://github.com/sebastiancarlos/beachpatrol/assets/88276600/bc3bf9e8-28e2-48ef-a1f4-8754b4918916

Run beachpatrol to launch a Chromium or Firefox browser which can be controlled externally through Playwright scripts. You can use it as your daily driver; it works like a regular browser.

Use also beachpatrol --profile <profile-name> to launch a specific profile, or beachpatrol --incognito.

To automate it, create a custom Playwright script in the beachpatrol/commands folder. Then, run beachmsg <script-name> [<argument>...]. It will run your script by default on the currently focused tab, but you can use the Playwright API to move to an existing tab, open a new one, or use a headless tab instead.

If you don't want to go back and forth to the CLI to automate your browser, you can install the beachpatrol-browser-extension. Its UI allows you to select a command and call it with arguments. It will call beachmsg itself through the browser extension's Native Messaging feature. Also, the UI will highlight commands which are meant to run on the current URL, will provide GUI elements for common situations (such as pagination and dropdowns), and will support hotkeys:

image

What can you automate with Beachpatrol? The sky is the limit:

Requirements

Installation

Example

Technical details

First and foremost, beachpatrol contains a customized Playwright script to launch your browser. It passes arguments which closely recreate the experience of using a non-automated browser. For example, it does not set a fixed viewport (which is, otherwise, a sensible default for Playwright's main use-case of automated testing.)

Beachpatrol also installs and loads the packages playwright-extra and puppeteer-extra-plugin-stealth. This is needed to hide the fact that the browser is automated, which in turn is needed for basic features such as Google Sign-in.

Naturally, the above package is tangentially related to a cat-and-mouse game between web-scrapers and web-masters. As such, it might stop working at any time. Beachpatrol guarantees to find new automation-hiding techniques if that happens. Beachpatrol also encourages users to respect every website's terms and conditions.

After the browser is launched, it listens on a UNIX socket created on /tmp/beachpatrol.sock for messages by beachmsg.

Usage

Usage: beachpatrol [--profile <profile_name>] [--incognito] [--headless]

Launches a browser with the specified profile.
Opens a socket to listen for commands. Commands can be sent with
the 'beachmsg' command.

Options:
  --profile <profile_name>  Use the specified profile. Default: default
  --browser <browser_name>  Use the specified browser. Default: chromium
      Supported browsers: chromium, firefox
  --incognito               Launch browser in incognito mode
  --headless                Launch browser in headless mode
Usage: beachmsg <command> [<arg>...]

Send commands to beachpatrol. The provided command must exist
in the commands directory of beachpatrol.

F.A.Q.

Isn't the claim that web browsers aren't automatable a bit far-fetched?

When we say that web browsers aren't automatable, we're thinking more along the lines of the depth of automation available with tools like Bash, Vim or Emacs (where virtually every interaction can be scripted and interwoven into custom workflows without much resistance.)

Yes, we acknowledge there are existing ways to automate browser tasks like autofill, mouse and keyboard macros, bookmarklets, extensions, and of course various tools like Playwright.

Beachpatrol aspires to bring a new spin to the state-of-the-art, re-imagining automation tools not as a one-time task, but integrated into your daily browser. Just as your favorite shell or extendable text editor.

In short, our aim is to take existing automation tools (currently designed for testing or scraping) and tweak them for everyday browsing, while also providing a UI which is both simple and power-user friendly.

But what’s the point? Isn’t Beachpatrol just a wrapper around a Playwright browser?

True, but it offers several value-added features:

Why Playwright instead of Selenium?

Initial browser launch benchmarks suggested us to prioritize Playwright.

BrowserLaunch time
Playwright Chrome1.7s
Selenium Node Chrome1.8s
Selenium Java Chrome4s
Playwright Firefox4.3s
Selenium Java Firefox6s
Selenium Node Firefox9s

Why JavaScript/Node.js instead of Python?

While Python is a popular language for web automation, we decided for JavaScript to enable code sharing with the browser extension.

Why use an external automation tool (Playwright) instead of a browser extension?

Similar functionality can indeed be achieved with Userscript managers, such as the Violentmonkey browser extension.

But, while Beachpatrol allows us to control the browser from both the OS and a browser extension, our priority is the OS. Also, there are limitations on how much you can interact with the OS from a browser extension. Therefore, something like Playwright was the natural choice.

Furthermore, while controlling the browser from an extension is possible, Manifest v3 removed the ability to execute third-party strings of code. Popular automation extensions like Greasemonkey and Tampermonkey could also be affected by Manifest v3. The alternative is to embed the code into the extension, but that would require re-bundling the extensions after every change. Other tricks do exist to make this approach work, and there is some hope for future Manifest v3 solutions, but this path is certainly tricky.

It is more likely that Selenium and related tools will continue to work in the foreseeable future given the business demand for traditional browser testing.

How does Beachpatrol compare to bookmarklets for quick tasks?

Bookmarklets are handy for executing scripts with a click, but they are limited to user-triggered actions and may not handle complex workflows, such as automation based on specific timing or interaction with operating system features.

Plus, there's a personal preference factor. For those who like to have finer control, keeping automation scripts within their file system feels cleaner and less bound to a particular browser ecosystem. However, we recognize that bookmarklets have their place and can be the preferred choice for many users.

Writing Playwright scripts for every task takes too long.

You can use Chromium DevDool's Recorder tab to record actions and export them as Puppeteer scripts, which use the same API as Playwright.

Also, given Playwright's popularity, you can describe your task in natural language to an AI and ask for it as a Playwright script. With some practice, this should get you halfway to a working script.

Project Status

This project is in alpha.

You might also like

License

MIT

Contributing

We welcome contributions of all kinds. If you have a suggestion or fix, please feel free to open an issue or pull request.