puppeteer/lib/helper.js
Andrey Lushnikov 28d92116b7
feat(puppeteer): support convenience env variables (#3190)
We had (and still have) a ton of pull requests to support
PUPPETEER_EXECUTABLE_PATH and PUPPETEER_CHROMIUM_REVISION in puppeteer launcher.

We were hesitant before since env variables are not scoped
and thus don't make a good interface for a library. Now, since we
determined `puppeteer-core` as a library and `puppeteer` as our end-user
product, it's safe to satisfy our user needs.

This patch:
- teaches PUPPETEER_EXECUTABLE_PATH and PUPPETEER_CHROMIUM_REVISION
  env variables to control how Puppeteer launches browser
- makes sure these variables play no role in `puppeteer-core` package.
2018-09-05 22:59:14 +01:00

302 lines
9.2 KiB
JavaScript

/**
* Copyright 2017 Google Inc. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
const fs = require('fs');
const path = require('path');
const {TimeoutError} = require('./Errors');
const debugError = require('debug')(`puppeteer:error`);
/** @type {?Map<string, boolean>} */
let apiCoverage = null;
// Project root will be different for node6-transpiled code.
const projectRoot = fs.existsSync(path.join(__dirname, '..', 'package.json')) ? path.join(__dirname, '..') : path.join(__dirname, '..', '..');
const packageJson = require(path.join(projectRoot, 'package.json'));
class Helper {
/**
* @param {Function|string} fun
* @param {!Array<*>} args
* @return {string}
*/
static evaluationString(fun, ...args) {
if (Helper.isString(fun)) {
assert(args.length === 0, 'Cannot evaluate a string with arguments');
return /** @type {string} */ (fun);
}
return `(${fun})(${args.map(serializeArgument).join(',')})`;
/**
* @param {*} arg
* @return {string}
*/
function serializeArgument(arg) {
if (Object.is(arg, undefined))
return 'undefined';
return JSON.stringify(arg);
}
}
/**
* @param {string} name
* @return {(string|undefined)}
*/
static getEnv(name) {
// Ignore all PUPPETEER_* env variables in puppeteer-core package.
if (name.startsWith('PUPPETEER_') && packageJson.name === 'puppeteer-core')
return undefined;
return process.env[name];
}
/**
* @return {string}
*/
static projectRoot() {
return projectRoot;
}
/**
* @param {!Protocol.Runtime.ExceptionDetails} exceptionDetails
* @return {string}
*/
static getExceptionMessage(exceptionDetails) {
if (exceptionDetails.exception)
return exceptionDetails.exception.description || exceptionDetails.exception.value;
let message = exceptionDetails.text;
if (exceptionDetails.stackTrace) {
for (const callframe of exceptionDetails.stackTrace.callFrames) {
const location = callframe.url + ':' + callframe.lineNumber + ':' + callframe.columnNumber;
const functionName = callframe.functionName || '<anonymous>';
message += `\n at ${functionName} (${location})`;
}
}
return message;
}
/**
* @param {!Protocol.Runtime.RemoteObject} remoteObject
* @return {*}
*/
static valueFromRemoteObject(remoteObject) {
assert(!remoteObject.objectId, 'Cannot extract value when objectId is given');
if (remoteObject.unserializableValue) {
switch (remoteObject.unserializableValue) {
case '-0':
return -0;
case 'NaN':
return NaN;
case 'Infinity':
return Infinity;
case '-Infinity':
return -Infinity;
default:
throw new Error('Unsupported unserializable value: ' + remoteObject.unserializableValue);
}
}
return remoteObject.value;
}
/**
* @param {!Puppeteer.CDPSession} client
* @param {!Protocol.Runtime.RemoteObject} remoteObject
*/
static async releaseObject(client, remoteObject) {
if (!remoteObject.objectId)
return;
await client.send('Runtime.releaseObject', {objectId: remoteObject.objectId}).catch(error => {
// Exceptions might happen in case of a page been navigated or closed.
// Swallow these since they are harmless and we don't leak anything in this case.
debugError(error);
});
}
/**
* @param {!Object} classType
* @param {string=} publicName
*/
static tracePublicAPI(classType, publicName) {
let className = publicName || classType.prototype.constructor.name;
className = className.substring(0, 1).toLowerCase() + className.substring(1);
const debug = require('debug')(`puppeteer:${className}`);
if (!debug.enabled && !apiCoverage)
return;
for (const methodName of Reflect.ownKeys(classType.prototype)) {
const method = Reflect.get(classType.prototype, methodName);
if (methodName === 'constructor' || typeof methodName !== 'string' || methodName.startsWith('_') || typeof method !== 'function')
continue;
if (apiCoverage)
apiCoverage.set(`${className}.${methodName}`, false);
Reflect.set(classType.prototype, methodName, function(...args) {
const argsText = args.map(stringifyArgument).join(', ');
const callsite = `${className}.${methodName}(${argsText})`;
if (debug.enabled)
debug(callsite);
if (apiCoverage)
apiCoverage.set(`${className}.${methodName}`, true);
return method.call(this, ...args);
});
}
if (classType.Events) {
if (apiCoverage) {
for (const event of Object.values(classType.Events))
apiCoverage.set(`${className}.emit(${JSON.stringify(event)})`, false);
}
const method = Reflect.get(classType.prototype, 'emit');
Reflect.set(classType.prototype, 'emit', function(event, ...args) {
const argsText = [JSON.stringify(event)].concat(args.map(stringifyArgument)).join(', ');
if (debug.enabled && this.listenerCount(event))
debug(`${className}.emit(${argsText})`);
if (apiCoverage && this.listenerCount(event))
apiCoverage.set(`${className}.emit(${JSON.stringify(event)})`, true);
return method.call(this, event, ...args);
});
}
/**
* @param {!Object} arg
* @return {string}
*/
function stringifyArgument(arg) {
if (Helper.isString(arg) || Helper.isNumber(arg) || !arg)
return JSON.stringify(arg);
if (typeof arg === 'function') {
let text = arg.toString().split('\n').map(line => line.trim()).join('');
if (text.length > 20)
text = text.substring(0, 20) + '…';
return `"${text}"`;
}
const state = {};
const keys = Object.keys(arg);
for (const key of keys) {
const value = arg[key];
if (Helper.isString(value) || Helper.isNumber(value))
state[key] = JSON.stringify(value);
}
const name = arg.constructor.name === 'Object' ? '' : arg.constructor.name;
return name + JSON.stringify(state);
}
}
/**
* @param {!NodeJS.EventEmitter} emitter
* @param {string} eventName
* @param {function(?)} handler
* @return {{emitter: !NodeJS.EventEmitter, eventName: string, handler: function(?)}}
*/
static addEventListener(emitter, eventName, handler) {
emitter.on(eventName, handler);
return { emitter, eventName, handler };
}
/**
* @param {!Array<{emitter: !NodeJS.EventEmitter, eventName: string, handler: function(?)}>} listeners
*/
static removeEventListeners(listeners) {
for (const listener of listeners)
listener.emitter.removeListener(listener.eventName, listener.handler);
listeners.splice(0, listeners.length);
}
/**
* @return {?Map<string, boolean>}
*/
static publicAPICoverage() {
return apiCoverage;
}
static recordPublicAPICoverage() {
apiCoverage = new Map();
}
/**
* @param {!Object} obj
* @return {boolean}
*/
static isString(obj) {
return typeof obj === 'string' || obj instanceof String;
}
/**
* @param {!Object} obj
* @return {boolean}
*/
static isNumber(obj) {
return typeof obj === 'number' || obj instanceof Number;
}
static promisify(nodeFunction) {
function promisified(...args) {
return new Promise((resolve, reject) => {
function callback(err, ...result) {
if (err)
return reject(err);
if (result.length === 1)
return resolve(result[0]);
return resolve(result);
}
nodeFunction.call(null, ...args, callback);
});
}
return promisified;
}
/**
* @param {!NodeJS.EventEmitter} emitter
* @param {string} eventName
* @param {function} predicate
* @return {!Promise}
*/
static waitForEvent(emitter, eventName, predicate, timeout) {
let eventTimeout, resolveCallback, rejectCallback;
const promise = new Promise((resolve, reject) => {
resolveCallback = resolve;
rejectCallback = reject;
});
const listener = Helper.addEventListener(emitter, eventName, event => {
if (!predicate(event))
return;
cleanup();
resolveCallback(event);
});
if (timeout) {
eventTimeout = setTimeout(() => {
cleanup();
rejectCallback(new TimeoutError('Timeout exceeded while waiting for event'));
}, timeout);
}
function cleanup() {
Helper.removeEventListeners([listener]);
clearTimeout(eventTimeout);
}
return promise;
}
}
/**
* @param {*} value
* @param {string=} message
*/
function assert(value, message) {
if (!value)
throw new Error(message);
}
module.exports = {
helper: Helper,
assert,
debugError
};