All Projects → OnetapInc → Chromy

OnetapInc / Chromy

Licence: mit
Chromy is a library for operating headless chrome. 🍺🍺🍺

Programming Languages

javascript
184084 projects - #8 most used programming language

Projects that are alternatives of or similar to Chromy

Puppeteer Sharp Extra
Plugin framework for PuppeteerSharp
Stars: ✭ 39 (-93.42%)
Mutual labels:  chrome, browser, headless-chrome
Navalia
A bullet-proof, fast, and reliable headless browser API
Stars: ✭ 950 (+60.2%)
Mutual labels:  chrome, browser, headless-chrome
Nightmare
A high-level browser automation library.
Stars: ✭ 19,067 (+3115.35%)
Mutual labels:  chrome, browser, headless-chrome
Wrp
Web Rendering Proxy: Use vintage, historical, legacy browsers on modern web
Stars: ✭ 503 (-15.18%)
Mutual labels:  chrome, browser, headless-chrome
Searchwithmybrowser
Open Cortana searches with your default browser.
Stars: ✭ 285 (-51.94%)
Mutual labels:  chrome, browser
Hackbrowserdata
Decrypt passwords/cookies/history/bookmarks from the browser. 一款可全平台运行的浏览器数据导出解密工具。
Stars: ✭ 3,864 (+551.6%)
Mutual labels:  chrome, browser
Singlefile
Web Extension for Firefox/Chrome/MS Edge and CLI tool to save a faithful copy of an entire web page in a single HTML file
Stars: ✭ 4,417 (+644.86%)
Mutual labels:  chrome, browser
Copy As Markdown
Copying Link, Image and Tab(s) as Markdown Much Easier.
Stars: ✭ 332 (-44.01%)
Mutual labels:  chrome, browser
Supercookie
💭 Inspiration
Stars: ✭ 3,630 (+512.14%)
Mutual labels:  chrome, browser
Rawkit
🦊 Immediately Open Chrome DevTools when debugging Node.js apps
Stars: ✭ 306 (-48.4%)
Mutual labels:  chrome, browser
Extanalysis
Browser Extension Analysis Framework - Scan, Analyze Chrome, firefox and Brave extensions for vulnerabilities and intels
Stars: ✭ 351 (-40.81%)
Mutual labels:  chrome, browser
Headless Chrome Crawler
Distributed crawler powered by Headless Chrome
Stars: ✭ 5,129 (+764.92%)
Mutual labels:  chrome, headless-chrome
Browser Sec Whitepaper
Cure53 Browser Security White Paper
Stars: ✭ 251 (-57.67%)
Mutual labels:  chrome, browser
Adamantium Thief
🔑 Decrypt chromium based browsers passwords, cookies, credit cards, history, bookmarks, autofill. Version > 80 is supported.
Stars: ✭ 283 (-52.28%)
Mutual labels:  chrome, browser
Extension Create
Create modern cross-browser extensions with no build configuration.
Stars: ✭ 167 (-71.84%)
Mutual labels:  chrome, browser
Chrome Headless Browser Docker
Continuously building Chrome Docker image for Linux.
Stars: ✭ 323 (-45.53%)
Mutual labels:  chrome, headless-chrome
Puppeteer Lambda Starter Kit
Starter Kit for running Headless-Chrome by Puppeteer on AWS Lambda.
Stars: ✭ 563 (-5.06%)
Mutual labels:  chrome, headless-chrome
Scriptsafe
a browser extension to bring security and privacy to chrome, firefox, and opera
Stars: ✭ 434 (-26.81%)
Mutual labels:  chrome, browser
Puppeteer Extra
💯 Teach puppeteer new tricks through plugins.
Stars: ✭ 3,397 (+472.85%)
Mutual labels:  chrome, headless-chrome
Serverless Chrome
🌐 Run headless Chrome/Chromium on AWS Lambda
Stars: ✭ 2,625 (+342.66%)
Mutual labels:  chrome, headless-chrome

Chromy

Chromy is a library for operating headless chrome.

Document Site: https://onetapinc.github.io/chromy/

Chromy is similar to Nightmare.js but has some differences:

  • Controlling Chrome via Chrome DevTools Protocol.
  • Supports mobile emulation.
  • No need to prepare a screen such as xvfb.

Requirements

  • Node 6 or later
  • Install Chrome60 or later to your machine before use Chromy.

headless mode is supported by Chrome59 or later.

Installation

npm i chromy

Usage

const Chromy = require('chromy')

// not headless
// let chromy = new Chromy({visible:true})
let chromy = new Chromy()
chromy.chain()
      .goto('http://example.com/')
      .evaluate(() => {
        return document.querySelectorAll('*').length
      })
      .result((r) => console.log(r))
      .end()
      .then(() => chromy.close())

You can also use async/await interfaces like this:

const Chromy = require('chromy')

async function main () {
  let chromy = new Chromy()
  await chromy.goto('http://example.com/')
  const result = await chromy.evaluate(() => {
          return document.querySelectorAll('*').length
        })
  console.log(result)
  await chromy.close()
}

main()

Mobile Emulation

Chromy provides mobile emulation.
The emulation changes a screen resolution, density, userAgent and provides touch emulation.

const Chromy = require('chromy')

let chromy = new Chromy()
chromy.chain()
      .emulate('iPhone6')
      .goto('http://example.com/')
      .tap(100, 100) // emulate tap action by synthesizing touch events.
      .evaluate(() => {
        return navigator.userAgent
      })
      .result(console.log)
      .end()
      .then(() => chromy.close())

FAQ

FAQ

API

Chromy(options)
options
  • host(default: localhost): host address
  • port(default: 9222): --remote-debugging-port
  • userDataDir(default: null): Chrome profile path. This option can be used to persist an user profile.
  • launchBrowser(default: true): If you want chromy to attach to the Chrome instance that is already launched, set to false.
  • visible(default: false): If set to true, chrome is launched in visible mode. This option is not used if launchBrowser is false.
  • chromePath(default: null): This option is used to find out an executable of Chrome. If set to null, executable is selected automatically. This option is not used if launchBrowser is false.
  • enableExtensions(default: false): Enable extension loading. (Generally, this options is used with userDataDir option)
  • chromeFlags(default: []): These flags is passed to Chrome. Each flag must have a prefix string "--". This option is not used if launchBrowser is false.
  • waitTimeout(default: 30000): If wait() doesn't finish in the specified time WaitTimeoutError will be thrown.
  • gotoTimeout(default: 30000): If goto() doesn't finish in the specified time GotoTimeoutError will be thrown.
  • evaluateTimeout(default: 30000): If evaluate() doesn't finish in the specified time EvaluateTimeError will be thrown.
  • waitFunctionPollingInterval(default: 100): polling interval for wait().
  • typeInterval(default: 20): This option is used only in type() method.
  • activateOnStartUp(default: true): activate a first tab on startup. this option is enable only in visible mode.
.start(startingUrl = null)

Launches Chrome browser.

options

startingUrl: a staring url. If you set to null 'about:blank' is used as a starting url.

.goto(url, options = {})

Goes to url. If you have not called start(), this method calls start(url) automatically.

options

waitLoadEvent(default: true): If set to false, goto() doesn't wait until load event is fired.

returns

Returns Response object

.waitLoadEvent()

wait until a load event is fired.

.userAgent(ua)

set a useragent.

ua: new user agent.

Chromy.addCustomDevice(device)

add custom device definitions to emulate it.

See src.

.emulate(deviceName)

emulate a device that is defined by Chromy.addCustomDevice().

.forward()

go forward to the next page and wait until load event is fired.

.back()

go back to the previous page and wait until load event is fired.

.inject(type, file)

Injects a file into browser as a javascript or a css.

type: must be 'js' or 'css' file: injected file.

.evaluate(func|source, args)

Evaluates a expression in the browser context.
If the expression returns a Promise object, the promise is resolved automatically.

.result(func)

result() receives a result of previous directive.

chromy.chain()
      .goto('http://example.com')
      .evaluate(() => {
        return document.querySelectorAll('*').length
      })
      .result((length) => {
        // length is a result of evaluate() directive.
        console.log(length)
      }
      .end()
.end()
.exists(selector)

Returns whether an node matched with the selector is exists.

.visible(selector)

Returns whether an node matched with the selector is exists and visible.

.wait(msec)

alias for .sleep(msec)

.wait(selector)

wait until selector you specified appear in a DOM tree.

.wait(func)

wait until function you supplied is evaluated as true. func() executes in browser window context.

.sleep(msec)

wait for milli seconds you specified.

.type(selector, text)
.insert(selector, text)
.check(selector)
.uncheck(selector)
.select(selector, value)
.setFile(selector, files)

Sets the files to a file field that matches the selector.

  • selector: selector for specifying the file field.
  • files: The array or string value that represents a local file path.
.click(selector, options)
options

waitLoadEvent(default: false): If set to true, wait until load event is fired after click event is fired.

.mouseMoved(x, y, options = {})

Dispatch mousemoved event.

.mousePressed(x, y, options = {})

Dispatch mousedown event.

.mouseReleased(x, y, options = {})

Dispatch mouseup event.

.tap(x, y, options = {})

Synthesize tap by dispatching touch events. (NOTE: To dispatch touch events you need to enable a mobile emulation before.)

.doubleTap(x, y, options = {})

Synthesize double tap by dispatching touch events. (NOTE: To dispatch touch events you need to enable a mobile emulation before.)

.scroll(x, y)

Scrolls to the position. x and y means relative position.

.scrollTo(x, y)

Scrolls to the position. x and y means absolute position.

.rect(selector)

Returns a rect of the element specified by selector.

.rectAll(selector)

Returns an array of rects that is specified by selector.

.defineFunction(func)
function outerFunc () {
  return 'VALUE'
}
chromy.chain()
      .goto('http://example.com')
      .defineFunction(outerFunc)
      .evaluate(() => {
        outerFunc()
      })
      .end()
.send(eventName, parameter)

Calls DevTools protocol directly.

.on(eventName, listener)

Adds the listener function.

.once(eventName, listener)

Adds one time listener function.

.removeListener(eventName, listener)

Removes the listener function.

.removeAllListeners(eventName)

Removes all listener function.

.screenshot(options= {})

Exports a current screen as an image data.

See examples: examples/screenshot.js

options
  • format(default: 'png'): must be either 'png' or 'jpeg'
  • quality(default: 100): quality of image.
  • fromSurface(default: true): if set to true, take screenshot from surface.
  • useDeviceResolution(default: false): if set to true, the image will have same resolution with device.
.screenshotSelector(selector, options={})

Exports an area of selector you specified as an image data.

See examples: examples/screenshot.js

Note:

  • The size of target specified by selector must be smaller than viewport size. If not, image gets cropped.
  • It has a side-effect. After this api is called, scroll position is moved to target position.
options

See screenshot()

.screenshotMultipleSelectors(selectors, callback, options = {})

Takes multiple screenshot specified by selector at once. Each image can be received by callback.

Limitation:

Parameter
  • selectors: An array of selector
  • callback: function(error, image, index, selectors, subIndex)
    • error: error information.
    • image: image data
    • index: index of selectors.
    • subIndex: this value is used only if useQuerySelecotrAll is true.
  • options:
    • model: see explanation of screenDocument()
    • format: see explanation of screenshot()
    • quality: see explanation of screenshot()
    • fromSurface: see explanation of screenshot()
    • useQuerySelectorAll(default: false): If set to true, take all the screenshot of elements returned from document.querySelectorAll() (Since v 0.2.13)
.screenshotDocument(options = {})

Exports a entire document as an image data.

See examples: examples/screenshot.js

Limitation:

Known Issue:

  • When this api is called to take large page sometimes strange white area is appeared. This result is caused by --disable-flag option passed to Chrome. After chrome 60 is officially released I remove --disable-flag option to fix this problem.
options
  • model: this parameter affect page size. must be which one of: 'box', 'scroll'. 'box' means box model of body element. 'scroll' means size of scroll area.
  • format: see explanation of screenshot()
  • quality: see explanation of screenshot()
  • fromSurface: see explanation of screenshot()
.pdf(options={})

Exports a current page's printing image as a PDF data. This function is supported only in headless mode (since Chrome60).

See examples: examples/screenshot.js

Parameters
.startScreencast(callback, options = {})

Starts screencast to take screenshots by every frame.

See examples: examples/screencast.js

Parameter

callback: callback function for receiving parameters of screencastFrame event. See details here options: See details here.

.stopScreencast()

Stops screencast.

.console(func)
chromy.chain()
      .goto('http://example.com')
      .console((text) => {
        console.log(text)
      })
      .evaluate(() => {
        console.log('HEY')
      })
      .end()
.receiveMessage(func)

receive a message from browser.

You can communicate with a browser by using receiveMessage() and sendToChromy(). sendToChromy() is a special function to communicate with Chromy. When you call receiveMessage() at the first time, sendToChromy() is defined in a browser automatically. A listener function passed to receiveMessage() receives parameters when sendToChromy() is executed in a browser.

chromy.chain()
      .goto('http://example.com')
      .receiveMessage((msg) => {
        console.log(msg[0].value)
      })
      .evaluate(() => {
        sendToChromy({value: 'foo'})
      })
.ignoreCertificateErrors()

Ignores all certificate errors.

chromy.chain()
      .ignoreCertificateErrors()
      .goto('https://xxxxx/')
      .end()
.blockUrls(urls)

blocks urls from loading.

Parameter

urls: array[string]
Wildcard('*') is allowed in url string.

.clearBrowserCache()

Removes all browser caches.

.setCookie(params)
Parameters

params: object or array

See chrome document If url parameter is not set, current url(location.href) is used as default value.

.getCookies(name = null)
Parameters

name: string or array of string

See chrome document

.deleteCookie(name, url = null)

Remove a cookie.

Parameters

name: string or array of string url: url associated with cookie. If url is not set, current url(location.href) is used as default value.

.clearAllCookies()

Removes all browser cookies.

.clearDataForOrigin (origin = null, type = 'all')

Clear data for origin.(cookies, local_storage, indexedDb, etc...)

See details here.

.getDOMCounters()

Get count of these item: document, node, jsEventListeners

See details here.

.static cleanup()

close all browsers.

process.on('SIGINT', async () => {
  await Chromy.cleanup()
  process.exit(1)
})

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/OnetapInc/chromy

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].