webext-agent v0.2.0
webext-agent
The webext-agent is a browser extension that enables remote access to WebExtensions APIs. It helps you for automating browser integration and testing.
Installation
Install by npm:
$ npm install --save webext-agent # npm
$ yarn add webext-agent # yarn
$ pnpx webext-agent install # pnpm
Preparation
The webext-agent access the browser via native messaging. It requires a native messaging manifest to be installed to the local. The webext-agent does not install the manifest automatically due to the security reason. You can install it manually by the following command:
$ webext-agent install --addon-ids my-addon1@example.com,my-addon2@example.com,...
Quick start
Create a new agent add-on:
$ webext-agent create-addon \
--additional-permissions tabs \
--addon-id my-addon@example.com
/tmp/my-agent-addon
and load it via about:config
on your Firefox browser.
The agent server starts and you can access APIs by the following JavaScript/TypeScript:
const { connect } = require("webext-agent");
(async () => {
const browser = await connect("my-addon@example.com");
const tabs = await browser.tabs.query({});
tabs.forEach((tab) => {
console.log("[%d] %s - %s", tab.id, tab.title, tab.url)
})
})();
CLI
install
Install a native messaging manifest to the local
$ webext-agent install --addon-ids my-addon1@example.com,my-addon2@example.com,...
uninstall
Uninstall the installed native messaging manifest from the local.
$ webext-agent uninstall
check
Check if the native message manifest is installed.
$ webext-agent install
create-addon
Create a new agent add-on.
$ webext-agent create-addon \
--additional-permissions <permission1>,<permission2>,... \
--addon-id <addon-id> \
[--base-addon <base-addon>] \
<destination>
You can mix-in an agent add-on with your add-ons by --base-addon
option.
This is useful to debug or access the internal storage on your add-on.
JavaScript/TypeScript API
webext-agent also provides programmatic APIs.
createAgentAddon(destination, options)
destination
Destination directory to create an agent add-on.options
additionalPermissions
Additional permissions to be added to the add-on.
import { createAgentAddon } from "webext-agent";
const addon = await createAgentAddon("/tmp/my-agent-addon");
console.log(addon.getRoot());
createMixedInAgentAddon(baseAddon, destination, options)
baseAddon
The directory location containing a base add-on.destination
Destination directory to create an agent add-on.options
additionalPermissions
Additional permissions to be added to the add-on.addonId
An id of the Addon
import { createMixedInAgentAddon } from "webext-agent";
const addon = await createMixedInAgentAddon("path/to/your/addon", "/tmp/my-new-addon");
console.log(addon.getRoot());
connect()
address
The address and port the client connect to,address:port
in a string, or in a object containingaddress
in a string andport
in a number.
import { connect } from "webext-agent";
const browser = await connect("127.0.0.1:12345");
const tabs = await browser.tabs.query({});
console.log(tabs);
LICENSE
MIT