• This repository has been archived on 24/Nov/2018
  • Stars
    star
    13,240
  • Rank 2,365 (Top 0.05 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 7 years ago
  • Updated about 6 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

πŸ–₯ Chrome automation made simple. Runs locally or headless on AWS Lambda.

This project is deprecated in favor for Puppeteer. Thanks to all the contributors who made this project possible.

Chromeless

npm downloads circleci codecov dependencies node semantic-release

Chrome automation made simple. Runs locally or headless on AWS Lambda. (See Demo)

Chromeless can be used to...

  • Run 1000s of browser integration tests in parallel ⚑️
  • Crawl the web & automate screenshots
  • Write bots that require a real browser
  • Do pretty much everything you've used PhantomJS, NightmareJS or Selenium for before

Examples

▢️ Try it out

You can try out Chromeless and explore the API in the browser-based demo playground (source).

Contents

  1. How it works
  2. Installation
  3. Usage
  4. API Documentation
  5. Configuring Development Environment
  6. FAQ
  7. Contributors
  8. Credits
  9. Help & Community

How it works

With Chromeless you can control Chrome (open website, click elements, fill out forms...) using an elegant API. This is useful for integration tests or any other scenario where you'd need to script a real browser.

There are 2 ways to use Chromeless

  1. Running Chrome on your local computer
  2. Running Chrome on AWS Lambda and controlling it remotely

1. Local Setup

For local development purposes where a fast feedback loop is necessary, the easiest way to use Chromeless is by controlling your local Chrome browser. Just follow the usage guide to get started.

2. Remote Proxy Setup

You can also run Chrome in headless-mode on AWS Lambda. This way you can speed up your tests by running them in parallel. (In Graphcool's case this decreased test durations from ~20min to a few seconds.)

Chromeless comes out of the box with a remote proxy built-in - the usage stays completely the same. This way you can write and run your tests locally and have them be executed remotely on AWS Lambda. The proxy connects to Lambda through a Websocket connection to forward commands and return the evaluation results.

Installation

npm install chromeless

Proxy Setup

The project contains a Serverless service for running and driving Chrome remotely on AWS Lambda.

  1. Deploy The Proxy service to AWS Lambda. More details here
  2. Follow the usage instructions here.

Usage

Using Chromeless is similar to other browser automation tools. For example:

const { Chromeless } = require('chromeless')

async function run() {
  const chromeless = new Chromeless()

  const screenshot = await chromeless
    .goto('https://www.google.com')
    .type('chromeless', 'input[name="q"]')
    .press(13)
    .wait('#resultStats')
    .screenshot()

  console.log(screenshot) // prints local file path or S3 url

  await chromeless.end()
}

run().catch(console.error.bind(console))

Local Chrome Usage

To run Chromeless locally, you need a recent version of Chrome or Chrome Canary installed (version 60 or greater). By default, chromeless will start Chrome automatically and will default to the most recent version found on your system if there's multiple. You can override this behavior by starting Chrome yourself, and passing a flag of launchChrome: false in the Chromeless constructor.

To launch Chrome yourself, and open the port for chromeless, follow this example:

alias canary="/Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary"
canary --remote-debugging-port=9222

Or run Chrome Canary headless-ly:

canary --remote-debugging-port=9222 --disable-gpu --headless

Or run Chrome headless-ly on Windows:

cd "C:\Program Files (x86)\Google\Chrome\Application"
chrome --remote-debugging-port=9222 --disable-gpu --headless

Proxy Usage

Follow the setup instructions here.

Then using Chromeless with the Proxy service is the same as running it locally with the exception of the remote option. Alternatively you can configure the Proxy service's endpoint with environment variables. Here's how.

const chromeless = new Chromeless({
  remote: {
    endpointUrl: 'https://XXXXXXXXXX.execute-api.eu-west-1.amazonaws.com/dev',
    apiKey: 'your-api-key-here',
  },
})

API Documentation

Chromeless constructor options

Chromeless methods

Chrome methods

Configuring Development Environment

Requirements:

  • NodeJS version 8.2 and greater
  1. Clone this repository
  2. Run npm install
  3. To build: npm run build

Linking this NPM repository

  1. Go to this repository locally
  2. Run npm link
  3. Go to the folder housing your chromeless scripts
  4. Run npm link chromeless

Now your local chromeless scripts will use your local development of chromeless.

FAQ

How is this different from NightmareJS, PhantomJS or Selenium?

The Chromeless API is very similar to NightmareJS as their API is pretty awesome. The big difference is that Chromeless is based on Chrome in headless-mode, and runs in a serverless function in AWS Lambda. The advantage of this is that you can run hundreds of browsers in parallel, without having to think about parallelisation. Running integration Tests for example is much faster.

I'm new to AWS Lambda, is this still for me?

You still can use this locally without Lambda, so yes. Besides that, here is a simple guide on how to set the lambda function up for Chromeless.

How much does it cost to run Chromeless in production?

The compute price is $0.00001667 per GB-s and the free tier provides 400,000 GB-s. The request price is $0.20 per 1 million requests and the free tier provides 1M requests per month.

This means you can easily execute > 100.000 tests for free in the free tier.

Are there any limitations?

If you're running Chromeless on AWS Lambda, the execution cannot take longer than 5 minutes which is the current limit of Lambda. Besides that, every feature that's supported in Chrome is also working with Chromeless. The maximal number of concurrent function executions is 1000. AWS API Limits

Are there commercial options?

Although Chromeless is the easiest way to get started running Chrome on Lambda, you may not have time to build and manage your own visual testing toolkit. Commercial options include:

Troubleshooting

Error: Unable to get presigned websocket URL and connect to it.

In case you get an error like this when running the Chromeless client:

{ HTTPError: Response code 403 (Forbidden)
    at stream.catch.then.data (/code/chromeless/node_modules/got/index.js:182:13)
    at process._tickDomainCallback (internal/process/next_tick.js:129:7)
  name: 'HTTPError',
...
Error: Unable to get presigned websocket URL and connect to it.

Make sure that you're running at least version 1.19.0 of serverless. It is a known issue, that the API Gateway API keys are not setup correctly in older Serverless versions. Best is to run npm run deploy within the project as this will use the local installed version of serverless.

Resource ServerlessDeploymentBucket does not exist for stack chromeless-serverless-dev

In case the deployment of the serverless function returns an error like this:

  Serverless Error ---------------------------------------

  Resource ServerlessDeploymentBucket does not exist for stack chromeless-serverless-dev

Please check, that there is no stack with the name chromeless-serverless-dev existing yet, otherwise serverless can't correctly provision the bucket.

No command gets executed

In order for the commands to be processed, make sure, that you call one of the commands screenshot, evaluate, cookiesGetAll or end at the end of your execution chain.

Contributors

A big thank you to all contributors and supporters of this repository πŸ’š

joelgriffith adieuadieu schickling timsuchanek Chrisgozd criticalbh d2s emeth- githubixx hax Hazealign joeyvandijk liady matthewmueller seangransee sorenbs toddwprice vladgolubev

Credits

Help & Community Slack Status

Join our Slack community if you run into issues or have questions. We love talking to you!

Prisma

More Repositories

1

dockerfiles

Collection of lightweight and ready-to-use docker images
Shell
835
star
2

gulp-webserver

Streaming gulp plugin to run a local webserver with LiveReload
JavaScript
356
star
3

laravel-backup

Backup and restore database support for Laravel 4 applications
PHP
351
star
4

docker-hook

Automatic Docker Deployment via Webhooks
Python
257
star
5

git-s3

Easy way to deploy your git repo to an AWS S3 bucket
PHP
228
star
6

Device.swift

Super-lightweight library to detect used device
Swift
220
star
7

timemachine

Test your time-dependent app by monkey patching the Date function and overriding your system time.
JavaScript
133
star
8

calculate-size

Calculate the pixel size (width/height) of a string (with integrated caching)
TypeScript
121
star
9

awesome-local-first

A collection of awesome local-first projects including offline-first and collaboration functionality
93
star
10

beanstalkd-cli

Simple to use commandline tool for Beanstalkd
Rust
71
star
11

dotfiles

Contents of my ~/.config
Nix
63
star
12

rust-beanstalkd

Easy-to-use beanstalkd client for Rust (IronMQ compatible)
Rust
46
star
13

vim-bufonly

Delete all the buffers except the current buffer.
Vim Script
40
star
14

laravel-cash

Simple to use cache layer for your laravel application using memcached & nginx.
PHP
34
star
15

three-vr

Device controls and render steps for mobile virtual reality applications
JavaScript
30
star
16

laravel-queue-checker

Command to check the queue health status
PHP
26
star
17

Icomoon.swift

Use your Icomoon fonts with Swift - auto-generates type safe enums for each icon
Swift
26
star
18

fps-meter

TypeScript
18
star
19

gulp-webserver-article

Code examples for "Gulp as a (development) webserver"
JavaScript
17
star
20

colorrado

Beautiful color gradients based on images
TypeScript
15
star
21

local-first-landscape

A resource to learn about and compare tools in the local-first landscape
11
star
22

rust-examples

Rust examples in order to learn the language
Rust
11
star
23

zipcoder

Get zipcode, city and country for given coordinates or user location
JavaScript
11
star
24

jquery-rotate

Very lightweight jquery rotate plugin using CSS 3 Transformation
JavaScript
11
star
25

figma-plugin-code-syntax-highlighting

TypeScript
11
star
26

immersive

Virtual room tour using Google Cardboard
JavaScript
8
star
27

opentelemetry

8
star
28

algorithms

Implementation of several algorithms in Javascript
JavaScript
8
star
29

coroni

🦠
TypeScript
8
star
30

laravel-validators

A set of additional validator rules for Laravel 4
PHP
7
star
31

crawl-notifier

Crawl any website and get notified via mail when changes occur
JavaScript
5
star
32

graphql-summit-demo

TypeScript
4
star
33

react-figma-tailwind

JavaScript
4
star
34

dunkelziffer

News crawler for the deep web
JavaScript
4
star
35

crud-codegen

TypeScript
3
star
36

challenges

Coding challenges - talk about solutions
Python
3
star
37

graphql-delegate-subscriptions-example

TypeScript
3
star
38

angular-coordinate

Coordiante system for AngularJS
JavaScript
3
star
39

laravel-schema-summary

Creates a summary file of all migrations
2
star
40

es-producthunt

TypeScript
2
star
41

hackrisk-calm-app

iPhone + Apple Watch App to detect and avoid stressful situations
Swift
2
star
42

base-konfik

Base configuration files for Konfik
TypeScript
2
star
43

contentlayer-blog-2

Jamstack site created with Stackbit
TypeScript
1
star
44

relay-compiler-bug

Minimal reproduction of the recursive input type bug in relay-compiler
JavaScript
1
star
45

codenames

Codenames Game built as React-Native app
JavaScript
1
star
46

slides

Slides for my talks
JavaScript
1
star