WebRun DevTools

Pilot Browser from the Browser

WebRun DevTools is a Chrome browser extension that empowers developers to seamlessly write browser automation and testing scripts directly within HTML pages or notebooks, like ObservableHQ.

The API library interacts with the extension and provides access to the same features as standalone tools like Playwright or Selenium without the overhead of heavyweight external installations in NodeJS environment.

The API access is safeguarded by a key generated by the extension and never leaves your environment.

Examples

Note 1: These examples will work only if you have the WebRun DevTools extension already installed and activated in your browser

See also the "Step 3: Write Automation Scripts" section.

TL;DR

Install Extension:

Zipped File: webrun-devtools-extension.zip
Chrome Web Store > WebRun DevTools

Generate API Key:

Write automation code:

// For the latest/local version of the extension:
import initDevTools from `https://unpkg.com/@statewalker/webrun-devtools`;
const api = await initDevTools({ apiKey: `your_generated_api_key` });
const win = await api.windows.create({ ... });
const imgUrl = await api.tabs.captureVisibleTab(win.id, ...);
...
await api.windows.remove(win.id);
await api.close();

Note: if you are using the extension installed from the Chrome Marketplace you should use the same client API version:

// For the published extension v0.0.12:
import initDevTools from 'https://unpkg.com/@statewalker/webrun-devtools@0.0.12';

You can check how it works using these Observabe Notebooks: Observable > WebRun DevTools

The video below shows how to install and use a local extension:

Video: WebRun DevTools - Introduction

How To Use

By following steps described below, you can seamlessly integrate the WebRun DevTools library into your HTML or notebook environment, establish a connection with the extension using the generated API key, and access various automation functionalities tailored to the specified access level.

Install WebRun DevTools Extension: Add the extension to your Chrome browser.
Generate API Key: Get an API key generated by the extension to access internal browser APIs. This key stays within your browser.
Write Automation Scripts: Initialize the provided API with the generated key and write automation scripts in your HTML pages or ObservableHQ notebooks.

Step 1: Install Extension

To install a Chrome extension from a local folder, follow these short instructions:

Download the Extension: Download the prepared extension from CDN (UNPKG: webrun-devtools-extension.zip) and unzip it in a separate folder.

Note: See how to build the extension from sources in the section Build From Sources

Access Chrome Extensions: Open the Google Chrome browser and go to the Extensions page. You can do this by typing chrome://extensions/ in the address bar and pressing Enter.
Enable Developer Mode: In the top right corner of the Extensions page, toggle on the Developer mode switch.
Load Unpacked: After enabling Developer mode, a few additional options will appear. Click on the Load unpacked button.
Select Extension Folder: A file dialog will open. Navigate to the folder where you downloaded the extension files, select the folder, and click Select Folder (or equivalent).
Verify Installation: The extension should now appear in the list of installed extensions. Ensure that it is enabled by toggling the switch next to its name.

Now the Chrome extension should be successfully installed from the local folder, and you can use it within your browser.

Step 2: Generate API Key

Once the extension is enabled, you can pin its icon to the Chrome toolbar for quick access: right-click on the extension icon within the Extensions page, and select Show in toolbar or a similar option. This will place the extension icon in your browser's toolbar for easy access. Now, the pinned extension icon on the toolbar gives access to the key generation UI.

Click on the icon to reveal a popup panel managing the key for internal API access:

Step 3: Write Automation Scripts

Import the WebRun DevTools Library:

import initDevTools from `path/to/webrun-devtools.js`;
OR:
import initDevTools from `https://unpkg.com/@statewalker/webrun-devtools`;

Initialize the API: Make the initial call to the imported function, passing the generated API key as an argument. This call establishes the connection with the WebRun DevTools extension, validate the API key and returns an API object.

const apiKey = `azevajqpn`; // your_generated_api_key
const api = await initDevTools({ apiKey });

Note: This operation will rise an exception if the extension is not installed in your browser or your API key is invalid.

Access Functionality via API Object: The returned API object gives access to browser APIs and allows to perform various automation tasks.

Note: See the section "Exposed APIs" for more information

// Example: Open a new window
const win = await api.windows.create({
    url : `http://example.com`,
    focused : true,
    width : 800,
    height : 600
  });

// Example: Capture a screenshot
const imgUrl = await api.tabs.captureVisibleTab(win.id, {
  format: `png`
});

The following example allows to create a screenshot of any website. You can find the full code of this example here: ./examples/01.screenshot.html (On-line version)

<script type=`module`>
import initDevTools from `https://unpkg.com/@statewalker/webrun-devtools`;
// OR: 
// import initDevTools from `path/to/webrun-devtools.js`;

createScreenshot({
  // API key generated by the extension
  apiKey: `your_generated_api_key`,
  // URL of the site
  url: `https://www.google.com`,
  // Container element, where the screenshot should be attached. In this case it is the document body
  container: document.querySelector(`body`)
}).catch(console.error);

async function createScreenshot({
  apiKey,
  url,
  container
}) {
  const api = await initDevTools({ apiKey });
  try {
    // Open site in a new window
    const winOptions = { url, focused:true, width:800, height:600 }
    const win = await api.windows.create(winOptions);

    // Await a little bit while site is loading...
    await new Promise(resolve => setTimeout(resolve, 300));

    // Capture a PNG screenshot of the active tab
    const imgUrl = await api.tabs.captureVisibleTab(win.id, {
      format: `png`
    });

    // Create an image
    const div = document.createElement('div');
    container.appendChild(div);
    div.innerHTML = `<a href=`${url}` target=`_blank`>
      <img src=`${imgUrl}` style=`max-width: 400px;` />
    </a>`

    // Remove the window
    await api.windows.remove(win.id);

  } finally {
    // Cleanup resources and disconnect from the extension
    await api.close();
  }
}
</script>

Build From Sources

> git clone https://github.com/statewalker/webrun-devtools.git
> cd webrun-devtools
> yarn 
> yarn build

Output:

/dist/webrun-devtools-extension - ready to use Chrome extension (see the "Step 1: Install Extension" section)
/dist/webrun-devtools.js - client-side script to import in your HTML pages

Exposed APIs

This extension creates a bridge with the client code and the exposes the following subset of the Chrome Extensions APIs:

chrome.windows
- create
- get
- getAll
- getCurrent
- getLastFocused
- remove
- update
- onBoundsChanged,
- onCreated,
- onFocusChanged,
- onRemoved,
chrome.tabs:
- captureVisibleTab
- connect - not exposed; we can not return ports
- create
- detectLanguage
- discard
- duplicate
- executeScript - deprecated; not available
- get
- getAllInWindow - deprecated; not available
- getCurrent
- getSelected - deprecated; not available
- getZoom
- getZoomSettings
- goBack
- goForward
- group
- highlight
- insertCSS - deprecated; not available
- move
- query
- reload
- remove
- removeCSS - deprecated; not available
- sendMessage
- sendRequest - deprecated; not available
- setZoom
- setZoomSettings
- ungroup
- update
- onActiveChanged - deprecated; not available
- onActivated
- onAttached
- onCreated
- onDetached
- onHighlightChanged - deprecated; not available
- onHighlighted
- onMoved
- onRemoved
- onReplaced
- onSelectionChanged - deprecated; not available
- onUpdated
- onZoomChange
chrome.debugger
- attach
- detach
- sendCommand
- getTargets
- onDetach
- onEvent
- $once(target, event) - this additional method allows to await the specified event generated by the debugger
custom - a namespace to custom functions
- injectScript(target, { func, args = [], type = "module" }) - injects scripts in the current target tab
  - target - id of the target tab
  - func - code of the async function to inject in the page
  - args - list of arguments transferred in the function

@statewalker/webrun-devtools

WebRun DevTools

Table Of Content

Examples

TL;DR

How To Use

Step 1: Install Extension

Step 2: Generate API Key

Step 3: Write Automation Scripts

Build From Sources

Exposed APIs

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@statewalker/webrun-devtools

WebRun DevTools

Table Of Content

Examples

TL;DR

How To Use

Step 1: Install Extension

Step 2: Generate API Key

Step 3: Write Automation Scripts

Build From Sources

Exposed APIs

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads