vivocha/hands-free-chrome

Name: hands-free-chrome

Owner: Vivocha

Description: Headless Chrome utilities

Created: 2017-06-09 13:41:12.0

Updated: 2017-09-13 11:33:03.0

Pushed: 2017-11-10 03:51:09.0

Homepage: null

Size: 105

Language: JavaScript

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

Hands-free Chrome

Headless Chrome utilities.

travis build Coverage Status npm version Commitizen friendly

Current included features:

Prerequisites

Chrome version > 59.x must be installed.

WARNING: due to a known bug of Chrome 59 on macOS closing tabs doesn't work properly on that platform. See API documentation below for more info.

Node.js version > 8.1.0

Quick Start
m install hands-free-chrome

then:

t HandsfreeChrome = require('hands-free-chrome');

chrome = new HandsfreeChrome();

pture a screenshot as png
me.captureScreenshot('<A VALID WEB PAGE URL>')
hen(name => console.log(`Created file: ${name}.png`))
atch(err => console.log(err));
API

new HandsfreeChrome( [options] )

Constructor.

Instantiate a new HandsFreeChrome.

options is an optional object with the following properties:

HandsfreeChrome # captureScreenshot(url, [options])

Capture a screenshot of a web page and create image files.

Params:

HandsfreeChrome # captureScreenshotAsStream(url, [options])

Capture a screenshot of a web page and return a data readable stream.

Params:

HandsfreeChrome # captureScreenshotAsStreamByTab(url, [options])

Capture a screenshot of a web page opening and closing a new browser tab and return a data readable stream.

WARNING: due to a known bug of Chrome 59 on macOS closing tabs doesn't work properly on that platform. To use this method please use Linux or Docker ;)

Params:

HandsfreeChrome # resizePng(pngStream, [size])

Resize a png image given its stream and a size.

Params:

Metrics Object

Metrics Object specifies some configuration options for Headless Chrome, like the browser window size, mobile emulation and so on. See Chrome DevTools Protocol page for more info.

Supported params are:

dth: number;
ight: number;
viceScaleFactor: (optional) number;
bile: (optional) boolean;
tWindow: (optional) boolean;

If metrics param is not specified or undefined in the above methods calls, then it defaults to: DesktopScreenMetrics, set as follows:


dth: 1920,
ight: 1080,
viceScaleFactor: 0,
bile: false,
tWindow: false
Web API Server

A Web API Server is now included in the package in order to expose the lib as Microservice.

After installing the npm package, running:

de ./node_modules/hands-free-chrome/dist/api

it starts a HTTP server at localhost, default port: 8000.

To start the API server listening at a different port, just set the PORT environment variable.

To start the underlying Headless Chrome instance at a different port, set the CHROME_PORT environment variable (default is 9222).

Example:

RT=8080 node ./node_modules/hands-free-chrome/dist/api
Endpoints

POST /screenshots/actions/capture

Sends a request to capture a screenshot. It returns a response with a base64 encoded stream body with Content-Type equal to image/png or application/pdf.

POST body must be a JSON object with the following properties:

Example:


rl": "https://en.wikipedia.org/wiki/Node.js",
ype": "png"

GET /screenshots/{url}[?thumbnail=width,height]

Gets a screenshot thumbnail for the specified url path parameter. It returns a response with a base64 encoded stream body with Content-Type equal to image/png. The thumbnail will have the size specified by the thumbnail query param.

Path parameter is:

Query parameter is:

Example:

 --request GET \
url 'http://<your-server>/screenshots/http%3A%2F%2Fwww.corriere.it?thumbnail=160%2C100' \
header 'content-type: application/json'

Docker

Thanks to the provided Dockerfile it is possible to run this component + API server as a Microservice, exposing the Web API endopoints listed above.

In order to “dockerize” the microservice, from the project root directory:

  1. build the image:
cker build -t vvc/hfchrome .
  1. run the container (as default, API server is configured to listen at port 8000, see Dockerfile):
cker run --name hfc -p 8000:8000 -d --privileged vvc/hfchrome

Docker Compose

This project also includes a Docker Compose configuration in order to launch a composition of 3 microservices, as follows:

Docker Microservices

To execute composed services, run the following commands in the project root directory:

cker-compose build
cker-compose up -d

NGINX is configured to listen at port 8000, exposed APIs are the same as described above.

License - “MIT License”

Copyright (c) 2017 Vivocha S.p.A.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.