selenium-webdriver 2.47.0 → 2.52.0

package/lib/logging.js

@@ -0,0 +1,668 @@
+// 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.
+
+'use strict';
+
+/**
+ * @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 {@linkplain Logger} class is
+ * similar to Java's logging API. Loggers, retrieved by
+ * {@linkplain #getLogger getLogger(name)}, use hierarchical, dot-delimited
+ * namespaces (e.g. "" > "webdriver" > "webdriver.logging"). Recorded log
+ * messages are represented by the {@linkplain Entry} class. You can capture log
+ * records by {@linkplain Logger#addHandler attaching} a handler function to the
+ * desired logger. For convenience, you can quickly enable logging to the
+ * console by simply calling {@linkplain #installConsoleHandler
+ * 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 creating
+ * a WebDriver session:
+ *
+ *     var prefs = new logging.Preferences();
+ *     prefs.setLevel(logging.Type.BROWSER, logging.Level.DEBUG);
+ *
+ *     var caps = Capabilities.chrome();
+ *     caps.setLoggingPrefs(prefs);
+ *     // ...
+ *
+ * Remote log entries, also represented by the {@link Entry} class, may be
+ * retrieved via {@link webdriver.WebDriver.Logs}:
+ *
+ *     driver.manage().logs().get(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://sites.google.com/a/chromium.org/chromedriver/logging)
+ * options. Remote logging is still considered a non-standard feature, and the
+ * APIs exposed by this module for it are non-frozen. This module will be
+ * updated, possibly breaking backwards-compatibility, once logging is
+ * officially defined by the
+ * [W3C WebDriver spec](http://www.w3.org/TR/webdriver/).
+ */
+
+/**
+ * Defines a message level that may be used to control logging output.
+ *
+ * @final
+ */
+class Level {
+  /**
+   * @param {string} name the level's name.
+   * @param {number} level the level's numeric value.
+   */
+  constructor(name, level) {
+    if (level < 0) {
+      throw new TypeError('Level must be >= 0');
+    }
+
+    /** @private {string} */
+    this.name_ = name;
+
+    /** @private {number} */
+    this.value_ = level;
+  }
+
+  /** This logger's name. */
+  get name() {
+    return this.name_;
+  }
+
+  /** The numeric log level. */
+  get value() {
+    return this.value_;
+  }
+
+  /** @override */
+  toString() {
+    return this.name;
+  }
+}
+
+/**
+ * Indicates no log messages should be recorded.
+ * @const
+ */
+Level.OFF = new Level('OFF', Infinity);
+
+
+/**
+ * Log messages with a level of `1000` or higher.
+ * @const
+ */
+Level.SEVERE = new Level('SEVERE', 1000);
+
+
+/**
+ * Log messages with a level of `900` or higher.
+ * @const
+ */
+Level.WARNING = new Level('WARNING', 900);
+
+
+/**
+ * Log messages with a level of `800` or higher.
+ * @const
+ */
+Level.INFO = new Level('INFO', 800);
+
+
+/**
+ * Log messages with a level of `700` or higher.
+ * @const
+ */
+Level.DEBUG = new Level('DEBUG', 700);
+
+
+/**
+ * Log messages with a level of `500` or higher.
+ * @const
+ */
+Level.FINE = new Level('FINE', 500);
+
+
+/**
+ * Log messages with a level of `400` or higher.
+ * @const
+ */
+Level.FINER = new Level('FINER', 400);
+
+
+/**
+ * Log messages with a level of `300` or higher.
+ * @const
+ */
+Level.FINEST = new Level('FINEST', 300);
+
+
+/**
+ * Indicates all log messages should be recorded.
+ * @const
+ */
+Level.ALL = new Level('ALL', 0);
+
+
+const ALL_LEVELS = /** !Set<Level> */new Set([
+  Level.OFF,
+  Level.SEVERE,
+  Level.WARNING,
+  Level.INFO,
+  Level.DEBUG,
+  Level.FINE,
+  Level.FINER,
+  Level.FINEST,
+  Level.ALL
+]);
+
+
+const LEVELS_BY_NAME = /** !Map<string, !Level> */ new Map([
+  [Level.OFF.name, Level.OFF],
+  [Level.SEVERE.name, Level.SEVERE],
+  [Level.WARNING.name, Level.WARNING],
+  [Level.INFO.name, Level.INFO],
+  [Level.DEBUG.name, Level.DEBUG],
+  [Level.FINE.name, Level.FINE],
+  [Level.FINER.name, Level.FINER],
+  [Level.FINEST.name, Level.FINEST],
+  [Level.ALL.name, Level.ALL]
+]);
+
+
+/**
+ * Converts a level name or value to a {@link Level} value. If the name/value
+ * is not recognized, {@link Level.ALL} will be returned.
+ *
+ * @param {(number|string)} nameOrValue The log level name, or value, to
+ *     convert.
+ * @return {!Level} The converted level.
+ */
+function getLevel(nameOrValue) {
+  if (typeof nameOrValue === 'string') {
+    return LEVELS_BY_NAME.get(nameOrValue) || Level.ALL;
+  }
+  if (typeof nameOrValue !== 'number') {
+    throw new TypeError('not a string or number');
+  }
+  for (let level of ALL_LEVELS) {
+    if (nameOrValue >= level.value) {
+      return level;
+    }
+  }
+  return Level.ALL;
+}
+
+
+/**
+ * Describes a single log entry.
+ *
+ * @final
+ */
+class Entry {
+  /**
+   * @param {(!Level|string|number)} 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(level, message, opt_timestamp, opt_type) {
+    this.level = level instanceof Level ? level : getLevel(level);
+    this.message = message;
+    this.timestamp =
+        typeof opt_timestamp === 'number' ? opt_timestamp : Date.now();
+    this.type = opt_type || '';
+  }
+
+  /**
+   * @return {{level: string, message: string, timestamp: number,
+   *           type: string}} The JSON representation of this entry.
+   */
+  toJSON() {
+    return {
+      'level': this.level.name,
+      'message': this.message,
+      'timestamp': this.timestamp,
+      'type': this.type
+    };
+  }
+}
+
+
+/** @typedef {(string|function(): string)} */
+let Loggable;
+
+
+/**
+ * An object used to log debugging messages. Loggers use a hierarchical,
+ * dot-separated naming scheme. For instance, "foo" is considered the parent of
+ * the "foo.bar" and an ancestor of "foo.bar.baz".
+ *
+ * Each logger may be assigned a {@linkplain #setLevel log level}, which
+ * controls which level of messages will be reported to the
+ * {@linkplain #addHandler handlers} attached to this instance. If a log level
+ * is not explicitly set on a logger, it will inherit its parent.
+ *
+ * This class should never be directly instantiated. Instead, users should
+ * obtain logger references using the {@linkplain ./logging.getLogger()
+ * getLogger()} function.
+ *
+ * @final
+ */
+class Logger {
+  /**
+   * @param {string} name the name of this logger.
+   * @param {Level=} opt_level the initial level for this logger.
+   */
+  constructor(name, opt_level) {
+    /** @private {string} */
+    this.name_ = name;
+
+    /** @private {Level} */
+    this.level_ = opt_level || null;
+
+    /** @private {Logger} */
+    this.parent_ = null;
+
+    /** @private {Set<function(!Entry)>} */
+    this.handlers_ = null;
+  }
+
+  /** @return {string} the name of this logger. */
+  getName() {
+    return this.name_;
+  }
+
+  /**
+   * @param {Level} level the new level for this logger, or `null` if the logger
+   *     should inherit its level from its parent logger.
+   */
+  setLevel(level) {
+    this.level_ = level;
+  }
+
+  /** @return {Level} the log level for this logger. */
+  getLevel() {
+    return this.level_;
+  }
+
+  /**
+   * @return {!Level} the effective level for this logger.
+   */
+  getEffectiveLevel() {
+    let logger = this;
+    let level;
+    do {
+      level = logger.level_;
+      logger = logger.parent_;
+    } while (logger && !level);
+    return level || Level.OFF;
+  }
+
+  /**
+   * @param {!Level} level the level to check.
+   * @return {boolean} whether messages recorded at the given level are loggable
+   *     by this instance.
+   */
+  isLoggable(level) {
+    return level.value !== Level.OFF.value
+        && level.value >= this.getEffectiveLevel().value;
+  }
+
+  /**
+   * Adds a handler to this logger. The handler will be invoked for each message
+   * logged with this instance, or any of its descendants.
+   *
+   * @param {function(!Entry)} handler the handler to add.
+   */
+  addHandler(handler) {
+    if (!this.handlers_) {
+      this.handlers_ = new Set;
+    }
+    this.handlers_.add(handler);
+  }
+
+  /**
+   * Removes a handler from this logger.
+   *
+   * @param {function(!Entry)} handler the handler to remove.
+   * @return {boolean} whether a handler was successfully removed.
+   */
+  removeHandler(handler) {
+    if (!this.handlers_) {
+      return false;
+    }
+    return this.handlers_.delete(handler);
+  }
+
+  /**
+   * Logs a message at the given level. The message may be defined as a string
+   * or as a function that will return the message. If a function is provided,
+   * it will only be invoked if this logger's
+   * {@linkplain #getEffectiveLevel() effective log level} includes the given
+   * `level`.
+   *
+   * @param {!Level} level the level at which to log the message.
+   * @param {(string|function(): string)} loggable the message to log, or a
+   *     function that will return the message.
+   */
+  log(level, loggable) {
+    if (!this.isLoggable(level)) {
+      return;
+    }
+    let message = '[' + this.name_ + '] '
+        + (typeof loggable === 'function' ? loggable() : loggable);
+    let entry = new Entry(level, message, Date.now());
+    for (let logger = this; !!logger; logger = logger.parent_) {
+      if (logger.handlers_) {
+        for (let handler of logger.handlers_) {
+          handler(entry);
+        }
+      }
+    }
+  }
+
+  /**
+   * Logs a message at the {@link Level.SEVERE} log level.
+   * @param {(string|function(): string)} loggable the message to log, or a
+   *     function that will return the message.
+   */
+  severe(loggable) {
+    this.log(Level.SEVERE, loggable);
+  }
+
+  /**
+   * Logs a message at the {@link Level.WARNING} log level.
+   * @param {(string|function(): string)} loggable the message to log, or a
+   *     function that will return the message.
+   */
+  warning(loggable) {
+    this.log(Level.WARNING, loggable);
+  }
+
+  /**
+   * Logs a message at the {@link Level.INFO} log level.
+   * @param {(string|function(): string)} loggable the message to log, or a
+   *     function that will return the message.
+   */
+  info(loggable) {
+    this.log(Level.INFO, loggable);
+  }
+
+  /**
+   * Logs a message at the {@link Level.DEBUG} log level.
+   * @param {(string|function(): string)} loggable the message to log, or a
+   *     function that will return the message.
+   */
+  debug(loggable) {
+    this.log(Level.DEBUG, loggable);
+  }
+
+  /**
+   * Logs a message at the {@link Level.FINE} log level.
+   * @param {(string|function(): string)} loggable the message to log, or a
+   *     function that will return the message.
+   */
+  fine(loggable) {
+    this.log(Level.FINE, loggable);
+  }
+
+  /**
+   * Logs a message at the {@link Level.FINER} log level.
+   * @param {(string|function(): string)} loggable the message to log, or a
+   *     function that will return the message.
+   */
+  finer(loggable) {
+    this.log(Level.FINER, loggable);
+  }
+
+  /**
+   * Logs a message at the {@link Level.FINEST} log level.
+   * @param {(string|function(): string)} loggable the message to log, or a
+   *     function that will return the message.
+   */
+  finest(loggable) {
+    this.log(Level.FINEST, loggable);
+  }
+}
+
+
+/**
+ * Maintains a collection of loggers.
+ *
+ * @final
+ */
+class LogManager {
+  constructor() {
+    /** @private {!Map<string, !Logger>} */
+    this.loggers_ = new Map;
+    this.root_ = new Logger('', Level.OFF);
+  }
+
+  /**
+   * Retrieves a named logger, creating it in the process. This function will
+   * implicitly create the requested logger, and any of its parents, if they
+   * do not yet exist.
+   *
+   * @param {string} name the logger's name.
+   * @return {!Logger} the requested logger.
+   */
+  getLogger(name) {
+    if (!name) {
+      return this.root_;
+    }
+    let parent = this.root_;
+    for (let i = name.indexOf('.'); i != -1; i = name.indexOf('.', i + 1)) {
+      let parentName = name.substr(0, i);
+      parent = this.createLogger_(parentName, parent);
+    }
+    return this.createLogger_(name, parent);
+  }
+
+  /**
+   * Creates a new logger.
+   *
+   * @param {string} name the logger's name.
+   * @param {!Logger} parent the logger's parent.
+   * @return {!Logger} the new logger.
+   * @private
+   */
+  createLogger_(name, parent) {
+    if (this.loggers_.has(name)) {
+      return /** @type {!Logger} */(this.loggers_.get(name));
+    }
+    let logger = new Logger(name, null);
+    logger.parent_ = parent;
+    this.loggers_.set(name, logger);
+    return logger;
+  }
+}
+
+
+const logManager = new LogManager;
+
+
+/**
+ * Retrieves a named logger, creating it in the process. This function will
+ * implicitly create the requested logger, and any of its parents, if they
+ * do not yet exist.
+ *
+ * The log level will be unspecified for newly created loggers. Use
+ * {@link Logger#setLevel(level)} to explicitly set a level.
+ *
+ * @param {string} name the logger's name.
+ * @return {!Logger} the requested logger.
+ */
+function getLogger(name) {
+  return logManager.getLogger(name);
+}
+
+
+function pad(n) {
+  if (n > 10) {
+    return '' + n;
+  } else {
+    return '0' + n;
+  }
+}
+
+
+/**
+ * Logs all messages to the Console API.
+ * @param {!Entry} entry the entry to log.
+ */
+function consoleHandler(entry) {
+  if (typeof console === 'undefined' || !console) {
+    return;
+  }
+
+  var timestamp = new Date(entry.timestamp);
+  var msg =
+      '[' + timestamp.getUTCFullYear() + '-' +
+      pad(timestamp.getUTCMonth() + 1) + '-' +
+      pad(timestamp.getUTCDate()) + 'T' +
+      pad(timestamp.getUTCHours()) + ':' +
+      pad(timestamp.getUTCMinutes()) + ':' +
+      pad(timestamp.getUTCSeconds()) + 'Z] ' +
+      '[' + entry.level.name + '] ' +
+      entry.message;
+
+  var level = entry.level.value;
+  if (level >= Level.SEVERE.value) {
+    console.error(msg);
+  } else if (level >= 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.
+ */
+function addConsoleHandler(opt_logger) {
+  let logger = opt_logger || logManager.root_;
+  logger.addHandler(consoleHandler);
+}
+
+
+/**
+ * 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
+ */
+function removeConsoleHandler(opt_logger) {
+  let logger = opt_logger || logManager.root_;
+  logger.removeHandler(consoleHandler);
+}
+
+
+/**
+ * Installs the console log handler on the root logger.
+ */
+function installConsoleHandler() {
+  addConsoleHandler(logManager.root_);
+}
+
+
+/**
+ * Common log types.
+ * @enum {string}
+ */
+const 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'
+};
+
+
+/**
+ * Describes the log preferences for a WebDriver session.
+ *
+ * @final
+ */
+class Preferences {
+  constructor() {
+    /** @private {!Map<string, !Level>} */
+    this.prefs_ = new Map;
+  }
+
+  /**
+   * Sets the desired logging level for a particular log type.
+   * @param {(string|Type)} type The log type.
+   * @param {(!Level|string|number)} level The desired log level.
+   * @throws {TypeError} if `type` is not a `string`.
+   */
+  setLevel(type, level) {
+    if (typeof type !== 'string') {
+      throw TypeError('specified log type is not a string: ' + typeof type);
+    }
+    this.prefs_.set(type, level instanceof Level ? level : getLevel(level));
+  }
+
+  /**
+   * Converts this instance to its JSON representation.
+   * @return {!Object<string, string>} The JSON representation of this set of
+   *     preferences.
+   */
+  toJSON() {
+    let json = {};
+    for (let key of this.prefs_.keys()) {
+      json[key] = this.prefs_.get(key).name;
+    }
+    return json;
+  }
+}
+
+
+// PUBLIC API
+
+
+exports.Entry = Entry;
+exports.Level = Level;
+exports.LogManager = LogManager;
+exports.Logger = Logger;
+exports.Preferences = Preferences;
+exports.Type = Type;
+exports.addConsoleHandler = addConsoleHandler;
+exports.getLevel = getLevel;
+exports.getLogger = getLogger;
+exports.installConsoleHandler = installConsoleHandler;
+exports.removeConsoleHandler = removeConsoleHandler;