class Selenium::WebDriver::Logger

@example Enable full logging

Selenium::WebDriver.logger.level = :debug

@example Log to file

Selenium::WebDriver.logger.output = 'selenium.log'

@example Use logger manually

Selenium::WebDriver.logger.info('This is info message')
Selenium::WebDriver.logger.warn('This is warning message')

Public Class Methods

new(progname = 'Selenium', default_level: nil, ignored: nil, allowed: nil) click to toggle source

@param [String] progname Allow child projects to use Selenium’s Logger pattern

# File lib/selenium/webdriver/common/logger.rb, line 51
def initialize(progname = 'Selenium', default_level: nil, ignored: nil, allowed: nil)
  default_level ||= $DEBUG || ENV.key?('DEBUG') ? :debug : :warn

  @logger = create_logger(progname, level: default_level)
  @ignored = Array(ignored)
  @allowed = Array(allowed)
  @first_warning = false
  @level_forced = false
  @output_forced = false
end

Public Instance Methods

allow(*ids) click to toggle source

Will only log the provided ID.

@param [Array, Symbol] ids

# File lib/selenium/webdriver/common/logger.rb, line 134
def allow(*ids)
  @allowed += Array(ids).flatten
end

debug(message, id: [], &block) click to toggle source

Used to supply information of interest for debugging a problem Overrides default debug to skip ignored messages by provided id

@param [String] message @param [Symbol, Array<Symbol>] id @yield see deprecate

# File lib/selenium/webdriver/common/logger.rb, line 146
def debug(message, id: [], &block)
  discard_or_log(:debug, message, id, &block)
end

debug!() click to toggle source

Forces debug level and prevents it from being overridden.

# File lib/selenium/webdriver/common/logger.rb, line 65
def debug!
  @level_forced = true
  @logger.level = :debug
end

deprecate(old, new = nil, id: [], reference: '', &block) click to toggle source

Marks code as deprecated with/without replacement.

@param [String] old @param [String, nil] new @param [Symbol, Array<Symbol>] id @param [String] reference @yield appends additional message to end of provided template

# File lib/selenium/webdriver/common/logger.rb, line 192
def deprecate(old, new = nil, id: [], reference: '', &block)
  id = Array(id)
  return if @ignored.include?(:deprecations)

  id << :deprecations if @allowed.include?(:deprecations)

  message = "[DEPRECATION] #{old} is deprecated"
  message << if new
               ". Use #{new} instead."
             else
               ' and will be removed in a future release.'
             end
  message << " See explanation for this deprecation: #{reference}." unless reference.empty?

  discard_or_log(:warn, message, id, &block)
end

error(message, id: [], &block) click to toggle source

Used to supply information that suggests an error occurred

@param [String] message @param [Symbol, Array<Symbol>] id @yield see deprecate

# File lib/selenium/webdriver/common/logger.rb, line 168
def error(message, id: [], &block)
  discard_or_log(:error, message, id, &block)
end

ignore(*ids) click to toggle source

Will not log the provided ID.

@param [Array, Symbol] ids

# File lib/selenium/webdriver/common/logger.rb, line 125
def ignore(*ids)
  @ignored += Array(ids).flatten
end

info(message, id: [], &block) click to toggle source

Used to supply information of general interest

@param [String] message @param [Symbol, Array<Symbol>] id @yield see deprecate

# File lib/selenium/webdriver/common/logger.rb, line 157
def info(message, id: [], &block)
  discard_or_log(:info, message, id, &block)
end

io() click to toggle source

Returns IO object used by logger internally.

Normally, we would have never needed it, but we want to use it as IO object for all child processes to ensure their output is redirected there.

It is only used in debug level, in other cases output is suppressed.

@api private

# File lib/selenium/webdriver/common/logger.rb, line 116
def io
  @logger.instance_variable_get(:@logdev).dev
end

level=(level) click to toggle source

# File lib/selenium/webdriver/common/logger.rb, line 78
def level=(level)
  if @level_forced
    warn('Logger level is forced; ignoring override', id: :logger)
    return
  end

  if level == :info && @logger.level == :info
    info(':info is now the default log level, to see additional logging, set log level to :debug')
  end

  @logger.level = level
end

output=(io) click to toggle source

Changes logger output to a new IO.

@param [String] io

# File lib/selenium/webdriver/common/logger.rb, line 96
def output=(io)
  if @output_forced
    warn('Logger output is forced; ignoring override', id: :logger)
    return
  end

  @logger.reopen(io)
end

stderr!() click to toggle source

Forces output to stderr and prevents it from being overridden.

# File lib/selenium/webdriver/common/logger.rb, line 73
def stderr!
  @output_forced = true
  @logger.reopen($stderr)
end

warn(message, id: [], &block) click to toggle source

Used to supply information that suggests action be taken by user

@param [String] message @param [Symbol, Array<Symbol>] id @yield see deprecate

# File lib/selenium/webdriver/common/logger.rb, line 179
def warn(message, id: [], &block)
  discard_or_log(:warn, message, id, &block)
end

Private Instance Methods

create_logger(name, level:) click to toggle source

# File lib/selenium/webdriver/common/logger.rb, line 211
def create_logger(name, level:)
  logger = ::Logger.new($stderr)
  logger.progname = name
  logger.level = level
  logger.formatter = proc do |severity, time, progname, msg|
    "#{time.strftime('%F %T')} #{severity} #{progname} #{msg}\n".force_encoding('UTF-8')
  end

  logger
end

discard_or_log(level, message, id) click to toggle source

# File lib/selenium/webdriver/common/logger.rb, line 222
def discard_or_log(level, message, id)
  id = Array(id)
  return if @ignored.intersect?(id)
  return if @allowed.any? && !@allowed.intersect?(id)

  return if ::Logger::Severity.const_get(level.upcase) < @logger.level

  unless @first_warning
    @first_warning = true
    info("Details on how to use and modify Selenium logger:\n", id: [:logger_info]) do
      "https://selenium.dev/documentation/webdriver/troubleshooting/logging\n"
    end
  end

  msg = id.empty? ? message : "[#{id.map(&:inspect).join(', ')}] #{message} "
  msg += " #{yield}" if block_given?

  @logger.send(level) { msg }
end