27 |
28 |
29 | Remote Browser is a library for controlling web browsers like Chrome and Firefox programmatically using JavaScript.
30 | You've likely heard of similar browser automation frameworks before, such as [Puppeteer](https://github.com/GoogleChrome/puppeteer) and [Selenium](https://github.com/SeleniumHQ/selenium).
31 | Much 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.
32 | What 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.
33 |
34 | Remote 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).
35 | If you're already familiar with these technologies, then you already know almost everything that you need to use Remote Browser.
36 | If 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.
37 | Be 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.
38 |
39 |
40 | ## Table of Contents
41 |
42 | - [Introduction](#introduction) - A detailed explanation of what Remote Browser is and the core concepts behind the project.
43 | - [Interactive Tour](#interactive-tour)
44 | - [Installation](#installation) - Instructions for installing Remote Browser.
45 | - [Usage Examples](#usage-examples) - Illustrative examples of how Remote Browser can be used.
46 | - [Development](#development) - Instructions for setting up the development environment.
47 | - [Contributing](#contributing) - Guidelines for contributing.
48 | - [License](#license) - License details for the project.
49 |
50 |
51 | ## Introduction
52 |
53 | The core technology that makes Remote Browser possible is the [Web Extensions API](https://developer.mozilla.org/en-US/Add-ons/WebExtensions).
54 | This API is what allows third party browser addons to extend and modify the capabilities of browsers such as Firefox, Chrome, Edge, and Opera.
55 | If you've never written a browser extension before, then you might be surprised at just how powerful this API is.
56 | Creating 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).
57 | The 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.
58 |
59 | Let's take a look at a quick example of how you would navigate to a tab and take a screenshot using Remote Browser.
60 |
61 | ```javascript
62 | import Browser from 'remote-browser';
63 |
64 | (async () => {
65 | // Create and launch a new browser instance.
66 | const browser = new Browser();
67 | await browser.launch();
68 |
69 | // Directly access the Web Extensions API from a remote client.
70 | const tab = await browser.tabs.create({ url: 'https://intoli.com' });
71 | const screenshot = await browser.tabs.captureVisibleTab();
72 | })();
73 | ```
74 |
75 | On the surface, this probably looks pretty similar to examples from other browser automation frameworks.
76 | The 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.
77 |
78 | In a web extension, you would typically interact with the Web Extensions API through a global `browser` object.
79 | You 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.
80 | Remote 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.
81 | The following three calls are actually all exactly equivalent with Remote Browser.
82 |
83 | ```javascript
84 | // Very explicit, we're specifying a function and argument to evaluate in the background page.
85 | await browser.evaluateInBackground(createProperties => (
86 | browser.tabs.create(createProperties)
87 | ), { url: 'https://intoli.com' });
88 |
89 | // A bit of syntactic sugar, we can omit ".evaluateInBackground" and the same thing happens.
90 | await browser(createProperties => (
91 | browser.tabs.create(createProperties)
92 | ), { url: 'https://intoli.com' });
93 |
94 | // A lot of syntactic sugar, the function and explicit argument get constructed automatically.
95 | await browser.tabs.create({ url: 'https://intoli.com' });
96 | ```
97 |
98 | It's mostly immediately clear what's really happening here with the the first `browser.evaluateInBackground()` call.
99 | A function and it's argument are being transmitted to the background script context of a web extension where they're evaluated.
100 | The next two calls just rip out successive layers of boilerplate, but they're doing the exact same thing.
101 |
102 | Similarly, we can evaluate code in the context of a tab in the browser.
103 | The 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.
104 | The following two calls are also exactly equivalent.
105 |
106 | ```javascript
107 | // Evaluate the function in the content script context for the identified by `tab.id`.
108 | await browser.evaluateInContent(tab.id, () => (
109 | document.innerHTML = 'hi!';
110 | ));
111 |
112 | // A shorthand for first accessing a specific tab, and then evaluating code in it.
113 | await browser[tab.id](() => document.body.innerHTML = 'hi!');
114 | ```
115 |
116 | At this point, you've seen nearly all of the syntax that Remote Browser provides.
117 | It 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.
118 |
119 |
120 | ## Interactive Tour
121 |
122 |
123 |
5 |
6 | 
8 |
9 | 
11 |
12 | 
14 | 
20 |
21 | 
23 |
24 | 
26 | 
126 |
127 |