povils/chromeless

🖥 Chrome automation made simple. Runs locally or headless on AWS Lambda.

Chromeless

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

• JSON of Google Results: Google for chromeless and get a list of JSON results
• Screenshot of Google Results: Google for chromeless and take a screenshot of the results
• prep: Compile-time prerendering for SPA/PWA (like React, Vue...) instead of server-side rendering (SSR)
• See the full examples list for more

▶️ 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. FAQ
6. Contributors
7. Credits
8. 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 and running.

For example, on MacOS:

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

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 methods

• end()

Chrome methods

• goto(url: string)
• click(selector: string)
• wait(timeout: number)
• wait(selector: string)
• wait(fn: (...args: any[]) => boolean, ...args: any[])
• focus(selector: string)
• press(keyCode: number, count?: number, modifiers?: any)
• type(input: string, selector?: string)
• back() - Not implemented yet
• forward() - Not implemented yet
• refresh() - Not implemented yet
• mousedown() - Not implemented yet
• mouseup() - Not implemented yet
• scrollTo(x: number, y: number)
• viewport(width: number, height: number)
• evaluate<U extends any>(fn: (...args: any[]) => void, ...args: any[])
• inputValue(selector: string)
• exists(selector: string)
• screenshot()
• pdf() - Not implemented yet
• cookiesGet()
• cookiesGet(name: string)
• cookiesGet(query: CookieQuery) - Not implemented yet
• cookiesGetAll()
• cookiesSet(name: string, value: string)
• cookiesSet(cookie: Cookie)
• cookiesSet(cookies: Cookie[])
• cookiesClear(name: string)
• cookiesClearAll()

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

Contributors

A big thank you to all contributors and supporters of this repository 💚

Credits

• chrome-remote-interface: Chromeless uses this package as an interface to Chrome
• serverless-chrome: Compiled Chrome binary that runs on AWS Lambda (Azure and GCP soon, too.)
• NightmareJS: We draw a lot of inspiration for the API from this great tool

Help & Community

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