Code location

  • Library: rb/lib/selenium/webdriver
  • Tests: rb/spec/unit/ and rb/spec/integration/
  • Type signatures: rb/sig/

Common commands

  • Build: bazel build //rb/...

Testing

See rb/TESTING.md

Code conventions

Logging

WebDriver.logger.warn("actionable: something needs attention", id: :warning_id)
WebDriver.logger.info("useful: driver started successfully")
WebDriver.logger.debug("diagnostic: request details for debugging")

Deprecation

WebDriver.logger.deprecate(
  'OldClass#old_method',
  'NewClass#new_method',
  id: :old_method
)

Internal APIs

Mark internal APIs with @api private in YARD comments:

# @api private
def internal_method
end

Type signatures (steep/rbs)

When changing public API, update corresponding .rbs files in rb/sig/

Documentation

Use YARD for public APIs:

# Brief description.
#
# @param name [Type] description
# @return [Type] description
# @raise [ErrorClass] when condition

Integration test guards

Integration specs are guarded by RSpec metadata on describe/context/it (all enclosing guards combine). Use one of these five, and always include a reason::

  • skip_if: — skip when config matches
  • skip_unless: — run only when config matches
  • pending_if: — expect failure when config matches
  • pending_unless: — expect failure unless config matches
  • flaky: — skip_if reserved for unreliable/intermittent tests

Matching within one Hash = AND (every pair must match); an Array value within a key = OR (matches any listed value). An Array of Hashes lists configs matched independently, and the combined effect depends on the guard direction: for skip_if/pending_if the guard triggers if any Hash matches (OR); for skip_unless/pending_unless the example is kept only where all Hashes match (i.e. it is skipped/pended if any does not). The reason: is a String or an issue number. Conditions (browser, driver, platform, ci, etc.) are registered in spec_helper.rb.

skip_if: {browser: %i[chrome edge], headless: true, reason: '...'}                   # headless Chrome or Edge
pending_if: [{browser: :firefox, reason: 1234}, {platform: :macosx, reason: 5678}]   # Firefox OR macOS
skip_unless: [{bidi: false, reason: '...'}, {driver: :remote, reason: '...'}]        # only when non-bidi AND remote