JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 52
  • Score
    100M100P100Q66686F
  • License MIT

Puppeteer alternative for Chrome extensions. A module for Chrome extensions that functions similarly to Puppeteer.

Package Exports

  • browser-automator
  • browser-automator/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (browser-automator) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

browser-automator
NPM Version Publish Size Downloads License: MIT

Puppeteer alternative for Chrome extensions.

Whether you are developing a Chrome extension or need to automate tasks in your favorite Chrome extension, browser-automator offers a Puppeteer-like experience tailored for Chrome extensions. It provides a simple and efficient way to interact with Chrome browser pages. It allows you to control the browser programmatically. Perfect for Chrome extension-based web scraping and automation purposes.

Table of Contents

Install

npm i browser-automator

Usage

A minimal example to automate Goolge search:

import automator from 'browser-automator'

const browser = automator.launch()
const page = await browser.newPage()

await page.goto('https://www.google.com')
await page.waitForSelector('textarea[type="search"]')
await page.input('textarea[type="search"]', 'Who owns Google?')
await page.click('input[type="submit"]')

await page.waitForSelector('[class*="header"]')
const result = await page.evaluate((selector) => {
    return document.querySelector(selector)?.innerText?.trim()
}, ['div[class*="header"]'])
console.log(result)

API Reference

Namespace: automator

A namespace that provides functions for launching the browser automation process.

  • launch(): Browser

    Launches a new Browser instance for browser automation.

    • Returns: A new Browser instance for browser automation.

Class: Page

Represents a Page instance for interacting with Chrome browser pages.

Properties

  • tabId (number) - The ID of the Chrome tab.
  • windowId (number) - The ID of the Chrome window.
  • tryLimit (number) - The maximum number of attempts for waiting operations. Default: 50.
  • delay (number) - The delay between attempts in milliseconds. Default: 750.
  • onBeforeClose (Function) - Callback function to be executed before closing the page.

Constructor

  • constructor(options: { tabId: number; windowId: number })

    Creates a new Page instance for a specific Chrome tab with the given tabId and windowId.

    • options (Object)
      • tabId (number) - The unique identifier of the Chrome tab associated with this Page instance.
      • windowId (number) - The unique identifier of the Chrome window containing the tab.

Methods

  • goto(url: string, options?: { waitUntil: 'load' | 'domcontentloaded' }): Promise<void>

    Navigate to the specified URL.

    • url (string) - The URL to navigate to.
    • options (Object, optional)
      • waitUntil (string) - When to consider navigation as complete ('load' or 'domcontentloaded'). Default: 'domcontentloaded'.

  • reload(): Promise<void>

    Reloads the current page.

  • url(): Promise<string>

    Get the current URL of the page.

  • close(): Promise<void>

    Close the current page.

  • zoom(zoomFactor: number): Promise<void>

    Zoom the current page.

    • zoomFactor (number) - The new zoom factor. Use a value of 0 here to set the tab to its current default zoom factor. Values greater than zero specify a (possibly non-default) zoom factor for the tab.

  • bringToFront(): Promise<void>

    Brings the Chrome browser window associated with the page to the front.

  • hideFromFront(): Promise<void>

    Hides the Chrome browser window associated with the page.

  • evaluate(options: object): Promise<any>

    Evaluates JavaScript code on the page.

    • options (Object)
      • func (Function, optional) - The function to evaluate.
      • files (string[], optional) - An array of script file paths to evaluate.
      • args (any[], optional) - Arguments to pass to the evaluated function.
      • world ('ISOLATED' | 'MAIN', optional) - The world context for evaluation (default is 'MAIN').
      • allFrames (boolean, optional) - Indicates whether to evaluate in all frames (default is false).
      • frameIds (number[], optional) - An array of frame identifiers where the evaluation should take place.
      • documentIds (string[], optional) - An array of document identifiers for the frames to evaluate in.

  • evaluate(func: Function, args?: any[], options?: object): Promise<any>

    Evaluates a function on the page.

    • func (Function) - The function to evaluate.
    • args (any[], optional) - Arguments to pass to the function.
    • options (Object, optional)
      • world ('ISOLATED' | 'MAIN') - The world context for evaluation (default is 'MAIN').
      • allFrames (boolean) - Indicates whether to evaluate in all frames (default is false).
      • frameIds (number[]) - An array of frame identifiers where the evaluation should take place.
      • documentIds (string[]) - An array of document identifiers for the frames to evaluate in.

  • evaluate(files: string[], args?: any[], options?: object): Promise<any>

    Evaluates JS files on the page.

    • files (string[]) - An array of script file paths to evaluate.
    • args (any[], optional) - Arguments to pass to the function.
    • options (Object, optional)
      • world ('ISOLATED' | 'MAIN') - The world context for evaluation (default is 'MAIN').
      • allFrames (boolean) - Indicates whether to evaluate in all frames (default is false).
      • frameIds (number[]) - An array of frame identifiers where the evaluation should take place.
      • documentIds (string[]) - An array of document identifiers for the frames to evaluate in.

  • waitFor(func: Function, args: any[], options?: { tryLimit?: number; delay?: number }): Promise<any>

    Waits for a function to return a truthy value.

    • func (Function) - The function representing the condition to wait for.
    • args (any[]) - Arguments to pass to the function.
    • options (Object, optional)
      • tryLimit (number) - The maximum number of attempts to wait for the condition (default is this.tryLimit).
      • delay (number) - The delay in milliseconds between attempts (default is this.delay).

  • waitForNavigation(options?: { tryLimit?: number; delay?: number }): Promise<void>

    Waits for the page to navigate to a new URL.

    • options (Object, optional)
      • tryLimit (number) - The maximum number of attempts to wait for navigation (default is 50).
      • delay (number) - The delay between each attempt in milliseconds (default is 750).

  • waitForSelector(selectors: string, options?: { tryLimit?: number; delay?: number }, index: number = -1): Promise<void>

    Waits for an element matching the given CSS selector to become available.

    • selectors (string) - The CSS selector to wait for.
    • options (Object, optional)
      • tryLimit (number) - The maximum number of attempts to find the element (default is 1000).
      • delay (number) - The delay between attempts in milliseconds (default is 750).
    • index (number, optional) - The index of the element if multiple elements match the selector.

  • waitForSelectorMiss(selectors: string, options?: { tryLimit?: number; delay?: number }, index: number = -1): Promise<void>

    Waits for an element matching the given selector to disappear from the page.

    • selectors (string) - The CSS selector or XPath expression to check for element absence.
    • options (Object, optional)
      • tryLimit (number) - The maximum number of attempts (default is 1000).
      • delay (number) - The delay in milliseconds between attempts (default is 750ms).
    • index (number, optional) - The index of the element if there are multiple matches.

  • waitForXPath(expression: any, options?: { tryLimit?: number; delay?: number }, index: number = -1): Promise<void>

    Waits for an element matching the given XPath expression to appear in the page.

    • expression (any) - The XPath expression to wait for.
    • options (Object, optional)
      • tryLimit (number) - The maximum number of attempts to find the element (default is 1000).
      • delay (number) - The delay in milliseconds between attempts (default is 750ms).
    • index (number, optional) - The index of the element to interact with.

  • elementExists(selectors: string, index: number = -1): Promise<boolean>

    Checks if an element specified by the CSS selector or XPath expression exists on the page.

    • selectors (string) - The CSS selector or XPath expression to check for existence.
    • index (number) - The index of the element to check.

  • click(selectors: string, index: number = -1): Promise<void>

    Clicks on the element specified by the CSS selector or XPath expression.

    • selectors (string) - The CSS selector or XPath expression to click on.
    • index (number) - The index of the element to interact with.

  • execCopy(text: string): void

    Copies text to the clipboard.

    • text (string) - The text to copy to the clipboard.

  • execPaste(selectors: string, index: number = -1): Promise<void>

    Pastes text from the clipboard to an element specified by the CSS selector or XPath expression.

    • selectors (string) - The CSS selector or XPath expression of the target element.
    • index (number) - The index of the element to interact with (default is -1).

  • triggerEvent(selectors: string, type: any, index: number = -1): Promise<void>

    Triggers an event on the element specified by the CSS selector or XPath expression.

    • selectors (string) - The CSS selector or XPath expression of the target element.
    • type (string) - The type of event to trigger.
    • index (number) - The index of the element to interact with.

  • input(selectors: string, value: any, index: number = -1): Promise<void>

    Inputs a value into the element specified by the CSS selector or XPath expression.

    • selectors (string) - The CSS selector or XPath expression of the target element.
    • value (any) - The value to input.
    • index (number) - The index of the element to interact with.

  • uploadFiles(files: (File | { name: string, blob: Blob, dataUrl?: string, blobUrl?: string } | any)[], selectors: string, caughtElementIndex: number): Promise<void>

    Uploads files to an input element specified by the CSS selector or XPath expression.

    • files (Array) - An array of files to upload, where each file can be a File object or an object with name, blob, dataUrl, and blobUrl properties.
    • selectors (string) - The CSS selector or XPath expression of the input element.
    • caughtElementIndex (number) - The index of the element to interact with (default is -1).

  • screenshot(options: { clip?: { x: number; y: number; width: number; height: number } }): Promise<string>

    Takes a screenshot of the visible area of the page.

    • options (Object, optional)
      • clip (Object) - Optional clipping parameters.

Class: Browser

Represents a Browser instance for interacting with Chrome browser pages.

Properties

  • availablePages (Page[]) - An array of available Page instances within the browser.
  • onPageAdded (Function) - A callback function that is invoked when a new page is added to the browser.
  • onPageCloseListener (Function) - A function to listen for page close events.

Constructor

  • constructor()

    Creates a new Browser instance.

Methods

  • newPage({ tabId, windowId, originWindowId, activeInOrigin, windowOptions, tabOptions }): Promise<Page>

    Creates a new Page instance and associates it with the browser.

    • tabId (number, optional) - The ID of the tab to use for creating the Page instance. If not supplied, a tab will be created.

    • windowId (number, optional) - The ID of the window to open the page in. If not supplied, a window will be created.

    • originWindowId (number, optional) - The ID of the tab's origin window (if any).

    • activeInOrigin (boolean, optional) - Whether the page should be active in the origin window.

    • windowOptions (chrome.windows.CreateData, optional) - Options for creating the window.

    • tabOptions (chrome.tabs.CreateProperties | chrome.tabs.UpdateProperties, optional) - Options for creating or updating the tab.

    • Returns: A Promise that resolves with the new Page instance.

  • pages(): Page[]

    Returns an array of available Page instances.

    • Returns: An array of available Page instances.

  • onPageClose(closedTabId: number)

    Event listener for page close events.

    • closedTabId (number) - The ID of the closed tab.

  • close(): Promise<void>

    Closes all associated pages in the Browser instance.

Contributing

You are welcome to contribute! If you are adding a feature or fixing a bug, please contribute to the GitHub repository.

License

browser-automator is licensed under the MIT license.

Author

@SheikhAminul
@SheikhAminul