add option to override the default browser/puppeteer instances

closes #2

Author: bartveneman

package.json

@@ -46,8 +46,10 @@
   },
   "devDependencies": {
     "ava": "^1.3.1",
+    "chromium": "^2.1.0",
     "create-test-server": "^2.4.0",
     "prettier": "^1.16.4",
+    "puppeteer-core": "^1.13.0",
     "xo": "^0.24.0"
   },
   "dependencies": {

readme.md

@@ -65,20 +65,41 @@ String.
 
 Type: `Object`
 
+Default: `null`
+
 #### debug
 
-Type: `Boolean` Default: `false`
+Type: `Boolean`
+
+Default: `false`
 
 Set to `true` if you want a Chromium window to open as it works to get all the
 CSS from the page.
 
 #### waitUntil
 
-Type: `String` Default: `networkidle2`
+Type: `String`
+
+Default: `networkidle2`
 
 Can be any value as provided by the
 [Puppeteer docs](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagegotourl-options).
 
+#### browserOverride
+
+Type: `Object`
+
+Default: `null`
+
+An object consisting of the following fields:
+
+- `executablePath`: the path to a Chromium binary
+- `puppeteer`: a Puppeteer instance
+- `args`: arguments to start Chromium with
+
+See the `test` directory for implementation examples. This option exists
+primarily for use with [extract-css.now.sh](https://extract-css.now.sh)
+
 ## Related
 
 - [extract-css lambda](https://github.com/bartveneman/extract-css) - Extract CSS

src/index.js

@@ -1,4 +1,5 @@
 const puppeteer = require('puppeteer')
+const {validateBrowserOverride} = require('./validate')
 
 function InvalidUrlError({url, statusCode, statusText}) {
 	this.name = 'InvalidUrlError'
@@ -9,12 +10,27 @@ InvalidUrlError.prototype = Error.prototype
 
 module.exports = async (
 	url,
-	{debug = false, waitUntil = 'networkidle2'} = {}
+	{debug = false, waitUntil = 'networkidle2', browserOverride = null} = {}
 ) => {
+	// Basic validation for browserOverride
+	if (browserOverride !== null) {
+		validateBrowserOverride(browserOverride)
+	}
+
+	// Setup the minimal browser options that we need to launch
+	const browserOptions = {
+		headless: debug !== true,
+		executablePath: browserOverride
+			? browserOverride.executablePath
+			: puppeteer.executablePath(),
+		args: browserOverride ? browserOverride.args : []
+	}
+
 	// Setup a browser instance
-	const browser = await puppeteer.launch({
-		headless: debug !== true
-	})
+	const browser = await (
+		(browserOverride && browserOverride.puppeteer) ||
+		puppeteer
+	).launch(browserOptions)
 
 	// Create a new page and navigate to it
 	const page = await browser.newPage()

src/validate.js

@@ -0,0 +1,28 @@
+function InvalidBrowserOverrideError(message) {
+	this.name = 'InvalidBrowserOverrideError'
+	this.message = `BrowserOverride is not valid. ${message} https://github.com/bartveneman/extract-css-core#options`
+}
+
+InvalidBrowserOverrideError.prototype = Error.prototype
+
+exports.validateBrowserOverride = ({executablePath, args, puppeteer}) => {
+	if (typeof executablePath !== 'string') {
+		throw new InvalidBrowserOverrideError(
+			`Check that executablePath is a valid string, got "${JSON.stringify(
+				executablePath
+			)}"`
+		)
+	}
+
+	if (!Array.isArray(args)) {
+		throw new InvalidBrowserOverrideError('Check that args is an Array.')
+	}
+
+	if (typeof puppeteer.launch !== 'function') {
+		throw new InvalidBrowserOverrideError(
+			'Check that puppeteer.launch is a function.'
+		)
+	}
+
+	return true
+}

test/index.js

@@ -2,6 +2,9 @@ const test = require('ava')
 const createTestServer = require('create-test-server')
 const {readFileSync} = require('fs')
 const {resolve} = require('path')
+const chromium = require('chromium')
+const puppeteerCore = require('puppeteer-core')
+
 const extractCss = require('..')
 
 let server
@@ -113,19 +116,22 @@ test('it rejects on an invalid url', async t => {
 	await t.throwsAsync(extractCss('site.example'))
 })
 
-// TODO: write coverage for dynamically inserted style tags
-test.skip('it finds CSS-in-JS (styled components)', async t => {
-	const path = '/css-in-js'
-	const cssInJsExampleHtml = readFileSync(
-		resolve(__dirname, 'css-in-js.html'),
+test('it accepts a browser override for usage with other browsers', async t => {
+	const path = '/browser-override'
+	const kitchenSinkExample = readFileSync(
+		resolve(__dirname, 'kitchen-sink.html'),
 		'utf8'
 	)
 	server.get(path, (req, res) => {
-		res.send(cssInJsExampleHtml)
+		res.send(kitchenSinkExample)
+	})
+	const actual = await extractCss(server.url + path, {
+		browserOverride: {
+			executablePath: chromium.path,
+			puppeteer: puppeteerCore,
+			args: []
+		}
 	})
 
-	const actual = await extractCss(server.url + path)
-	const expected = 'lots of JS generated classNames and styles'
-
-	t.is(actual, expected)
+	t.snapshot(actual)
 })

test/snapshots/index.js.md

@@ -4,7 +4,7 @@ The actual snapshot is saved in `index.js.snap`.
 
 Generated by [AVA](https://ava.li).
 
-## it accepts a custom Chrome and Puppeteer version for use on AWS
+## it combines server generated <link> and <style> tags with client side created <link> and <style> tags
 
 > Snapshot 1
 
@@ -18,7 +18,21 @@ Generated by [AVA](https://ava.li).
     				counter-increment: 2;␊
     			}.js-style { counter-increment: 3; }`
 
-## it combines server generated <link> and <style> tags with client side created <link> and <style> tags
+## it finds CSS-in-JS (styled components)
+
+> Snapshot 1
+
+    `body {␊
+    	color: teal;␊
+    }␊
+    body {␊
+    	color: teal;␊
+    }␊
+    .server-style {␊
+    				counter-increment: 2;␊
+    			}.js-style { counter-increment: 3; }`
+
+## it accepts a browser override for usage with other browsers
 
 > Snapshot 1
 

test/snapshots/index.js.snap

@@ -0,0 +1,66 @@
+const test = require('ava')
+const extractCss = require('..')
+const {validateBrowserOverride} = require('../src/validate')
+
+test('it does basic validation on browserOverride', t => {
+	const failures = [
+		{},
+		{executablePath: null},
+		{executablePath: ''},
+		{
+			puppeteer: null
+		},
+		{puppeteer: {}},
+		{puppeteer: {launch: null}}
+	]
+	const successes = [
+		{
+			executablePath: '/path/to/chromium',
+			puppeteer: {launch: () => {}},
+			args: []
+		}
+	]
+
+	failures.forEach(failure => {
+		t.throws(() => validateBrowserOverride(failure))
+	})
+	successes.forEach(success =>
+		t.notThrows(() => validateBrowserOverride(success))
+	)
+})
+
+test('it does basic validation on the browserOverride option', async t => {
+	await t.throwsAsync(
+		extractCss('http://google.com', {
+			browserOverride: {
+				executablePath: null
+			}
+		}),
+		{
+			message:
+				'BrowserOverride is not valid. Check that executablePath is a valid string, got "null" https://github.com/bartveneman/extract-css-core#options'
+		}
+	)
+	await t.throwsAsync(
+		extractCss('http://google.com', {
+			browserOverride: {
+				puppeteer: null
+			}
+		}),
+		{
+			message:
+				'BrowserOverride is not valid. Check that executablePath is a valid string, got "undefined" https://github.com/bartveneman/extract-css-core#options'
+		}
+	)
+	await t.throwsAsync(
+		extractCss('http://google.com', {
+			browserOverride: {
+				args: null
+			}
+		}),
+		{
+			message:
+				'BrowserOverride is not valid. Check that executablePath is a valid string, got "undefined" https://github.com/bartveneman/extract-css-core#options'
+		}
+	)
+})