{"id":13394266,"url":"https://github.com/intoli/remote-browser","last_synced_at":"2025-05-15T20:02:12.213Z","repository":{"id":57353191,"uuid":"124411852","full_name":"intoli/remote-browser","owner":"intoli","description":"A low-level browser automation framework built on top of the Web Extensions API standard.","archived":false,"fork":false,"pushed_at":"2018-07-14T22:44:50.000Z","size":9519,"stargazers_count":1735,"open_issues_count":7,"forks_count":105,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-04-01T09:28:26.973Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intoli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-08T15:37:07.000Z","updated_at":"2025-03-27T21:21:04.000Z","dependencies_parsed_at":"2022-09-19T01:01:29.086Z","dependency_job_id":null,"html_url":"https://github.com/intoli/remote-browser","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intoli%2Fremote-browser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intoli%2Fremote-browser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intoli%2Fremote-browser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intoli%2Fremote-browser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intoli","download_url":"https://codeload.github.com/intoli/remote-browser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247819933,"owners_count":21001394,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T17:01:14.313Z","updated_at":"2025-04-08T10:14:29.240Z","avatar_url":"https://github.com/intoli.png","language":"JavaScript","readme":"\u003ch1 vertical-align=\"middle\"\u003eRemote Browser\n    \u003ca targe=\"_blank\" href=\"https://twitter.com/home?status=Remote%20Browser%20%E2%80%93%20A%20browser%20automation%20framework%20based%20on%20the%20Web%20Extensions%20API.%20%40IntoliNow%0A%0Ahttps%3A//github.com/intoli/remote-browser\"\u003e\n        \u003cimg height=\"26px\" src=\"https://simplesharebuttons.com/images/somacro/twitter.png\"\n            alt=\"Tweet\"\u003e\u003c/a\u003e\n    \u003ca target=\"_blank\" href=\"https://www.facebook.com/sharer/sharer.php?u=https%3A//github.com/intoli/remote-browser\"\u003e\n        \u003cimg height=\"26px\" src=\"https://simplesharebuttons.com/images/somacro/facebook.png\"\n            alt=\"Share on Facebook\"\u003e\u003c/a\u003e\n    \u003ca target=\"_blank\" href=\"http://reddit.com/submit?url=https%3A%2F%2Fgithub.com%2Fintoli%2Fremote-browser\u0026title=Remote%20Browser%20%E2%80%93%20A%20browser%20automation%20framework%20based%20on%20the%20Web%20Extensions%20API.\"\u003e\n        \u003cimg height=\"26px\" src=\"https://simplesharebuttons.com/images/somacro/reddit.png\"\n            alt=\"Share on Reddit\"\u003e\u003c/a\u003e\n    \u003ca target=\"_blank\" href=\"https://news.ycombinator.com/submitlink?u=https://github.com/intoli/remote-browser\u0026t=Remote%20Browser%20%E2%80%93%20A%20browser%20automation%20framework%20based%20on%20the%20Web%20Extensions%20API.\"\u003e\n        \u003cimg height=\"26px\" src=\"media/ycombinator.png\"\n            alt=\"Share on Hacker News\"\u003e\u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"left\"\u003e\n    \u003ca href=\"https://circleci.com/gh/intoli/remote-browser/tree/master\"\u003e\n        \u003cimg src=\"https://img.shields.io/circleci/project/github/intoli/remote-browser/master.svg\"\n            alt=\"Build Status\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/intoli/remote-browser/blob/master/LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/License-BSD%202--Clause-blue.svg\"\n            alt=\"License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/remote-browser\"\u003e\n        \u003cimg src=\"https://img.shields.io/npm/v/remote-browser.svg\"\n            alt=\"NPM Version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\nRemote Browser is a library for controlling web browsers like Chrome and Firefox programmatically using JavaScript.\nYou've likely heard of similar browser automation frameworks before, such as [Puppeteer](https://github.com/GoogleChrome/puppeteer) and [Selenium](https://github.com/SeleniumHQ/selenium).\nMuch like these other projects, Remote Browser can be used to accomplish a wide variety of tasks relating to UI testing, Server Side Rendering (SSR), and web scraping.\nWhat makes Remote Browser different from these other libraries is that it's built using standard cross-browser compatible technologies, and its primary goal is to facilitate interactions with existing APIs rather than to create a new one of its own.\n\nRemote Browser provides a minimalistic and lightweight framework for automating browsers using vanilla [JavaScript](https://tc39.github.io/ecma262/), [HTML browsing contexts](https://html.spec.whatwg.org/multipage/window-object.html#the-window-object), and the [Web Extensions API](https://developer.mozilla.org/en-US/Add-ons/WebExtensions).\nIf you're already familiar with these technologies, then you already know almost everything that you need to use Remote Browser.\nIf not, then there are vast learning resources out there, like [The Mozilla Developer Network (MDN)](https://developer.mozilla.org/en-US/docs/Web), which can get you up to speed in no time.\nBe sure to check out the [Introduction](#introduction), the [Interactive Tour](https://intoli.com/tour), and [Usage Examples](#usage-examples) to learn about how Remote Browser makes it easy to use these technologies.\n\n\n## Table of Contents\n\n- [Introduction](#introduction) - A detailed explanation of what Remote Browser is and the core concepts behind the project.\n- [Interactive Tour](#interactive-tour)\n- [Installation](#installation) - Instructions for installing Remote Browser.\n- [Usage Examples](#usage-examples) - Illustrative examples of how Remote Browser can be used.\n- [Development](#development) - Instructions for setting up the development environment.\n- [Contributing](#contributing) - Guidelines for contributing.\n- [License](#license) - License details for the project.\n\n\n## Introduction\n\nThe core technology that makes Remote Browser possible is the [Web Extensions API](https://developer.mozilla.org/en-US/Add-ons/WebExtensions).\nThis API is what allows third party browser addons to extend and modify the capabilities of browsers such as Firefox, Chrome, Edge, and Opera.\nIf you've never written a browser extension before, then you might be surprised at just how powerful this API is.\nCreating tabs and interacting with pages is just the beginning; it's also possible to [intercept and modify network requests/responses](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/webRequest), [create and control containerized sessions within a single browser instance](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/contextualIdentities), [take screenshots](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/captureVisibleTab), and [*much* more](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API).\nThe central idea behind Remote Browser is that there's no need to reinvent the wheel when modern browsers *already* ship with an extremely powerful cross-browser compatible API that's suitable for automation tasks.\n\nLet's take a look at a quick example of how you would navigate to a tab and take a screenshot using Remote Browser.\n\n```javascript\nimport Browser from 'remote-browser';\n\n(async () =\u003e {\n  // Create and launch a new browser instance.\n  const browser = new Browser();\n  await browser.launch();\n\n  // Directly access the Web Extensions API from a remote client.\n  const tab = await browser.tabs.create({ url: 'https://intoli.com' });\n  const screenshot = await browser.tabs.captureVisibleTab();\n})();\n```\n\nOn the surface, this probably looks pretty similar to examples from other browser automation frameworks.\nThe difference is that [browser.tabs.create()](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/create) and [browser.tabs.captureVisibleTab](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/captureVisibleTab) aren't part of the Remote Browser API; they're part of the Web Extensions API.\n\nIn a web extension, you would typically interact with the Web Extensions API through a global `browser` object.\nYou could make a call to `browser.tabs.create()` in your extension's [background script](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/background), and it would create a new tab.\nRemote Browser lets you make this call from the environment where you're running your browser control code as though you were inside of an extension.\nThe following three calls are actually all exactly equivalent with Remote Browser.\n\n```javascript\n// Very explicit, we're specifying a function and argument to evaluate in the background page.\nawait browser.evaluateInBackground(createProperties =\u003e (\n  browser.tabs.create(createProperties)\n), { url: 'https://intoli.com' });\n\n// A bit of syntactic sugar, we can omit \".evaluateInBackground\" and the same thing happens.\nawait browser(createProperties =\u003e (\n  browser.tabs.create(createProperties)\n), { url: 'https://intoli.com' });\n\n// A lot of syntactic sugar, the function and explicit argument get constructed automatically.\nawait browser.tabs.create({ url: 'https://intoli.com' });\n```\n\nIt's mostly immediately clear what's really happening here with the the first `browser.evaluateInBackground()` call.\nA function and it's argument are being transmitted to the background script context of a web extension where they're evaluated.\nThe next two calls just rip out successive layers of boilerplate, but they're doing the exact same thing.\n\nSimilarly, we can evaluate code in the context of a tab in the browser.\nThe syntax here is very similar to how we evaluate code in the background script, we just need to additionally specify which tab we're interested in.\nThe following two calls are also exactly equivalent.\n\n```javascript\n// Evaluate the function in the content script context for the identified by `tab.id`.\nawait browser.evaluateInContent(tab.id, () =\u003e (\n  document.innerHTML = 'hi!';\n));\n\n// A shorthand for first accessing a specific tab, and then evaluating code in it.\nawait browser[tab.id](() =\u003e document.body.innerHTML = 'hi!');\n```\n\nAt this point, you've seen nearly all of the syntax that Remote Browser provides.\nIt makes it really easy to evaluate code in different contexts, and lets you use the browser APIs to control and interact with the browser itself.\n\n\n## Interactive Tour\n\n\n\u003cp align=\"center\"\u003e\n    \u003ca alt=\"A Screenshot of the Tour\" href=\"https://intoli.com/tour\"\u003e\n        \u003cimg width=\"75%\" src=\"media/tour-screenshot.png\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\nYou can learn more about how Remote Browser works in [the interactive tour](https://intoli.com/tour).\nThe tour provides an interactive environment where you can run code examples in your browser without needing to install any software.\nIt expands upon some of the fundamental concepts behind Remote Browser, and demonstrates how the library can be used in real-world scenarios.\n\n\n## Usage Examples\n\n### Connecting to a Running Browser\n\nAll of the browser control code for Remote Browser is implemented as a cross-browser compatible web extension.\nWhen you execute `Browser.launch()`, it simply runs a browser instance with the extension installed and passes it the parameters necessary to connect to the remote client.\nYou can also install this same extension in your day-to-day browser, and tell it to connect to a remote client manually.\nThis can be a very useful debugging tool while you're developing scripts, or as a means to quickly automate simple tasks without needing to create a whole browser extension from scratch.\n\nCalling `Browser.listen()` on a new browser instance will cause it to listen on an open port for a connection from an already running browser.\nIt will return the port that it's listening on, and wait for you to initialize a connection from a browser that has the Remote Browser extension installed.\n\n```javascript\nconst browser = new Browser();\nconst port = await browser.listen();\nconsole.log(`Listening on port: ${port}`);\n```\n\nThe connection can be initiated from within the browser using the Remote Browser extension popup.\nHere's an example of the connection process.\n\n![Connecting the Client to a Live Browser](media/live-connection-demo.gif)\n\nThe browser interactions that we do in this video aren't particularly useful, but you have the full power of Remote Browser at your fingertips once you're connected.\nYou could, for instance, use [web extension alarms](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/alarms) to schedule arbitrary tasks to run in the browser at specified times or intervals.\nThese tasks would be scheduled within the browser itself, so you could configure code to run even after the client has disconnected.\n\n\n## Installation\n\nRemote Browser is available as an [npm package](https://www.npmjs.com/package/remote-browser), and the latest version can be installed by running the following.\n\n```bash\nyarn add remote-browser\n```\n\nIt's possible to use Remote Browser as a client for browser sessions on remote servers, but you'll almost certainly want a local browser installed when you're first getting started.\nWe recommend [installing Firefox](https://www.mozilla.org/firefox), even if it's not your day-to-day browser, because it has a more complete implementation of the Web Extensions API than other browsers.\nIt's additionally set as the default in Remote Browser, so it will allow you to run the usage examples without changing any of the configuration options.\n\n\n## Development\n\nTo get started on development, you simply need to clone the repository and install the project dependencies.\n\n```bash\n# Clone the repository.\ngit clone https://github.com/intoli/remote-browser.git\ncd remote-browser\n\n# Install the dependencies.\nyarn install\n\n# Build the project.\nyarn build\n\n# Run the tests.\nyarn test\n```\n\n## Contributing\n\nContributions are welcome, but please follow these contributor guidelines outlined in [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\n## License\n\nRemote Browser is licensed under a [BSD 2-Clause License](LICENSE) and is copyright [Intoli, LLC](https://intoli.com).\n","funding_links":[],"categories":["JavaScript","📦 Legacy \u0026 Inactive Projects","others","创意 \u003ca name=\"idea\"\u003e\u003c/a\u003e"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintoli%2Fremote-browser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintoli%2Fremote-browser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintoli%2Fremote-browser/lists"}