{"id":16206927,"url":"https://github.com/statewalker/webrun-devtools","last_synced_at":"2025-03-19T07:31:38.406Z","repository":{"id":208447258,"uuid":"721653251","full_name":"statewalker/webrun-devtools","owner":"statewalker","description":"WebRun DevTools is a Chrome extension for browser automation and testing from HTML pages","archived":false,"fork":false,"pushed_at":"2024-02-05T23:14:15.000Z","size":265,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-28T16:41:39.466Z","etag":null,"topics":["automation-testing","chrome-extension"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statewalker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-21T13:57:17.000Z","updated_at":"2023-12-11T06:29:27.000Z","dependencies_parsed_at":"2024-10-27T20:24:11.046Z","dependency_job_id":"56c9af63-b7c8-468c-91af-29a76e0f51dd","html_url":"https://github.com/statewalker/webrun-devtools","commit_stats":null,"previous_names":["statewalker/webrun-devtools"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fwebrun-devtools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fwebrun-devtools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fwebrun-devtools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fwebrun-devtools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statewalker","download_url":"https://codeload.github.com/statewalker/webrun-devtools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243976644,"owners_count":20377693,"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":["automation-testing","chrome-extension"],"created_at":"2024-10-10T10:08:55.787Z","updated_at":"2025-03-19T07:31:38.107Z","avatar_url":"https://github.com/statewalker.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebRun DevTools\n**Pilot Browser from the Browser**\n\nWebRun 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](https://observablehq.com/). \n\nThe 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.\n\nThe API access is safeguarded by a key generated by the extension and never leaves your environment.\n\n## Table Of Content\n\n* [Examples](#examples)\n* [How To Use](#how-to-use)\n  * [TL;DR](#tldr)\n  * [Step 1: Install Extension](#step-1-install-extension)\n  * [Step 2: Generate API Key](#step-2-generate-api-key)\n  * [Step 3: Write Automation Scripts](#step-3-write-automation-scripts)\n* [Build From Sources](#build-from-sources)\n* [Exposed APIs](#exposed-apis)\n\n## Examples\n\n*Note 1: These examples will work only if you have the WebRun DevTools extension already installed and activated in your browser*\n\n* Standalone Examples\n  * [Example 1: Create Screenshot](./examples/01.screenshot.html) ([cdn: Example 1](https://unpkg.com/@statewalker/webrun-devtools/examples/01.screenshot.html))\n  * [Example 2: Create Multiple Screenshots](./examples/02.screenshots-many.html) ([cdn: Example 2](https://unpkg.com/@statewalker/webrun-devtools/examples/02.screenshots-many.html)) \n  * [Example 3: Multiple Screenshots with Chrome Debugger API](./examples/03.screenshots-debugger.html) ([cdn: Example 3](https://unpkg.com/@statewalker/webrun-devtools/examples/03.screenshots-debugger.html)) \n* [Observable \u003e WebRun DevTools](https://observablehq.com/@kotelnikov/webrun-devtools)\n* [Codepen \u003e WebRun DevTools: Create Site Screenshot](https://codepen.io/Mikhail-Kotelnikov/pen/xxMNMJR)\n\n\nSee also the \"[Step 3: Write Automation Scripts](#step-3-write-automation-scripts)\" section.\n\n\n## TL;DR\n\n1. Install Extension:\n  - Zipped File: [webrun-devtools-extension.zip](https://unpkg.com/@statewalker/webrun-devtools/dist/webrun-devtools-extension.zip)\n  - [Chrome Web Store \u003e WebRun DevTools](https://chromewebstore.google.com/detail/webrun-devtools/cfphcdekgckldjfmjajcklchnajkpakf)\n\n3. Generate API Key:\n\n![](./docs/images/generate-api-key.png)\n\n3. Write automation code:\n```js\n// For the latest/local version of the extension:\nimport initDevTools from `https://unpkg.com/@statewalker/webrun-devtools`;\nconst api = await initDevTools({ apiKey: `your_generated_api_key` });\nconst win = await api.windows.create({ ... });\nconst imgUrl = await api.tabs.captureVisibleTab(win.id, ...);\n...\nawait api.windows.remove(win.id);\nawait api.close();\n```\n\n*Note: if you are using the extension installed from the Chrome Marketplace you should use the same client API version:*\n```js\n// For the published extension v0.0.12:\nimport initDevTools from 'https://unpkg.com/@statewalker/webrun-devtools@0.0.12';\n```\n\nYou can check how it works using these Observabe Notebooks: [Observable \u003e WebRun DevTools](https://observablehq.com/@kotelnikov/webrun-devtools)\n\nThe video below shows how to install and use a local extension:\n\n[Video: WebRun DevTools - Introduction](https://github.com/statewalker/webrun-devtools/assets/1032407/22529b0f-6198-4970-9943-749209751665)\n\n## How To Use\n\nBy 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.\n\n1. [Install WebRun DevTools Extension](#step-1-install-extension): Add the extension to your Chrome browser.\n2. [Generate API Key](#step-2-generate-api-key): Get an API key generated by the extension to access internal browser APIs. This key stays within your browser.\n3. [Write Automation Scripts](#step-3-write-automation-scripts): Initialize the provided API with the generated key and write automation scripts in your HTML pages or ObservableHQ notebooks.\n\n### Step 1: Install Extension\n\nTo install a Chrome extension from a local folder, follow these short instructions:\n\n1. *Download the Extension:* Download the prepared extension from CDN (UNPKG: [webrun-devtools-extension.zip](https://unpkg.com/@statewalker/webrun-devtools/dist/webrun-devtools-extension.zip)) and unzip it in a separate folder. \n\n*Note: See how to build the extension from sources in the section [Build From Sources]( #build-from-sources )*\n\n2. *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`.\n\n3. *Enable Developer Mode:* In the top right corner of the Extensions page, toggle on the `Developer mode` switch.\n\n4. *Load Unpacked:* After enabling Developer mode, a few additional options will appear. Click on the `Load unpacked` button.\n\n5. *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).\n\n6. *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.\n\nNow the Chrome extension should be successfully installed from the local folder, and you can use it within your browser.\n\n### Step 2: Generate API Key\n\nOnce 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. \n\nClick on the icon to reveal a popup panel managing the key for internal API access:\n\n![](./docs/images/generate-api-key.png)\n\n### Step 3: Write Automation Scripts\n\n1. *Import the WebRun DevTools Library:* \n\n```js\nimport initDevTools from `path/to/webrun-devtools.js`;\nOR:\nimport initDevTools from `https://unpkg.com/@statewalker/webrun-devtools`;\n```\n\n2. *Initialize the API:*\nMake 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.\n```js\nconst apiKey = `azevajqpn`; // your_generated_api_key\nconst api = await initDevTools({ apiKey });\n```\n*Note:* This operation will rise an exception if the extension is not installed in your browser or your API key is invalid.\n\n3. *Access Functionality via API Object:*\nThe returned API object gives access to browser APIs and allows to perform various automation tasks.\n\n*Note:* See the section \"[Exposed APIs](#exposed-apis)\" for more information\n\n```js\n// Example: Open a new window\nconst win = await api.windows.create({\n    url : `http://example.com`,\n    focused : true,\n    width : 800,\n    height : 600\n  });\n\n// Example: Capture a screenshot\nconst imgUrl = await api.tabs.captureVisibleTab(win.id, {\n  format: `png`\n});\n```\n\nThe following example allows to create a screenshot of any website.\nYou can find the full code of this example here: [./examples/01.screenshot.html](./examples/01.screenshot.html) ([On-line version](https://unpkg.com/browse/@statewalker/webrun-devtools/examples/01.screenshot.html))\n\n```html\n\u003cscript type=`module`\u003e\nimport initDevTools from `https://unpkg.com/@statewalker/webrun-devtools`;\n// OR: \n// import initDevTools from `path/to/webrun-devtools.js`;\n\ncreateScreenshot({\n  // API key generated by the extension\n  apiKey: `your_generated_api_key`,\n  // URL of the site\n  url: `https://www.google.com`,\n  // Container element, where the screenshot should be attached. In this case it is the document body\n  container: document.querySelector(`body`)\n}).catch(console.error);\n\nasync function createScreenshot({\n  apiKey,\n  url,\n  container\n}) {\n  const api = await initDevTools({ apiKey });\n  try {\n    // Open site in a new window\n    const winOptions = { url, focused:true, width:800, height:600 }\n    const win = await api.windows.create(winOptions);\n\n    // Await a little bit while site is loading...\n    await new Promise(resolve =\u003e setTimeout(resolve, 300));\n\n    // Capture a PNG screenshot of the active tab\n    const imgUrl = await api.tabs.captureVisibleTab(win.id, {\n      format: `png`\n    });\n\n    // Create an image\n    const div = document.createElement('div');\n    container.appendChild(div);\n    div.innerHTML = `\u003ca href=`${url}` target=`_blank`\u003e\n      \u003cimg src=`${imgUrl}` style=`max-width: 400px;` /\u003e\n    \u003c/a\u003e`\n\n    // Remove the window\n    await api.windows.remove(win.id);\n\n  } finally {\n    // Cleanup resources and disconnect from the extension\n    await api.close();\n  }\n}\n\u003c/script\u003e\n```\n\n## Build From Sources\n\n```shell\n\u003e git clone https://github.com/statewalker/webrun-devtools.git\n\u003e cd webrun-devtools\n\u003e yarn \n\u003e yarn build\n```\n\nOutput:\n* `/dist/webrun-devtools-extension` - ready to use Chrome extension (see the \"[Step 1: Install Extension](#step-1-install-extension)\" section)\n* `/dist/webrun-devtools.js` - client-side script to import in your HTML pages\n\n## Exposed APIs\n\nThis extension creates a bridge with the client code and the exposes the following subset of the [Chrome Extensions APIs](https://developer.chrome.com/docs/extensions/reference/):\n* [chrome.windows](https://developer.chrome.com/docs/extensions/reference/windows/)\n  - `create`\n  - `get`\n  - `getAll`\n  - `getCurrent`\n  - `getLastFocused`\n  - `remove`\n  - `update`\n  - `onBoundsChanged`,\n  - `onCreated`,\n  - `onFocusChanged`,\n  - `onRemoved`,\n* [chrome.tabs](https://developer.chrome.com/docs/extensions/reference/tabs/):\n  - `captureVisibleTab`\n  - `connect` - not exposed; we can not return ports\n  - `create`\n  - `detectLanguage`\n  - `discard`\n  - `duplicate`\n  - `executeScript` - deprecated; not available\n  - `get`\n  - `getAllInWindow` - deprecated; not available\n  - `getCurrent`\n  - `getSelected` - deprecated; not available\n  - `getZoom`\n  - `getZoomSettings`\n  - `goBack`\n  - `goForward`\n  - `group`\n  - `highlight`\n  - `insertCSS` - deprecated; not available\n  - `move`\n  - `query`\n  - `reload`\n  - `remove`\n  - `removeCSS` - deprecated; not available\n  - `sendMessage`\n  - `sendRequest` - deprecated; not available\n  - `setZoom`\n  - `setZoomSettings`\n  - `ungroup`\n  - `update`\n  - `onActiveChanged` - deprecated; not available\n  - `onActivated`\n  - `onAttached`\n  - `onCreated`\n  - `onDetached`\n  - `onHighlightChanged` - deprecated; not available\n  - `onHighlighted`\n  - `onMoved`\n  - `onRemoved`\n  - `onReplaced`\n  - `onSelectionChanged` - deprecated; not available\n  - `onUpdated`\n  - `onZoomChange`\n* [chrome.debugger](https://developer.chrome.com/docs/extensions/reference/debugger/)\n  - `attach`\n  - `detach` \n  - `sendCommand`\n  - `getTargets`\n  - `onDetach`\n  - `onEvent`\n  - `$once(target, event)` - this additional method allows to await the specified event generated by the debugger\n* `custom` - a namespace to custom functions\n  - `injectScript(target, { func, args = [], type = \"module\" })` - injects scripts in the current target tab\n    - target - id of the target tab\n    - func - code of the async function to inject in the page\n    - args - list of arguments transferred in the function\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatewalker%2Fwebrun-devtools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatewalker%2Fwebrun-devtools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatewalker%2Fwebrun-devtools/lists"}