{"id":23537494,"url":"https://github.com/smikodanic/pptr-plus","last_synced_at":"2026-02-25T15:02:56.653Z","repository":{"id":57749736,"uuid":"524359088","full_name":"smikodanic/pptr-plus","owner":"smikodanic","description":"Some extra functions which are missing in the Puppeteer (pptr.dev) library.","archived":false,"fork":false,"pushed_at":"2023-10-19T10:15:50.000Z","size":14,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-26T10:04:19.424Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smikodanic.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}},"created_at":"2022-08-13T09:50:16.000Z","updated_at":"2024-03-01T17:32:20.000Z","dependencies_parsed_at":"2022-08-26T23:21:33.721Z","dependency_job_id":null,"html_url":"https://github.com/smikodanic/pptr-plus","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smikodanic%2Fpptr-plus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smikodanic%2Fpptr-plus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smikodanic%2Fpptr-plus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smikodanic%2Fpptr-plus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smikodanic","download_url":"https://codeload.github.com/smikodanic/pptr-plus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239250324,"owners_count":19607427,"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":[],"created_at":"2024-12-26T03:15:48.220Z","updated_at":"2026-02-25T15:02:56.562Z","avatar_url":"https://github.com/smikodanic.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pptr-plus\n\u003e Enhancing Puppeteer with useful extra functionalities.\n\n[![npm version](https://badge.fury.io/js/pptr-plus.svg)](https://www.npmjs.com/package/pptr-plus)\n\n`pptr-plus` is a Node.js library that extends the capabilities of the popular [Puppeteer](https://pptr.dev/) library by providing a collection of convenient and commonly needed functions for web automation and scraping.\n\n## Installation\n\n```bash\n$ npm install pptr-plus\n````\n\n## Usage\n\n```javascript\n/*** NodeJS script ***/\nconst puppeteer = require('puppeteer');\nconst PptrPlus = require('pptr-plus');\n\n(async () =\u003e {\n  const browser = await puppeteer.launch();\n  const page = await browser.newPage();\n  await page.goto('[https://example.com](https://example.com)');\n\n  const pp = new PptrPlus(page);\n\n  // Example using checkTextOnPage\n  try {\n    await pp.checkTextOnPage('Example Domain');\n    console.log('Text found on the page.');\n  } catch (error) {\n    console.error('Text not found:', error.message);\n  }\n\n  await browser.close();\n})();\n```\n\n## API\n\n### `constructor(page)`\n\nInitializes a new `PptrPlus` instance.\n\n  - `page`: The [Puppeteer Page](https://pptr.dev/api/puppeteer.page) or [Frame](https://pptr.dev/api/puppeteer.frame) object to extend.\n\n\u003c!-- end list --\u003e\n\n```javascript\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\nconst pp = new PptrPlus(page);\n```\n\n### `async autoscroll(cssSel, delay = 3400)`\n\nAutoscrolls a web page that loads content dynamically as the user scrolls down (e.g., Facebook feeds). It scrolls vertically to the last element defined by the `cssSel`. The scrolling stops when the text content of the last element remains the same after a scroll, indicating no new content has loaded.\n\n  - `cssSel` (`string`): CSS selector of the last repetitive content element (e.g., `'table \u003e tbody \u003e tr:last-child'`).\n  - `delay` (`number`, optional): The time interval in milliseconds between consecutive scrolls. Defaults to `3400`.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.autoscroll('#post-container \u003e div.post:last-child');\nawait pp.autoscroll('.comment', 2000);\n```\n\n### `async scrollToElement(page, selector, position)`\n\nScrolls the specified Puppeteer `Page` to a particular element defined by the CSS `selector`, making it visible.\n\n  - `page` (`Page`): The Puppeteer `Page` object.\n  - `selector` (`string`): The CSS selector of the element to scroll to.\n  - `position` (`'start'|'end'`): Where the scrolled element should appear after scrolling: 'start' means at the top, 'end' means at the bottom\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.scrollToElement(page, '#footer');\n```\n\n### `async scrollToBottom(page)`\n\nScrolls the specified Puppeteer `Page` to the very bottom of the document.\n\n  - `page` (`Page`): The Puppeteer `Page` object.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.scrollToBottom(page);\n```\n\n### `async scrollToBottomEasy(delay = 100)`\n\nScrolls the current page to the bottom incrementally. It scrolls by the window's `innerHeight` at each interval defined by `delay` until the bottom of the page is reached.\n\n  - `delay` (`number`, optional): The time interval in milliseconds between consecutive scrolls. Defaults to `100`.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.scrollToBottomEasy();\nawait pp.scrollToBottomEasy(500);\n```\n\n### `async selectOptionByText(sel, txt)`\n\nClicks a `\u003cselect\u003e` element and then clicks the `\u003coption\u003e` within it that contains the specified text.\n\n  - `sel` (`string`): CSS selector for the `\u003cselect\u003e` tag.\n  - `txt` (`string`): The text content of the `\u003coption\u003e` tag to select.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.selectOptionByText('#country-select', 'United States');\n```\n\n### `async selectOptionByValue(sel, val)`\n\nSelects an option in a `\u003cselect\u003e` element by its `value` attribute.\n\n  - `sel` (`string`): CSS selector for the `\u003cselect\u003e` tag.\n  - `val` (`string`): The `value` attribute of the `\u003coption\u003e` tag to select.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.selectOptionByValue('#product-type', 'premium');\n```\n\n### `async clickElemWithText(xPath, txt, exactMatch)`\n\nClicks an HTML element identified by an XPath that contains specific text.\n\n  - `xPath` (`string`): The base XPath to search within (e.g., `'//ul[@id=\"menu\"]/li/a'`).\n  - `txt` (`string`): The text content to look for within the element.\n  - `exactMatch` (`boolean`, optional): If `true`, it will only match elements where the text content is exactly equal to `txt`. If `false` (default), it will match elements that contain `txt`.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.clickElemWithText('//nav/ul/li/a', 'Products', true);\nawait pp.clickElemWithText('//div[@class=\"item\"]', 'Add to cart');\n```\n\n### `async clickElemWithText_bubles(xPath, txt, exactMatch)`\n\nSimilar to `clickElemWithText`, but it dispatches a native 'click' event with `bubbles: true` and `cancelable: true`. This can be useful for triggering event listeners that are not directly attached to the target element.\n\n  - `xPath` (`string`): The base XPath to search within (e.g., `'//ul[@id=\"menu\"]/li/button'`).\n  - `txt` (`string`): The text content to look for within the element.\n  - `exactMatch` (`boolean`, optional): If `true`, it will only match elements where the text content is exactly equal to `txt`. If `false` (default), it will match elements that contain `txt`.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.clickElemWithText_bubles('//div[@class=\"control\"]/button', 'Submit');\n```\n\n### `checkTextOnPage(txt)`\n\nChecks if the specified text is present anywhere within the `\u003cbody\u003e` of the current page.\n\n  - `txt` (`string`): The text to search for.\n\n**Returns:** `Promise\u003cboolean\u003e` - Resolves if the text is found, rejects with an error if not found within the timeout.\n\n```javascript\nawait pp.checkTextOnPage('Welcome to our website');\n```\n\n### `async waitURLContains(txt)`\n\nWaits for a page response whose URL contains the specified text pattern.\n\n  - `txt` (`string`): The text to check for in the URL.\n\n**Returns:** `Promise\u003cvoid\u003e` - Resolves when a matching URL is encountered in a response.\n\n```javascript\nawait pp.waitURLContains('/products/');\nawait pp.waitURLContains('checkout');\n```\n\n### `async inputClear(sel)`\n\nClears the value of an input field specified by the CSS selector. Useful before typing a new value.\n\n  - `sel` (`string`): CSS selector of the input field.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.inputClear('#search-box');\n```\n\n### `async inputType(sel, val)`\n\nTypes the specified value into an input field identified by the CSS selector. It first focuses on the element and then simulates keyboard input.\n\n  - `sel` (`string`): CSS selector of the input field.\n  - `val` (`string`): The value to type into the input field.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.inputType('#username', 'john.doe');\nawait pp.inputType('#password', 'secure123');\n```\n\n### `async inputSetValue(sel, val)`\n\nSets the value of an input element directly. This can be used for various input types, including text, radio buttons, and checkboxes. For radio and checkbox inputs, it sets the `checked` property based on the `val`.\n\n  - `sel` (`string`): CSS selector of the input element(s).\n  - `val` (`string`): The value to set. For radio buttons and checkboxes, this is the `value` attribute to check.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.inputSetValue('#email', 'test@example.com');\nawait pp.inputSetValue('input[name=\"gender\"]', 'male'); // For radio buttons\nawait pp.inputSetValue('input[type=\"checkbox\"]', 'agree'); // For checkboxes\n```\n\n### `async saveScreenshot(dirPath, fileName)`\n\nTakes a full-page screenshot and saves it as a `.jpg` file in the specified directory. If the filename doesn't include the `.jpg` extension, it will be added automatically.\n\n  - `dirPath` (`string`): The path to the directory where the screenshot will be saved (e.g., `'./screenshots'`). The directory will be created if it doesn't exist.\n  - `fileName` (`string`): The name of the screenshot file (e.g., `'homepage.jpg'` or `'homepage'`).\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.saveScreenshot('./screenshots', 'home_page');\nawait pp.saveScreenshot('../../temp/shots', 'product_details.jpg');\n```\n\n### `async elementHandle2HTML(eh)`\n\nRetrieves the `outerHTML` string of a given Puppeteer `ElementHandle`.\n\n  - `eh` (`ElementHandle`): The Puppeteer `ElementHandle` to get the HTML from.\n\n**Returns:** `Promise\u003cstring\u003e` - The outer HTML of the element.\n\n```javascript\nconst header = await page.$('h1');\nconst headerHTML = await pp.elementHandle2HTML(header);\nconsole.log(headerHTML);\n```\n\n### `async cookieSave(cookie_file_path)`\n\nSaves the current browser cookies to a JSON file.\n\n  - `cookie_file_path` (`string`): The path to the JSON file where cookies will be saved (e.g., `'./cookies.json'`). The file and any necessary directories will be created.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.cookieSave('./session_cookies.json');\n```\n\n### `async cookieTake(cookie_file_path)`\n\nLoads cookies from a JSON file and sets them in the current browser session.\n\n  - `cookie_file_path` (`string`): The path to the JSON file containing the saved cookies.\n\n**Returns:** `Promise\u003cboolean\u003e` - Returns `true` if the cookie file was found and cookies were set, `false` otherwise.\n\n```javascript\nawait pp.cookieTake('./session_cookies.json');\n```\n\n### `async storageSave(storage_file_path, storage_type = 'localStorage')`\n\nSaves either the `localStorage` or `sessionStorage` data from the browser to a JSON file.\n\n  - `storage_file_path` (`string`): The path to the JSON file where the storage data will be saved (e.g., `'./local_storage.json'`).\n  - `storage_type` (`string`, optional): The type of storage to save. Can be `'localStorage'` (default) or `'sessionStorage'`.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.storageSave('./local_data.json', 'localStorage');\nawait pp.storageSave('./session_data.json', 'sessionStorage');\n```\n\n### `async storageTake(storage_file_path, storage_type = 'localStorage')`\n\nLoads `localStorage` or `sessionStorage` data from a JSON file and sets it in the current browser session.\n\n  - `storage_file_path` (`string`): The path to the JSON file containing the saved storage data.\n  - `storage_type` (`string`, optional): The type of storage to load. Can be `'localStorage'` (default) or `'sessionStorage'`.\n\n**Returns:** `Promise\u003cvoid\u003e`\n\n```javascript\nawait pp.storageTake('./local_data.json', 'localStorage');\nawait pp.storageTake('./session_data.json', 'sessionStorage');\n```\n\n## License\nThe software is licensed under [AGPL-3](https://www.google.com/search?q=LICENSE).\n\nCreator website: [www.mikosoft.info](https://www.mikosoft.info/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmikodanic%2Fpptr-plus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmikodanic%2Fpptr-plus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmikodanic%2Fpptr-plus/lists"}