logging.js

// Licensed to the Software Freedom Conservancy (SFC) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The SFC licenses this file
// to you 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.

/**
 * @fileoverview Defines WebDriver's logging system. The logging system is
 * broken into major components: local and remote logging.
 *
 * The local logging API, which is anchored by the
 * {@link webdriver.logging.Logger Logger} class, is similar to Java's
 * logging API. Loggers, retrieved by {@link webdriver.logging.getLogger}, use
 * hierarchical, dot-delimited namespaces
 * (e.g. "" > "webdriver" > "webdriver.logging"). Recorded log messages are
 * represented by the {@link webdriver.logging.LogRecord LogRecord} class. You
 * can capture log records by
 * {@linkplain webdriver.logging.Logger#addHandler attaching} a handler function
 * to the desired logger. For convenience, you can quickly enable logging to
 * the console by simply calling
 * {@link webdriver.logging.installConsoleHandler()}.
 *
 * The [remote logging API](https://github.com/SeleniumHQ/selenium/wiki/Logging)
 * allows you to retrieve logs from a remote WebDriver server. This API uses the
 * {@link Preferences} class to define desired log levels prior to create a
 * WebDriver session:
 *
 *     var prefs = new webdriver.logging.Preferences();
 *     prefs.setLevel(webdriver.logging.Type.BROWSER,
 *                    webdriver.logging.Level.DEBUG);
 *
 *     var caps = webdriver.Capabilities.chrome();
 *     caps.setLoggingPrefs(prefs);
 *     // ...
 *
 * Remote log entries are represented by the {@link Entry} class and may be
 * retrieved via {@link webdriver.WebDriver.Logs}:
 *
 *     driver.manage().logs().get(webdriver.logging.Type.BROWSER)
 *         .then(function(entries) {
 *            entries.forEach(function(entry) {
 *              console.log('[%s] %s', entry.level.name, entry.message);
 *            });
 *         });
 *
 * **NOTE:** Only a few browsers support the remote logging API (notably
 * Firefox and Chrome). Firefox supports basic logging functionality, while
 * Chrome exposes robust
 * [performance logging](https://chromedriver.chromium.org/logging)
 * options. Remote logging is still considered a non-standard feature, and the
 * APIs exposed by this module for it are non-frozen. Once logging is officially
 * defined by the [W3C WebDriver spec](http://www.w3.org/TR/webdriver/), this
 * module will be updated to use a consistent API for local and remote logging.
 */

goog.module('webdriver.logging');
goog.module.declareLegacyNamespace();

var LogManager = goog.require('goog.debug.LogManager');
var LogRecord = goog.require('goog.debug.LogRecord');
var Logger = goog.require('goog.debug.Logger');
var googString = goog.require('goog.string');

var padNumber = googString.padNumber;

/** @const */
exports.LogRecord = LogRecord;


/** @const */
exports.Logger = Logger;


/** @const */
exports.Level = Logger.Level;


/**
 * DEBUG is a message level for debugging messages and has the same log level
 * as the {@link Logger.Level.CONFIG} message level.
 * @const {!Logger.Level}
 */
Logger.Level.DEBUG = new Logger.Level('DEBUG', Logger.Level.CONFIG.value);


/**
 * Finds a named logger.
 *
 * @param {string=} opt_name The dot-delimited logger name, such as
 *     "webdriver.logging.Logger". Defaults to the name of the root logger.
 * @return {!Logger} The named logger.
 */
function getLogger(opt_name) {
  return LogManager.getLogger(opt_name || Logger.ROOT_LOGGER_NAME);
}
exports.getLogger = getLogger;


/**
 * Logs all messages to the Console API.
 */
function consoleHandler(record) {
  if (typeof console === 'undefined' || !console) {
    return;
  }
  record = /** @type {!LogRecord} */(record);
  var timestamp = new Date(record.getMillis());
  var msg =
      '[' + timestamp.getUTCFullYear() + '-' +
      padNumber(timestamp.getUTCMonth() + 1, 2) + '-' +
      padNumber(timestamp.getUTCDate(), 2) + 'T' +
      padNumber(timestamp.getUTCHours(), 2) + ':' +
      padNumber(timestamp.getUTCMinutes(), 2) + ':' +
      padNumber(timestamp.getUTCSeconds(), 2) + 'Z]' +
      '[' + record.getLevel().name + ']' +
      '[' + record.getLoggerName() + '] ' +
      record.getMessage();

  var level = record.getLevel().value;
  if (level >= Logger.Level.SEVERE.value) {
    console.error(msg);
  } else if (level >= Logger.Level.WARNING.value) {
    console.warn(msg);
  } else {
    console.log(msg);
  }
}


/**
 * Adds the console handler to the given logger. The console handler will log
 * all messages using the JavaScript Console API.
 *
 * @param {Logger=} opt_logger The logger to add the handler to; defaults
 *     to the root logger.
 * @see exports.removeConsoleHandler
 */
exports.addConsoleHandler = function(opt_logger) {
  var logger = opt_logger || getLogger();
  logger.addHandler(consoleHandler);
};


/**
 * Installs the console log handler on the root logger.
 * @see exports.addConsoleHandler
 */
exports.installConsoleHandler = function() {
  exports.addConsoleHandler();
};


/**
 * Removes the console log handler from the given logger.
 *
 * @param {Logger=} opt_logger The logger to remove the handler from; defaults
 *     to the root logger.
 * @see exports.addConsoleHandler
 */
exports.removeConsoleHandler = function(opt_logger) {
  var logger = opt_logger || getLogger();
  logger.removeHandler(consoleHandler);
};


/**
 * Converts a level name or value to a {@link webdriver.logging.Level} value.
 * If the name/value is not recognized, {@link webdriver.logging.Level.ALL}
 * will be returned.
 * @param {(number|string)} nameOrValue The log level name, or value, to
 *     convert .
 * @return {!Logger.Level} The converted level.
 */
function getLevel(nameOrValue) {
  // DEBUG is not a predefined Closure log level, but maps to CONFIG. Since
  // DEBUG is a predefined level for the WebDriver protocol, we prefer it over
  // CONFIG.
  if ('DEBUG' === nameOrValue || Logger.Level.DEBUG.value === nameOrValue) {
    return Logger.Level.DEBUG;
  } else if (goog.isString(nameOrValue)) {
    return Logger.Level.getPredefinedLevel(/** @type {string} */(nameOrValue))
        || Logger.Level.ALL;
  } else {
    return Logger.Level.getPredefinedLevelByValue(
        /** @type {number} */(nameOrValue)) || Logger.Level.ALL;
  }
}
exports.getLevel = getLevel;


/**
 * Normalizes a {@link Logger.Level} to one of the distinct values recognized
 * by WebDriver's wire protocol.
 * @param {!Logger.Level} level The input level.
 * @return {!Logger.Level} The normalized level.
 */
function normalizeLevel(level) {
  if (level.value <= Logger.Level.ALL.value) {          // ALL is 0.
    return Logger.Level.ALL;

  } else if (level.value === Logger.Level.OFF.value) {  // OFF is Infinity
    return Logger.Level.OFF;

  } else if (level.value < Logger.Level.INFO.value) {
    return Logger.Level.DEBUG;

  } else if (level.value < Logger.Level.WARNING.value) {
    return Logger.Level.INFO;

  } else if (level.value < Logger.Level.SEVERE.value) {
    return Logger.Level.WARNING;

  } else {
    return Logger.Level.SEVERE;
  }
}


/**
 * Common log types.
 * @enum {string}
 */
var Type = {
  /** Logs originating from the browser. */
  BROWSER: 'browser',
  /** Logs from a WebDriver client. */
  CLIENT: 'client',
  /** Logs from a WebDriver implementation. */
  DRIVER: 'driver',
  /** Logs related to performance. */
  PERFORMANCE: 'performance',
  /** Logs from the remote server. */
  SERVER: 'server'
};
exports.Type = Type;


/**
 * Describes the log preferences for a WebDriver session.
 * @final
 */
var Preferences = goog.defineClass(null, {
  /** @constructor */
  constructor: function() {
    /** @private {!Object.<string, Logger.Level>} */
    this.prefs_ = {};
  },

  /**
   * Sets the desired logging level for a particular log type.
   * @param {(string|Type)} type The log type.
   * @param {!Logger.Level} level The desired log level.
   */
  setLevel: function(type, level) {
    this.prefs_[type] = normalizeLevel(level);
  },

  /**
   * Converts this instance to its JSON representation.
   * @return {!Object.<string, string>} The JSON representation of this set of
   *     preferences.
   */
  toJSON: function() {
    var obj = {};
    for (var type in this.prefs_) {
      if (this.prefs_.hasOwnProperty(type)) {
        obj[type] = this.prefs_[type].name;
      }
    }
    return obj;
  }
});
exports.Preferences = Preferences;


/**
 * A single log entry recorded by a WebDriver component, such as a remote
 * WebDriver server.
 * @final
 */
var Entry = goog.defineClass(null, {
  /**
   * @param {(!Logger.Level|string)} level The entry level.
   * @param {string} message The log message.
   * @param {number=} opt_timestamp The time this entry was generated, in
   *     milliseconds since 0:00:00, January 1, 1970 UTC. If omitted, the
   *     current time will be used.
   * @param {string=} opt_type The log type, if known.
   * @constructor
   */
  constructor: function(level, message, opt_timestamp, opt_type) {

    /** @type {!Logger.Level} */
    this.level = goog.isString(level) ? getLevel(level) : level;

    /** @type {string} */
    this.message = message;

    /** @type {number} */
    this.timestamp = goog.isNumber(opt_timestamp) ? opt_timestamp : goog.now();

    /** @type {string} */
    this.type = opt_type || '';
  },

  statics: {
    /**
     * Converts a {@link goog.debug.LogRecord} into a
     * {@link webdriver.logging.Entry}.
     * @param {!LogRecord} logRecord The record to convert.
     * @param {string=} opt_type The log type.
     * @return {!Entry} The converted entry.
     */
    fromClosureLogRecord: function(logRecord, opt_type) {
      return new Entry(
          normalizeLevel(/** @type {!Logger.Level} */(logRecord.getLevel())),
          '[' + logRecord.getLoggerName() + '] ' + logRecord.getMessage(),
          logRecord.getMillis(),
          opt_type);
    }
  },

  /**
   * @return {{level: string, message: string, timestamp: number,
   *           type: string}} The JSON representation of this entry.
   */
  toJSON: function() {
    return {
      'level': this.level.name,
      'message': this.message,
      'timestamp': this.timestamp,
      'type': this.type
    };
  }
});
exports.Entry = Entry;