# chromy-sharpless

> The library for manipulating headless chrome with Nightmare.js like API.

Latest version **0.4.0** (published 2017-07-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install chromy-sharpless
pnpm add chromy-sharpless
yarn add chromy-sharpless
bun add chromy-sharpless
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2017-07-23 |
| First published | 2017-07-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Known vulnerabilities | 0 (+2 in 2 direct dependencies) |
| Install scripts | no |
| Author | shinji |
| Maintainers | mistereo |

## Links

- npm: https://www.npmjs.com/package/chromy-sharpless
- npm.io page: https://npm.io/package/chromy-sharpless

## Dependencies (4)

- [uuid](https://npm.io/package/uuid.md) ^3.0.1
- [chrome-launcher](https://npm.io/package/chrome-launcher.md) ^0.3.1
- [async-chain-proxy](https://npm.io/package/async-chain-proxy.md) ^0.1.5
- [chrome-remote-interface](https://npm.io/package/chrome-remote-interface.md) ^0.23.2

## Recent versions

- 0.4.0 (latest) — 2017-07-23
- 0.3.6 — 2017-07-23

## README

# Chromy without sharp (and some features) as dependency

For personal use, please prefer original [Chromy](https://github.com/OnetapInc/chromy).

Chromy is a library for operating headless chrome.

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 Chrome59 or later to your machine before use Chromy.

headless mode is supported by Chrome59 or later.

## Installation

```bash
npm i chromy
```

## Usage

```js
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:

```js
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.

```js
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](https://github.com/OnetapInc/chromy/wiki/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 Chrome that is already launched, set to true.
 - 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.
 - 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 threw.
 - gotoTimeout(default: 30000): If goto() doesn't finish in the specified time GotoTimeoutError will be threw.
 - evaluateTimeout(default: 30000): If evaluate() doesn't finish in the specified time EvaluateTimeError will be threw.
 - 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.

##### .waitLoadEvent()

wait until a load event is fired.

##### .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)

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.

```js
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.

##### .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.)

##### .defineFunction(func)

```js
function outerFunc () {
  return 'VALUE'
}
chromy.chain()
      .goto('http://example.com')
      .defineFunction(outerFunc)
      .evaluate(() => {
        outerFunc()
      })
      .end()
```

##### .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](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.

##### .screenshotDocument(options = {})

Exports a entire document as an image data.

See examples: [examples/screenshot.js](examples/screenshot.js)

Limitation:
  - Cannot take a screenshot of an area under 16384px.
    Detail: https://groups.google.com/a/chromium.org/d/msg/headless-dev/DqaAEXyzvR0/P9zmTLMvDQAJ

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](examples/screenshot.js)

###### Parameters

 - options: See [devtools protocol](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF)

##### .startScreencast(callback, options = {})

Starts screencast to take screenshots by every frame.

See examples: [examples/screencast.js](examples/screenshot.js)

###### Parameter

callback: callback function for receiving parameters of screencastFrame event. See details [here](https://chromedevtools.github.io/devtools-protocol/tot/Page/#event-screencastFrame)
options: See details [here](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-startScreencast).

##### .stopScreencast()

Stops screencast.

##### .console(func)

```js
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.


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

##### 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](https://chromedevtools.github.io/devtools-protocol/tot/Network/#method-setCookie)
If url parameter is not set, current url(location.href) is used as default value.

##### 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](https://chromedevtools.github.io/devtools-protocol/tot/Storage/#method-clearDataForOrigin).

##### getDOMCounters()

Get count of these item: document, node, jsEventListeners

See details [here](https://chromedevtools.github.io/devtools-protocol/tot/Memory/#method-getDOMCounters).

##### static cleanup()

close all browsers.

```js
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

---
_Source: https://npm.io/package/chromy-sharpless · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._