{"id":14984323,"url":"https://github.com/lucianoganga/simple-headless-chrome","last_synced_at":"2025-04-05T13:07:21.166Z","repository":{"id":44443397,"uuid":"91772397","full_name":"LucianoGanga/simple-headless-chrome","owner":"LucianoGanga","description":"Simple abstraction to use Chrome as a Headless Browser with Node JS","archived":false,"fork":false,"pushed_at":"2017-12-19T19:07:38.000Z","size":3086,"stargazers_count":215,"open_issues_count":25,"forks_count":43,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-05T13:06:57.709Z","etag":null,"topics":["chrome","chrome-headless","google-chrome","horseman","node-browsers","testing-tools","unit-testing"],"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/LucianoGanga.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":"2017-05-19T06:19:47.000Z","updated_at":"2025-02-23T08:52:06.000Z","dependencies_parsed_at":"2022-07-16T02:00:31.798Z","dependency_job_id":null,"html_url":"https://github.com/LucianoGanga/simple-headless-chrome","commit_stats":null,"previous_names":[],"tags_count":68,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucianoGanga%2Fsimple-headless-chrome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucianoGanga%2Fsimple-headless-chrome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucianoGanga%2Fsimple-headless-chrome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucianoGanga%2Fsimple-headless-chrome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LucianoGanga","download_url":"https://codeload.github.com/LucianoGanga/simple-headless-chrome/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339158,"owners_count":20923014,"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":["chrome","chrome-headless","google-chrome","horseman","node-browsers","testing-tools","unit-testing"],"created_at":"2024-09-24T14:08:51.801Z","updated_at":"2025-04-05T13:07:21.145Z","avatar_url":"https://github.com/LucianoGanga.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/LucianoGanga/simple-headless-chrome.svg?branch=master)](https://travis-ci.org/LucianoGanga/simple-headless-chrome)\n\n# simple-headless-chrome\n\n# This project is looking for a maintainer\nIf you'd like to help others in this project, you're more than welcome! I made this project for work and I wanted to make it available for other people, but usually I don't have the time I'd like to have to maintain the project. So, if you're interested, and want to help with this, just let me know :) \n\nIt will be mostly having help to answer some doubts and issues. \n\nThanks!\n\n\n## Important version \u003e= 3.3.0\n\nVersion 3.3.0 includes a new feature that allows managing browser tabs. \n\nThis new feature comes with some breaking changes that will allow us future scalability. \n\nTo avoid problems for people that uses version \u003e= 3.3.0 of this module, we supported those breaking changes with methods that will be deprecated in version 4.0.0. \n\n# Introduction\n\nThis is an abstraction to use a Headless version of Google Chrome in a very simple way.\nI was inspired by the next projects:\n\n-   Doffy (\u003chttps://github.com/qieguo2016/doffy\u003e)\n-   Horseman (\u003chttps://github.com/johntitus/node-horseman\u003e)\n-   chrome-remote-interface (\u003chttps://github.com/cyrus-and/chrome-remote-interface\u003e)\n-   lighthouse (\u003chttps://github.com/googlechrome/lighthouse\u003e)\n\nAnd I had to read a lot here too:\n\n-   \u003chttps://developers.google.com/web/updates/2017/04/headless-chrome\u003e\n-   \u003chttps://chromedevtools.github.io/devtools-protocol\u003e\n\nAnd you can also use this in heroku thanks to \u003chttps://github.com/heroku/heroku-buildpack-google-chrome\u003e\n\nI built this basically because I got tired of an error I received in an edge case when using PhantomJS (Unhandled reject Error: Failed to load url). So I decided to make my own abstraction, to be used in a heroku app, and simple to use as Horseman.\n\nI didn't have time to document here in the readme, but every method in the source code is documented.\n\nIt's really simple to use. I hope I can get some time to make a QuickStart guide + document the API methods here.\n\nYou can read my post in Medium about this module: [How to tell to a headless Google Chrome to write a post in Medium for you](https://medium.com/@lucho_1312/how-to-tell-to-a-headless-google-chrome-to-write-a-post-in-medium-for-you-cbee3272f2fa)\n\n#### You can check a video of the module in action clicking in the image below\n\n[![A quick example](http://img.youtube.com/vi/m1Cr7bbM1Qk/0.jpg)](http://www.youtube.com/watch?v=m1Cr7bbM1Qk)\n\n# Features\n\n-   Easy to use\n-   Multiples Tabs navigation\n-   Private tab navigation (incognito mode)\n-   Cookies management\n-   Full-size screenshots\n-   Export to PDF\n-   Docker compatible\n\nAnd comming soon...\n\n-   Video capture (yes, you'll be able to record your navigation and save it as a video or gif)\n\n# Collaboration\n\nIf you want to collaborate with the project, in any way (documentation, examples, fixes, etc), just send a PR :)\n\nIf you rock at making tests, it would be very useful if you can help us making this module better.\nIt's not necesary to build all the tests, but if someone knows how to code the base to add tests to this module, it would really help for someone else to start with this part.\n\nThank you to everyone who already help submitting a PR! :D\n\n# Installation\n\n## 1) Install Google Chrome Headless\n\n### In your PC\n\nMac: Chrome Headless is shipped in Chrome Canary. You can install it here: \u003chttps://www.google.com/chrome/browser/canary.html\u003e\n\nLinux: Chrome headless is shipped on chrome 59. so you can install Chrome 59 to use the headless mode:\n\n\u003chttps://askubuntu.com/questions/79280/how-to-install-chrome-browser-properly-via-command-line\u003e\n\n    sudo apt-get install libxss1 libappindicator1 libindicator7\n    wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb\n    sudo dpkg -i google-chrome*.deb  # Might show \"errors\", fixed by next line\n    sudo apt-get install -f\n\n### In a NodeJS Heroku App\n\nJust add the buildpack for Heroku and vualá! Everything is ready\nYou can check the buildpack repository here: \u003chttps://github.com/heroku/heroku-buildpack-google-chrome\u003e\n\n### Using a Docker image\n\nWith the addition of Chrome Remote Interface into Chrome 59, a simple way to install is using the Docker image for Chrome Headless, such as \u003chttps://hub.docker.com/r/justinribeiro/chrome-headless/\u003e or \u003chttps://hub.docker.com/r/yukinying/chrome-headless/\u003e\n\nIf using Docker, in your app, configure for headless as follows:\n\n```js\nconst browser = new HeadlessChrome({\n  headless: true,\n  launchChrome: false,\n  chrome: {\n    host: 'localhost',\n    port: 9222, // Chrome Docker default port\n    remote: true,\n  },\n  browserlog: true\n})\n```\n\n## 2) Install the NPM Module\n\n    npm install --save simple-headless-chrome\n\n# Compatibility\n\nThanks to @lewisf, simple-headless-chrome is compatible on NodeJS \u003e= 4! \nI hope more persons can benefit of this now :) \n\n# Usage\n\n```js\nconst HeadlessChrome = require('simple-headless-chrome')\n\nconst browser = new HeadlessChrome({\n  headless: true, // If you turn this off, you can actually see the browser navigate with your instructions,\n  chrome: {\n    userDataDir: '/tmp/headlessDataDir' // This can be null, so a tmp folder will be created and then destroyed\n  }\n})\n```\n\nOnce you have the browser instance, you can call the methods to interact with it.\n\n# Methods\n\n\u003c!-- Generated by documentation.js. Update this documentation by updating the source code. --\u003e\n\n## inject\n\nInjects JavaScript in the page\n\nModules available: jQuery, jquery, jQuery.slim and jquery.slim\n\n**Parameters**\n\n-   `moduleOrScript` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Javascript code, file, url or name of the\n    module to inject.\n\n**Examples**\n\n```javascript\ninject('jquery')\n\nYou can use jsdelivr to inject any npm or github package in the page\n```\n\n```javascript\ninject('https://cdn.jsdelivr.net/npm/lodash@4/lodash.min.js')\n```\n\n```javascript\ninject('https://cdn.jsdelivr.net/npm/jquery@3/dist/jquery.min.js')\n\nYou can inject a local Javascript file\n```\n\n```javascript\ninject('./custom-file.js')\n```\n\n```javascript\ninject(__dirname + '/path/to/file.js')\n\nNote: the path will be resolved with `require.resolve()` so you can include\nfiles that are in `node_modules` simply by installing them with NPM\n```\n\n```javascript\ninject('jquery/dist/jquery.min')\n```\n\n```javascript\ninject('lodash/dist/lodash.min')\n```\n\n## injectRemoteScript\n\nInjects a remote script in the page\n\n**Parameters**\n\n-   `src` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Url to remote JavaScript file\n\n**Examples**\n\n```javascript\ninjectRemoteScript(https://ajax.googleapis.com/ajax/libs/jquery/2.2.0/jquery.min.js)\n```\n\n## injectScript\n\nInjects code in the DOM as script tag\n\n**Parameters**\n\n-   `script` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Code to be injected and evaluated in the DOM\n\n## evaluate\n\nEvaluates a fn in the context of the browser\n\n**Parameters**\n\n-   `fn`  {function} - The function to evaluate in the browser\n-   `args` **...any** {\\*} - The arguments to pass to the function\n\n## evaluateAsync\n\nEvaluates an async fn in the context of the browser\n\n**Parameters**\n\n-   `fn`  {function} - The function to evaluate in the browser\n-   `args` **...any** {\\*} - The arguments to pass to the function\n\n## evaluateOnNode\n\nEvaluates a fn in the context of a passed node\n\n**Parameters**\n\n-   `node` **NodeObject** The Node Object used to get the context\n-   `fn`  {function} - The function to evaluate in the browser\n-   `args` **...any** {\\*} - The arguments to pass to the function\n\n## goTo\n\nNavigates to a URL\n\n**Parameters**\n\n-   `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The URL to navigate to\n-   `opt`   (optional, default `{}`)\n-   `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The options object.\n    options:\n\n**Properties**\n\n-   `timeout` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Time in ms that this method has to wait until the\n    \"pageLoaded\" event is triggered. If the value is 0 or false, it means that it doesn't\n    have to wait after calling the \"Page.navigate\" method\n\n## getNodeValue\n\nGet the value of an Node.\n\n**Parameters**\n\n-   `node` **NodeObject** The Node Object\n\nReturns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object containing type and value of the element\n\n## getValue\n\nGet the value of an element.\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The target selector\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\nReturns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object containing type and value of the element\n\n## setNodeValue\n\nSet the value of an element.\n\n**Parameters**\n\n-   `node` **NodeObject** The Node Object\n-   `value` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The value to set the node to (it may be an array of values when the node is a multiple \"HTMLSelectElement\")\n\n## setValue\n\nSet the value of an element.\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector to set the value of.\n-   `value` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The value to set the selector to\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\n## fill\n\nFills a selector of an input or textarea element with the passed value\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector\n-   `value` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The value to fill the element matched in the selector\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\n## clear\n\nClear an input field.\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector to clear.\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\n## querySelector\n\nReturns the node associated to the passed selector\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector to find\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\n## focus\n\nFocus on an element matching the selector\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector to find the element\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\n## type\n\nSimulate a keypress on a selector\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector to type into.\n-   `text` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The text to type.\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n-   `opts`  \n-   `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Lets you send keys like control \u0026 shift\n\n## typeText\n\nTypes text (doesn't matter where it is)\n\n**Parameters**\n\n-   `text` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The text to type.\n-   `opts`  \n-   `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Lets you send keys like control \u0026 shift\n\n## select\n\nSelect a value in an html select element.\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The identifier for the select element.\n-   `value` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The value to select.\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\n## keyboardEvent\n\n-   **See: \u003chttps://chromedevtools.github.io/devtools-protocol/tot/Input/#method-dispatchKeyEvent\u003e**\n\nFire a key event.\n\n**Parameters**\n\n-   `type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The type of key event. (optional, default `keypress`)\n-   `key` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The key to use for the event. (optional, default `null`)\n-   `modifier` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** The keyboard modifier to use. (optional, default `0`)\n-   `windowsVirtualKeyCode`   (optional, default `0`)\n\n## wait\n\nWaits certain amount of ms\n\n**Parameters**\n\n-   `time` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Ammount of ms to wait\n\n## onConsole\n\nBinding callback to handle console messages\n\n**Parameters**\n\n-   `listener`  is a callback for handling console message\n\n## waitForPageToLoad\n\nWaits for a page to finish loading. Throws error after timeout\n\n**Parameters**\n\n-   `timeout` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** The timeout in ms. (Default: \"loadPageTimeout\" property in the browser instance options)\n\n## waitForFrameToLoad\n\nWaits for all the frames in the page to finish loading. Returns the list of frames after that\n\n**Parameters**\n\n-   `url` **([regexp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) \\| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** The URL that must be waited for load\n-   `timeout`  \n\nReturns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** List of frames, with childFrames\n\n## waitForSelectorToLoad\n\nWaits for a selector to finish loading. Throws error after timeout\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The identifier for the select element.\n-   `interval` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** The interval in ms. (Default: \"loadPageTimeout\" property in the browser instance options)\n-   `timeout` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** The timeout in ms. (Default: \"loadPageTimeout\" property in the browser instance options)\n\n## mouseEvent\n\n-   **See: \u003chttps://chromedevtools.github.io/devtools-protocol/tot/Input/#method-dispatchMouseEvent\u003e**\n\nFire a mouse event.\n\n**Parameters**\n\n-   `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** \n    -   `$0.type`   (optional, default `'mousePressed'`)\n    -   `$0.x`   (optional, default `0`)\n    -   `$0.y`   (optional, default `0`)\n    -   `$0.modifiers`   (optional, default `0`)\n    -   `$0.button`   (optional, default `'left'`)\n    -   `$0.clickCount`   (optional, default `1`)\n-   `type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of the mouse event. Allowed values: mousePressed, mouseReleased, mouseMoved. (optional, default `mousePressed`)\n-   `x` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** X coordinate of the event relative to the main frame's viewport. (optional, default `0`)\n-   `y` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Y coordinate of the event relative to the main frame's viewport. 0 refers to the top of the viewport and Y increases as it proceeds towards the bottom of the viewport. (optional, default `0`)\n-   `modifier` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Bit field representing pressed modifier keys. Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0). (optional, default `0`)\n-   `button` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Mouse button (default: \"none\"). Allowed values: none, left, middle, right. (optional, default `left`)\n\n## click\n\nClick on a selector by firing a 'click event' directly in the element of the selector\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Selector of the element to click\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\n## clickOnSelector\n\nClicks left button hover the centroid of the element matching the passed selector\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** \n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\n## getNodeCentroid\n\nCalculates the centroid of a node by using the boxModel data of the element\n\n**Parameters**\n\n-   `nodeId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The Node Id\n\nReturns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** { x, y } object with the coordinates\n\n## getCookies\n\nGet the browser cookies\n\nReturns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object with all the cookies\n\n## setCookie\n\nSet the browser cookies\n\n**Parameters**\n\n-   `name` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The name of the cookie.\n-   `value` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The value of the cookie.\n-   `options`   (optional, default `{}`)\n-   `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The request-URI to associate with the setting of the cookie.\n\n**Properties**\n\n-   `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options object\n-   `domain` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** If omitted, the cookie becomes a host-only cookie\n-   `path` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Defaults to the path portion of the url parameter\n-   `secure` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Defaults to false.\n-   `httpOnly` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Defaults to false.\n-   `sameSite` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Represents the cookie's 'SameSite' status: \u003chttps://tools.ietf.org/html/draft-west-first-party-cookies\u003e\n-   `expirationDate` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** If omitted, cookie becomes a session cookie\n    }} options - additional options for setting the cookie (more info here: \u003chttps://chromedevtools.github.io/devtools-protocol/tot/Network/#method-setCookie\u003e)\n\nReturns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** True if successfully set cookie\n\n## clearBrowserCookies\n\nClear the browser cookies\n\n## exist\n\nChecks if an element matches the selector\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector string\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\nReturns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Boolean indicating if element of selector exists or not\n\n## visible\n\nChecks if an element matching a selector is visible\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector string\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\nReturns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Boolean indicating if element of selector is visible or not\n\n## getScreenshot\n\nTakes a screenshot of the page and returns it as a string\n\n**Parameters**\n\n-   `captureOptions` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options object\n    Options properties:\n    -   `captureOptions.format`   (optional, default `'png'`)\n    -   `captureOptions.quality`  \n    -   `captureOptions.clip`   (optional, default `{x:0,y:0,width:this.options.deviceMetrics.width,height:this.options.deviceMetrics.height,scale:this.options.deviceMetrics.deviceScaleFactor}`)\n    -   `captureOptions.fromSurface`  \n    -   `captureOptions.selector`  \n    -   `captureOptions.fullPage`  \n-   `returnBinary` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If true, returns as binary. Otherwise, returns a base64 string (optional, default `false`)\n\n**Properties**\n\n-   `format` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Image compression format (defaults to png). Allowed values: jpeg, png.\n-   `quality` **integer?** Compression quality from range [0..100] \\(jpeg only).\n-   `clip` **ViewPort?** Capture the screenshot of a given viewport/region only (\u003chttps://chromedevtools.github.io/devtools-protocol/tot/Page/#type-Viewport\u003e)\n-   `fromSurface` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Capture the screenshot from the surface, rather than the view. Defaults to false. EXPERIMENTAL\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The selector to be captured. If empty, will capture the page\n-   `fullPage` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** If true, captures the full page height\n\nReturns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Binary or Base64 string with the image data\n\n## saveScreenshot\n\nSaves a screenshot of the page\n\n**Parameters**\n\n-   `fileName` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path and Name of the file (without the extension) (optional, default `` `screenshot-${Date.now()}` ``)\n-   `captureOptions` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options object\n    Options properties: (optional, default `{}`)\n    -   `captureOptions.format`   (optional, default `'png'`)\n    -   `captureOptions.quality`  \n    -   `captureOptions.clip`  \n    -   `captureOptions.fromSurface`  \n    -   `captureOptions.selector`  \n    -   `captureOptions.fullPage`  \n\n**Properties**\n\n-   `format` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Image compression format (defaults to png). Allowed values: jpeg, png.\n-   `quality` **integer** Compression quality from range [0..100] \\(jpeg only).\n-   `clip` **ViewPort** Capture the screenshot of a given region only (\u003chttps://chromedevtools.github.io/devtools-protocol/tot/Page/#type-Viewport\u003e)\n-   `fromSurface` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Capture the screenshot from the surface, rather than the view. Defaults to false. EXPERIMENTAL\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The selector to be captured. If empty, will capture the page\n-   `fullPage` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** If true, captures the full page height\n\nReturns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Binary or Base64 string with the image data\n\n## printToPDF\n\nPrints the page to PDF\n\n**Parameters**\n\n-   `options`   (optional, default `{}`)\n-   `returnBinary` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If true, returns as binary. Otherwise, returns a base64 string (optional, default `false`)\n\n**Properties**\n\n-   `landscape` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Paper orientation. Defaults to false.\n-   `displayHeaderFooter` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Display header and footer. Defaults to false.\n-   `printBackground` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Print background graphics. Defaults to false.\n-   `scale` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Scale of the webpage rendering. Defaults to 1.\n-   `paperWidth` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Paper width in inches. Defaults to 8.5 inches.\n-   `paperHeight` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Paper height in inches. Defaults to 11 inches.\n-   `marginTop` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Top margin in inches. Defaults to 1cm (~0.4 inches).\n-   `marginBottom` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Bottom margin in inches. Defaults to 1cm (~0.4 inches).\n-   `marginLeft` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Left margin in inches. Defaults to 1cm (~0.4 inches).\n-   `marginRight` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Right margin in inches. Defaults to 1cm (~0.4 inches).\n-   `pageRanges` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.\n    }} options - Options object\n\nReturns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Binary or Base64 string with the PDF data\n\n## savePdf\n\nSaves a PDF file of the page\n\n**Parameters**\n\n-   `fileName` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path and Name of the file (optional, default `` `pdf-${Date.now()}` ``)\n-   `options`   (optional, default `{}`)\n\n**Properties**\n\n-   `landscape` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Paper orientation. Defaults to false.\n-   `displayHeaderFooter` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Display header and footer. Defaults to false.\n-   `printBackground` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Print background graphics. Defaults to false.\n-   `scale` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Scale of the webpage rendering. Defaults to 1.\n-   `paperWidth` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Paper width in inches. Defaults to 8.5 inches.\n-   `paperHeight` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Paper height in inches. Defaults to 11 inches.\n-   `marginTop` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Top margin in inches. Defaults to 1cm (~0.4 inches).\n-   `marginBottom` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Bottom margin in inches. Defaults to 1cm (~0.4 inches).\n-   `marginLeft` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Left margin in inches. Defaults to 1cm (~0.4 inches).\n-   `marginRight` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Right margin in inches. Defaults to 1cm (~0.4 inches).\n-   `pageRanges` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.\n    }} options - PDF options\n\n## getSelectorViewport\n\nGet the Viewport of the element matching a selector\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector string\n-   `frameId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The FrameID where the selector should be searched\n\nReturns **Viewport** Object with the viewport properties (\u003chttps://chromedevtools.github.io/devtools-protocol/tot/Page/#type-Viewport\u003e)\n\n## getFrames\n\nGet the list of frames in the loaded page\n\nReturns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** List of frames, with childFrames\n\n## resizeFullScreen\n\nResize viewports of the page to full screen size\n\n## handleDialog\n\nAccepts or dismisses a JavaScript initiated dialog (alert, confirm, prompt, or onbeforeunload)\n\n**Parameters**\n\n-   `accept` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether to accept or dismiss the dialog (optional, default `true`)\n-   `promptText` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The text to enter into the dialog prompt before accepting. Used only if this is a prompt dialog. (optional, default `''`)\n\n## post\n\nPost data from the browser context\n\n**Parameters**\n\n-   `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The URL or path to POST to\n-   `data` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** The data object to be posted (optional, default `{}`)\n-   `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Options of the request (optional, default `{}`)\n\nReturns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Request status and data\n\n## value\n\nTODO: Take the value from the DOM Node. For some reason, there're some pages where is not possible\nto get the textarea value, as its nodeId refreshes all the time\n\n## setNodeValue\n\nTODO: Take the value from the DOM Node. For some reason, there're some pages where is not possible\nto get the textarea value, as its nodeId refreshes all the time\n\n## browserIsInitialized\n\nChecks if the browser is initialized. Exits the process if it's not\n\n## fixSelector\n\nAs the selectors may contain colons, it's necessary to escape them in order to correctly match an element\n\n**Parameters**\n\n-   `selector` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector string\n\nReturns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The selector with colons escaped (One backslash to escape the ':' for CSS, and other to escape the first one for JS)\n\n## promiseTimeout\n\nRuns a promise and throws an error if it's not resolved before the timeout\n\n**Parameters**\n\n-   `promise` **[promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** The promise to run\n-   `timeout` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** The timeout time, in ms\n\n## interleaveArrayToObject\n\nTransforms an interleave array into a key - value object\n\n**Parameters**\n\n-   `interleaveArray` **[array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** The interleave array\n\nReturns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The key value object\n\n## objectToEncodedUri\n\nGiven an object, transforms it's properties to a URL encoded string\n\n**Parameters**\n\n-   `object` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to transform\n\nReturns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The URL Enconded object\n\n## sleep\n\nCreates some delay\n\n**Parameters**\n\n-   `delay` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Delay in miliseconds\n\nReturns **[promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** The promise that will solve after the delay\n\n# Example\n\n```js\nconst HeadlessChrome = require('simple-headless-chrome')\n\nconst browser = new HeadlessChrome({\n  headless: true // If you turn this off, you can actually see the browser navigate with your instructions\n  // see above if using remote interface\n})\nasync function navigateWebsite() {\n  try {\n    await browser.init()\n\n    const mainTab = await browser.newTab({ privateTab: false })\n\n    // Navigate to a URL\n    await mainTab.goTo('http://www.mywebsite.com/login')\n\n    // Fill an element\n    await mainTab.fill('#username', 'myUser')\n\n    // Type in an element\n    await mainTab.type('#password', 'Yey!ImAPassword!')\n\n    // Click on a button\n    await mainTab.click('#Login')\n\n    // Log some info in your console\n    await mainTab.log('Click login')\n\n    // Wait some time! (2s)\n    await mainTab.wait(2000)\n\n    // Log some info in your console, ONLY if you started the app in DEBUG mode (DEBUG='HeadlessChrome*' npm start)\n    await mainTab.debugLog('Waiting 5 seconds to give some time to all the redirects')\n\n    // Navigate a little...\n    await mainTab.goTo('http://www.mywebsite.com/myProfile')\n\n    // Check the select current value\n    const myCurrentSubscriptionPlan = await mainTab.getValue('#subscriptionSelect')\n    console.log(myCurrentSubscriptionPlan) // {type: 'string', value: '1 month' }\n\n    // Edit the subscription\n    await mainTab.select('#subscriptionSelect', '3 months')\n    await mainTab.click('#Save')\n\n    // Resize the viewport to full screen size (One use is to take full size screen shots)\n    await mainTab.resizeFullScreen()\n\n    // Take a screenshot\n    await mainTab.saveScreenshot('./shc.png')\n\n    // Get a HTML tag value based on class id\n    const htmlTag = await mainTab.evaluate(function(selector) {\n        const selectorHtml = document.querySelector(selector)\n        return selectorHtml.innerHTML\n    }, '.main'); // returns innerHTML of first matching selector for class \"main\"\n\n    // Close the browser\n    await browser.close()\n  } catch (err) {\n    console.log('ERROR!', err)\n  }\n }\n navigateWebsite()\n```\n\n# TODO:\n\n### Better docs\n\n### Add more methods\n\n-   [x] .waitForSelector\n-   [x] .setCookie (set individual cookie) Thanks @saidganim !\n-   [ ] .setCookies (set a full object of cookies, like the one from .getCookies())\n\n### Support more Chrome flags\n\n-   [x] \\--disable-translate\n-   [x] \\--disable-extensions\n-   [x] \\--no-first-run\n-   [x] And many more! Only those useful...\n    All supported thanks to @hugorodrigues. Now just pass an array in the init settings, like this: \n\n```js\nconst browser = new HeadlessChrome({\n    headless: false, // If you turn this off, you can actually see the browser navigate with your instructions\n    chrome: {\n      flags: [\n        '--use-fake-device-for-media-stream',\n        '--use-fake-ui-for-media-stream'\n      ]\n    }\n  })\n```\n\n### And more...\n\n-   [ ] Handle xpath besides regular selectors\n\n-   [ ] Separate the methods in the actions file in actions per Domain (see left menu here: \u003chttps://chromedevtools.github.io/devtools-protocol/tot/\u003e)\n\n-   [x] Allow adding new targets/tabs and controlling them at the same time (\u003chttps://github.com/cyrus-and/chrome-remote-interface#cdpnewoptions-callback\u003e and \u003chttps://github.com/cyrus-and/chrome-remote-interface/wiki/Inspect-a-new-tab\u003e). Thanks @iyttor ! This was a great contribution! :D \n\n-   [ ] Improve existing methods:\n    .getCookies - Should receive a cookie name and return only that one, or all the cookies if no key is specified\n\n-   [x] Bypass Certificate Errors (\u003chttps://github.com/cyrus-and/chrome-remote-interface/wiki/Bypass-certificate-errors-(%22Your-connection-is-not-private%22)\u003e) Thanks @trevan !\n\n-   [x] Add Target domain API\n    So we can create tabs: \u003chttps://chromedevtools.github.io/devtools-protocol/tot/Target/#method-createTarget\u003e\n\n### Tests\n\nI was thinking on using this HTML page to make all the tests: \u003chttps://github.com/cbracco/html5-test-page\u003e\n\nIt'd be great to have some unit tests for each HTML element; besides, those test may be useful examples for everyone.\n\n### More examples!!!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucianoganga%2Fsimple-headless-chrome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucianoganga%2Fsimple-headless-chrome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucianoganga%2Fsimple-headless-chrome/lists"}