{"id":21055189,"url":"https://github.com/sheikhaminul/browser-automator","last_synced_at":"2025-08-14T07:43:32.218Z","repository":{"id":206137099,"uuid":"600853007","full_name":"SheikhAminul/browser-automator","owner":"SheikhAminul","description":"Puppeteer alternative for Chrome extensions.","archived":false,"fork":false,"pushed_at":"2025-06-17T18:33:28.000Z","size":57,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-09T02:46:11.059Z","etag":null,"topics":["automated-testing","automation","browser","browser-automation","browser-extension","chrome","puppeteer","web-scraping"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/browser-automator","language":"TypeScript","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/SheikhAminul.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,"zenodo":null}},"created_at":"2023-02-12T19:38:02.000Z","updated_at":"2025-06-17T18:33:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"825d7243-d2a0-4112-bbfe-73e6a1ad7bf4","html_url":"https://github.com/SheikhAminul/browser-automator","commit_stats":null,"previous_names":["sheikhaminul/browser-automator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SheikhAminul/browser-automator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SheikhAminul%2Fbrowser-automator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SheikhAminul%2Fbrowser-automator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SheikhAminul%2Fbrowser-automator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SheikhAminul%2Fbrowser-automator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SheikhAminul","download_url":"https://codeload.github.com/SheikhAminul/browser-automator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SheikhAminul%2Fbrowser-automator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270385016,"owners_count":24574537,"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","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["automated-testing","automation","browser","browser-automation","browser-extension","chrome","puppeteer","web-scraping"],"created_at":"2024-11-19T16:36:55.187Z","updated_at":"2025-08-14T07:43:32.188Z","avatar_url":"https://github.com/SheikhAminul.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"browser-automator\u003cbr\u003e\n[![NPM Version](https://img.shields.io/npm/v/browser-automator.svg?branch=main)](https://www.npmjs.com/package/browser-automator)\n[![Publish Size](https://badgen.net/packagephobia/publish/browser-automator)](https://packagephobia.now.sh/result?p=browser-automator)\n[![Downloads](https://img.shields.io/npm/dt/browser-automator)](https://www.npmjs.com/package/browser-automator)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/SheikhAminul/browser-automator/blob/main/LICENSE)\n================\n\n### Puppeteer alternative for Chrome extensions.\nWhether 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.\n\n\n## Table of Contents\n\n*   [Install](#install)\n*   [Usage](#usage)\n*   [API Reference](#api-reference)\n*   [Contributing](#contributing)\n*   [License](#license)\n*   [Author](#author)\n\n\n## Install\n\n```plaintext\nnpm i browser-automator\n```\n\n\n## Usage\n\nA minimal example to automate Goolge search:\n\n```javascript\nimport automator from 'browser-automator'\n\nconst browser = automator.launch()\nconst page = await browser.newPage()\n\nawait page.goto('https://www.google.com')\nawait page.waitForSelector('textarea[type=\"search\"]')\nawait page.input('textarea[type=\"search\"]', 'Who owns Google?')\nawait page.click('input[type=\"submit\"]')\n\nawait page.waitForSelector('[class*=\"header\"]')\nconst result = await page.evaluate((selector) =\u003e {\n\treturn document.querySelector(selector)?.innerText?.trim()\n}, ['div[class*=\"header\"]'])\nconsole.log(result)\n```\n\n## API Reference\n\n### Namespace: `automator`\n\nA namespace that provides functions for launching the browser automation process.\n\n- `launch(): Browser`\n\n  Launches a new Browser instance for browser automation.\n\n  - Returns: A new Browser instance for browser automation.\n\n\n### Class: `Page`\n\nRepresents a Page instance for interacting with Chrome browser pages.\n\n#### Properties\n\n- `tabId` (number) - The ID of the Chrome tab.\n- `windowId` (number) - The ID of the Chrome window.\n- `tryLimit` (number) - The maximum number of attempts for waiting operations. Default: 50.\n- `delay` (number) - The delay between attempts in milliseconds. Default: 750.\n- `onBeforeClose` (Function) - Callback function to be executed before closing the page.\n\n#### Constructor\n\n* #### `constructor(options: { tabId: number; windowId: number })`\n\n  Creates a new Page instance for a specific Chrome tab with the given `tabId` and `windowId`.\n\n  - `options` (Object)\n    - `tabId` (number) - The unique identifier of the Chrome tab associated with this Page instance.\n    - `windowId` (number) - The unique identifier of the Chrome window containing the tab.\n\n#### Methods\n\n* #### `goto(url: string, options?: { waitUntil: 'load' | 'domcontentloaded' }): Promise\u003cvoid\u003e`\n\n  Navigate to the specified URL.\n\n  - `url` (string) - The URL to navigate to.\n  - `options` (Object, optional)\n    - `waitUntil` (string) - When to consider navigation as complete ('load' or 'domcontentloaded'). Default: 'domcontentloaded'.\n\n* #### `reload(): Promise\u003cvoid\u003e`\n\n  Reloads the current page.\n\n* #### `url(): Promise\u003cstring\u003e`\n\n  Get the current URL of the page.\n\n* #### `close(): Promise\u003cvoid\u003e`\n\n  Close the current page.\n\n* #### `zoom(zoomFactor: number): Promise\u003cvoid\u003e`\n\n  Zoom the current page.\n\n  - `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.\n\n* #### `bringToFront(): Promise\u003cvoid\u003e`\n\n  Brings the Chrome browser window associated with the page to the front.\n\n* #### `hideFromFront(): Promise\u003cvoid\u003e`\n\n  Hides the Chrome browser window associated with the page.\n\n* #### `evaluate(options: object): Promise\u003cany\u003e`\n\n  Evaluates JavaScript code on the page.\n\n  - `options` (Object)\n    - `func` (Function, optional) - The function to evaluate.\n    - `files` (string[], optional) - An array of script file paths to evaluate.\n    - `args` (any[], optional) - Arguments to pass to the evaluated function.\n    - `world` ('ISOLATED' | 'MAIN', optional) - The world context for evaluation (default is 'MAIN').\n    - `allFrames` (boolean, optional) - Indicates whether to evaluate in all frames (default is false).\n    - `frameIds` (number[], optional) - An array of frame identifiers where the evaluation should take place.\n    - `documentIds` (string[], optional) - An array of document identifiers for the frames to evaluate in.\n\n* #### `evaluate(func: Function, args?: any[], options?: object): Promise\u003cany\u003e`\n\n  Evaluates a function on the page.\n\n  - `func` (Function) - The function to evaluate.\n  - `args` (any[], optional) - Arguments to pass to the function.\n  - `options` (Object, optional)\n    - `world` ('ISOLATED' | 'MAIN') - The world context for evaluation (default is 'MAIN').\n    - `allFrames` (boolean) - Indicates whether to evaluate in all frames (default is false).\n    - `frameIds` (number[]) - An array of frame identifiers where the evaluation should take place.\n    - `documentIds` (string[]) - An array of document identifiers for the frames to evaluate in.\n\n* #### `evaluate(files: string[], args?: any[], options?: object): Promise\u003cany\u003e`\n\n  Evaluates JS files on the page.\n\n  - `files` (string[]) - An array of script file paths to evaluate.\n  - `args` (any[], optional) - Arguments to pass to the function.\n  - `options` (Object, optional)\n    - `world` ('ISOLATED' | 'MAIN') - The world context for evaluation (default is 'MAIN').\n    - `allFrames` (boolean) - Indicates whether to evaluate in all frames (default is false).\n    - `frameIds` (number[]) - An array of frame identifiers where the evaluation should take place.\n    - `documentIds` (string[]) - An array of document identifiers for the frames to evaluate in.\n\n* #### `waitFor(func: Function, args: any[], options?: { tryLimit?: number; delay?: number }): Promise\u003cany\u003e`\n\n  Waits for a function to return a truthy value.\n\n  - `func` (Function) - The function representing the condition to wait for.\n  - `args` (any[]) - Arguments to pass to the function.\n  - `options` (Object, optional)\n    - `tryLimit` (number) - The maximum number of attempts to wait for the condition (default is this.tryLimit).\n    - `delay` (number) - The delay in milliseconds between attempts (default is this.delay).\n\n* #### `waitForNavigation(options?: { tryLimit?: number; delay?: number }): Promise\u003cvoid\u003e`\n\n  Waits for the page to navigate to a new URL.\n\n  - `options` (Object, optional)\n    - `tryLimit` (number) - The maximum number of attempts to wait for navigation (default is 50).\n    - `delay` (number) - The delay between each attempt in milliseconds (default is 750).\n\n* #### `waitForSelector(selectors: string, options?: { tryLimit?: number; delay?: number }, index: number = -1): Promise\u003cvoid\u003e`\n\n  Waits for an element matching the given CSS selector to become available.\n\n  - `selectors` (string) - The CSS selector to wait for.\n  - `options` (Object, optional)\n    - `tryLimit` (number) - The maximum number of attempts to find the element (default is 1000).\n    - `delay` (number) - The delay between attempts in milliseconds (default is 750).\n  - `index` (number, optional) - The index of the element if multiple elements match the selector.\n\n* #### `waitForSelectorMiss(selectors: string, options?: { tryLimit?: number; delay?: number }, index: number = -1): Promise\u003cvoid\u003e`\n\n  Waits for an element matching the given selector to disappear from the page.\n\n  - `selectors` (string) - The CSS selector or XPath expression to check for element absence.\n  - `options` (Object, optional)\n    - `tryLimit` (number) - The maximum number of attempts (default is 1000).\n    - `delay` (number) - The delay in milliseconds between attempts (default is 750ms).\n  - `index` (number, optional) - The index of the element if there are multiple matches.\n\n* #### `waitForXPath(expression: any, options?: { tryLimit?: number; delay?: number }, index: number = -1): Promise\u003cvoid\u003e`\n\n  Waits for an element matching the given XPath expression to appear in the page.\n\n  - `expression` (any) - The XPath expression to wait for.\n  - `options` (Object, optional)\n    - `tryLimit` (number) - The maximum number of attempts to find the element (default is 1000).\n    - `delay` (number) - The delay in milliseconds between attempts (default is 750ms).\n  - `index` (number, optional) - The index of the element to interact with.\n\n* #### `elementExists(selectors: string, index: number = -1): Promise\u003cboolean\u003e`\n\n  Checks if an element specified by the CSS selector or XPath expression exists on the page.\n\n  - `selectors` (string) - The CSS selector or XPath expression to check for existence.\n  - `index` (number) - The index of the element to check.\n\n* #### `click(selectors: string, index: number = -1): Promise\u003cvoid\u003e`\n\n  Clicks on the element specified by the CSS selector or XPath expression.\n\n  - `selectors` (string) - The CSS selector or XPath expression to click on.\n  - `index` (number) - The index of the element to interact with.\n\n* #### `execCopy(text: string): void`\n\n  Copies text to the clipboard.\n\n  - `text` (string) - The text to copy to the clipboard.\n\n* #### `execPaste(selectors: string, index: number = -1): Promise\u003cvoid\u003e`\n\n  Pastes text from the clipboard to an element specified by the CSS selector or XPath expression.\n\n  - `selectors` (string) - The CSS selector or XPath expression of the target element.\n  - `index` (number) - The index of the element to interact with (default is -1).\n\n* #### `triggerEvent(selectors: string, type: any, index: number = -1): Promise\u003cvoid\u003e`\n\n  Triggers an event on the element specified by the CSS selector or XPath expression.\n\n  - `selectors` (string) - The CSS selector or XPath expression of the target element.\n  - `type` (string) - The type of event to trigger.\n  - `index` (number) - The index of the element to interact with.\n\n* #### `input(selectors: string, value: any, index: number = -1): Promise\u003cvoid\u003e`\n\n  Inputs a value into the element specified by the CSS selector or XPath expression.\n\n  - `selectors` (string) - The CSS selector or XPath expression of the target element.\n  - `value` (any) - The value to input.\n  - `index` (number) - The index of the element to interact with.\n\n* #### `uploadFiles(files: (File | { name: string, blob: Blob, dataUrl?: string, blobUrl?: string } | any)[], selectors: string, caughtElementIndex: number): Promise\u003cvoid\u003e`\n\n  Uploads files to an input element specified by the CSS selector or XPath expression.\n\n  - `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.\n  - `selectors` (string) - The CSS selector or XPath expression of the input element.\n  - `caughtElementIndex` (number) - The index of the element to interact with (default is -1).\n\n* #### `screenshot(options: { clip?: { x: number; y: number; width: number; height: number } }): Promise\u003cstring\u003e`\n\n  Takes a screenshot of the visible area of the page.\n\n  - `options` (Object, optional)\n    - `clip` (Object) - Optional clipping parameters.\n\n\n### Class: `Browser`\n\nRepresents a Browser instance for interacting with Chrome browser pages.\n\n#### Properties\n\n- `availablePages` (Page[]) - An array of available Page instances within the browser.\n- `onPageAdded` (Function) - A callback function that is invoked when a new page is added to the browser.\n- `onPageCloseListener` (Function) - A function to listen for page close events.\n\n#### Constructor\n\n* #### `constructor()`\n\n  Creates a new Browser instance.\n\n#### Methods\n\n* #### `newPage({ tabId, windowId, originWindowId, activeInOrigin, windowOptions, tabOptions }): Promise\u003cPage\u003e`\n\n  Creates a new Page instance and associates it with the browser.\n\n  - `tabId` (number, optional) - The ID of the tab to use for creating the Page instance. If not supplied, a tab will be created.\n  - `windowId` (number, optional) - The ID of the window to open the page in. If not supplied, a window will be created.\n  - `originWindowId` (number, optional) - The ID of the tab's origin window (if any).\n  - `activeInOrigin` (boolean, optional) - Whether the page should be active in the origin window.\n  - `windowOptions` (chrome.windows.CreateData, optional) - Options for creating the window.\n  - `tabOptions` (chrome.tabs.CreateProperties | chrome.tabs.UpdateProperties, optional) - Options for creating or updating the tab.\n\n  - Returns: A Promise that resolves with the new Page instance.\n\n* #### `pages(): Page[]`\n\n  Returns an array of available Page instances.\n\n  - Returns: An array of available Page instances.\n\n* #### `onPageClose(closedTabId: number)`\n\n  Event listener for page close events.\n\n  - `closedTabId` (number) - The ID of the closed tab.\n\n* #### `close(): Promise\u003cvoid\u003e`\n\n  Closes all associated pages in the Browser instance.\n\n\n## Contributing\n\nYou are welcome to contribute! If you are adding a feature or fixing a bug, please contribute to the [GitHub repository](https://github.com/SheikhAminul/browser-automator/).\n\n\n## License\n\nbrowser-automator is licensed under the [MIT license](https://github.com/SheikhAminul/browser-automator/blob/main/LICENSE).\n\n\n## Author\n\n|[![@SheikhAminul](https://avatars.githubusercontent.com/u/25372039?v=4\u0026s=96)](https://github.com/SheikhAminul)|\n|:---:|\n|[@SheikhAminul](https://github.com/SheikhAminul)|","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsheikhaminul%2Fbrowser-automator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsheikhaminul%2Fbrowser-automator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsheikhaminul%2Fbrowser-automator/lists"}