watir 1.4.1 → 7.3.0

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'webidl', path: File.expand_path('../webidl') if ENV['LOCAL_WEBIDL']
+
+if ENV['LOCAL_SELENIUM']
+  ENV['RUBYOPT'] = '-I../selenium/bazel-bin/rb'
+  gem 'selenium-webdriver', path: File.expand_path('../selenium/rb')
+end
+
+gem 'ffi' if Gem.win_platform? # For selenium-webdriver on Windows
+
+# Specify your gem's dependencies in watir.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,24 @@
+(the MIT License)
+
+Copyright (c) 2009-2015 Jari Bakken
+Copyright (c) 2015-2023 Alex Rodionov, Titus Fortner
+Copyright (c) 2018-2023 Justin Ko
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,113 @@
+# watir
+
+Watir Powered By Selenium!
+
+[![Gem Version](https://badge.fury.io/rb/watir.svg)](http://badge.fury.io/rb/watir)
+[![Chrome Tests](https://github.com/watir/watir/actions/workflows/chrome.yml/badge.svg)](https://github.com/watir/watir/actions/workflows/chrome.yml)
+[![Edge Tests](https://github.com/watir/watir/actions/workflows/edge.yml/badge.svg)](https://github.com/watir/watir/actions/workflows/edge.yml)
+[![Firefox Tests](https://github.com/watir/watir/actions/workflows/firefox.yml/badge.svg)](https://github.com/watir/watir/actions/workflows/firefox.yml)
+[![IE Tests](https://github.com/watir/watir/actions/workflows/ie.yml/badge.svg)](https://github.com/watir/watir/actions/workflows/ie.yml)
+[![Safari Tests](https://github.com/watir/watir/actions/workflows/safari.yml/badge.svg)](https://github.com/watir/watir/actions/workflows/safari.yml)
+[![Unit Tests](https://github.com/watir/watir/actions/workflows/unit.yml/badge.svg)](https://github.com/watir/watir/actions/workflows/unit.yml)
+
+## Using Watir
+
+This README is for people interested in writing code for Watir or gems in the Watir ecosystem
+that leverage private-api Watir code.
+
+For our users, everything you'll need is on the [Watir website](http://watir.com):
+examples, news, guides, additional resources, support information and more.
+
+## Procedure for Patches/Pull Requests
+
+* Fork the project.
+* Clone onto your local machine.
+* Create a new feature branch (bonus points for good names).
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so we don't unintentionally break it in a future version.
+* Commit, do not change Rakefile, gemspec, or CHANGES files, we'll take care of that on release.
+* Make sure it is passing doctests.
+* Make sure it is passing rubocop.
+* Push to your forked repository.
+* Send a pull request.
+
+## Developing Extensions
+
+When developing a gem intended to be used with Watir, you can run your code with WatirSpec
+to make sure that requiring your code does not break something else in Watir.
+
+First, add WatirSpec Rake tasks to your gem:
+
+```ruby
+# Rakefile
+require 'watirspec/rake_tasks'
+WatirSpec::RakeTasks.new
+```
+
+Second, initialize WatirSpec for your gem:
+
+```bash
+$ bundle exec rake watirspec:init
+```
+
+This command will walk you through how to customize your code.
+
+## Automatic Element Generation
+
+The majority of element methods Watir provides is autogenerated from specifications.
+This is done by extracting the IDL parts from the spec and processing them with the
+[WebIDL gem](https://github.com/jarib/webidl).
+
+Generated elements are currently based on the following specifications:
+
+* [HTML](https://www.w3.org/TR/2017/REC-html52-20171214/) (`lib/watir/elements/html_elements.rb`)
+* [SVG](https://www.w3.org/TR/2018/CR-SVG2-20180807/) (`lib/watir/elements/svg_elements.rb`)
+
+To run:
+
+```bash
+$ bundle exec rake html:update
+$ bundle exec rake svg:update
+```
+
+## Specs
+
+#### Github Actions
+
+Watir specs are run with [Github Actions](https://github.com/watir/watir/tree/main/.github/workflows).
+
+Watir code is tested on Linux with latest versions of supported browsers and all active Ruby versions.
+
+#### Doctests
+
+Watir uses [yard-doctest](https://github.com/p0deje/yard-doctest) to directly test
+our documentation examples.
+
+```bash
+mkdir ~/.yard
+bundle exec yard config -a autoload_plugins yard-doctest
+rake yard:doctest
+```
+
+#### Coveralls
+
+Watir code is run through [Coveralls](https://coveralls.io/github/watir/watir) to encourage PRs
+to ensure all paths in their code have tests associated with them.
+
+#### Rubocop
+
+Watir is using [Rubocop](https://github.com/rubocop/rubocop) to ensure a consistent style across the
+code base. It is run with our minimum supported Ruby version (2.3)
+We have some established exceptions at `.rubocop.yml`
+that might need to be tweaked for new code submissions. This can be addressed in the PR as necessary.
+
+#### Statistics
+
+Element specs are run with
+[Selenium Statistics gem](https://github.com/titusfortner/selenium_statistics)
+to verify that changes to the code do not dramatically decrease the performance based
+on wire calls.
+
+## Copyright
+
+See LICENSE for details

data/Rakefile

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('lib', __dir__)
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.rspec_opts = %w[--color --format doc]
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.exclude_pattern = 'spec/unit/**/*_spec.rb'
+end
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new(:rubocop) do |t|
+  t.options = ['--display-cop-names']
+end
+
+{
+  html: 'https://www.w3.org/TR/html52/single-page.html',
+  svg: 'https://www.w3.org/TR/2018/CR-SVG2-20180807/single-page.html'
+}.each do |type, spec_uri|
+  namespace type do
+    spec_path = "support/#{type}.html"
+
+    desc 'require generator'
+    task generator_lib: :lib do
+      require 'watir/generator'
+    end
+
+    desc "Download #{type.upcase} spec from #{spec_uri}"
+    task :download do
+      require 'open-uri'
+      mv spec_path, "#{spec_path}.old" if File.exist?(spec_path)
+      downloaded_bytes = 0
+
+      File.open(spec_path, 'w') do |io|
+        io << "<!--  downloaded from #{spec_uri} on #{Time.now} -->\n"
+        io << data = URI.parse(spec_uri).read
+        downloaded_bytes = data.bytesize
+      end
+
+      puts "#{spec_uri} => #{spec_path} (#{downloaded_bytes} bytes)"
+    end
+
+    desc "Print IDL parts from #{spec_uri}"
+    task print: :generator_lib do
+      extractor = Watir::Generator.const_get("#{type.upcase}::SpecExtractor").new(spec_path)
+
+      extractor.process.each do |tag_name, interface_definitions|
+        puts "#{tag_name.ljust(10)} => #{interface_definitions.map(&:name)}"
+      end
+
+      extractor.print_hierarchy
+
+      if extractor.errors.any?
+        puts "\n\n<======================= ERRORS =======================>\n\n"
+        puts extractor.errors.join("\n#{'=' * 80}\n")
+      end
+    end
+
+    desc 'Re-generate the base Watir element classes from the spec'
+    task generate: :generator_lib do
+      old_file = "lib/watir/elements/#{type}_elements.rb"
+      generator = Watir::Generator.const_get(type.upcase).new
+
+      File.open("#{old_file}.new", 'w') do |file|
+        generator.generate(spec_path, file)
+      end
+
+      system "diff -Naut #{old_file} #{old_file}.new" if File.exist?(old_file)
+    end
+
+    desc "Move #{type}.rb.new to #{type}.rb"
+    task :overwrite do
+      file = "lib/watir/elements/#{type}_elements.rb"
+      mv "#{file}.new", file
+    end
+
+    desc "download spec -> generate -> #{type}.rb"
+    task update: %i[download generate overwrite]
+  end
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new do |task|
+  task.options = %w[--debug] # this is pretty slow, so nice with some output
+end
+
+require 'yard/doctest/rake'
+YARD::Doctest::RakeTask.new do |task|
+  task.doctest_opts = ['-v']
+end
+
+namespace :changes do
+  desc 'Show how versions differ'
+  task :differ do
+    require './support/version_differ'
+  end
+
+  desc 'Update CHANGES.md'
+  task update: :differ do
+    VersionDiffer.new.update('CHANGES.md')
+  end
+
+  desc 'Generate CHANGES.md from scratch'
+  task generate: :differ do
+    VersionDiffer.new.generate('CHANGES.md')
+  end
+
+  desc 'Print latest diff'
+  task print: :differ do
+    VersionDiffer.new.print_latest($stdout)
+  end
+end
+
+task default: [:spec, 'yard:doctest']
+
+namespace :spec do
+  RSpec::Core::RakeTask.new(:html) do |spec|
+    spec.rspec_opts = "--format html --out #{ENV['SPEC_REPORT'] || 'specs.html'}"
+    spec.pattern = 'spec/**/*_spec.rb'
+  end
+
+  require 'selenium-webdriver'
+
+  desc 'Run specs in all browsers'
+  task all_browsers: %i[browsers remote_browsers]
+
+  desc 'Run specs locally for all browsers'
+  task browsers: [:chrome,
+                  :firefox,
+                  (:safari if Selenium::WebDriver::Platform.mac?),
+                  (:ie if Selenium::WebDriver::Platform.windows?),
+                  (:edge if Selenium::WebDriver::Platform.windows?)].compact
+
+  desc 'Run specs remotely for all browsers'
+  task remote_browsers: [:remote_chrome,
+                         :remote_firefox,
+                         (:remote_safari if Selenium::WebDriver::Platform.mac?),
+                         (:remote_ie if Selenium::WebDriver::Platform.windows?),
+                         (:remote_edge if Selenium::WebDriver::Platform.windows?)].compact
+
+  %w[firefox chrome safari ie edge].each do |browser|
+    desc "Run specs in #{browser}"
+    task browser do
+      ENV['WATIR_BROWSER'] = browser
+      Rake::Task[:spec].execute
+    end
+
+    desc "Run specs in Remote #{browser}"
+    task "remote_#{browser}" do
+      ENV['WATIR_BROWSER'] = browser
+      ENV['USE_REMOTE'] = 'true'
+      Rake::Task[:spec].execute
+    end
+  end
+
+  desc 'Run the Unit tests'
+  RSpec::Core::RakeTask.new(:unit) do |spec|
+    spec.pattern = 'spec/unit/**/**_spec.rb'
+  end
+
+  desc 'Run element location specs and report wire calls'
+  RSpec::Core::RakeTask.new(:stats) do |spec|
+    ENV['SELENIUM_STATS'] = 'true'
+    spec.pattern = 'spec/**/**_spec.rb'
+    spec.exclude_pattern = '**/window_switching_spec.rb, **/browser_spec.rb, **/after_hooks_spec.rb, ' \
+                           '**/alert_spec.rb, **/wait_spec.rb, **/screenshot_spec.rb'
+  end
+end

data/lib/watir/adjacent.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Watir
+  module Adjacent
+    #
+    # Returns parent element of current element.
+    #
+    # @example
+    #   browser.text_field(name: "new_user_first_name").parent == browser.fieldset
+    #   #=> true
+    #
+
+    def parent(opt = {})
+      xpath_adjacent(opt.merge(adjacent: :ancestor, plural: false))
+    end
+
+    #
+    # Returns preceding sibling element of current element.
+    #
+    # @example
+    #   browser.text_field(name: "new_user_first_name").preceding_sibling(index: 1) == browser.legend
+    #   #=> true
+    #
+
+    def preceding_sibling(opt = {})
+      xpath_adjacent(opt.merge(adjacent: :preceding, plural: false))
+    end
+    alias previous_sibling preceding_sibling
+
+    #
+    # Returns collection of preceding sibling elements of current element.
+    #
+    # @example
+    #   browser.text_field(name: "new_user_first_name").preceding_siblings.size
+    #   #=> 3
+    #
+
+    def preceding_siblings(opt = {})
+      raise ArgumentError, '#previous_siblings can not take an index value' if opt[:index]
+
+      xpath_adjacent(opt.merge(adjacent: :preceding, plural: true))
+    end
+    alias previous_siblings preceding_siblings
+
+    #
+    # Returns following sibling element of current element.
+    #
+    # @example
+    #   following_sibling = browser.text_field(name: "new_user_first_name").following_sibling(index: 2)
+    #   following_sibling == browser.text_field(id: "new_user_last_name")
+    #   #=> true
+    #
+
+    def following_sibling(opt = {})
+      xpath_adjacent(opt.merge(adjacent: :following, plural: false))
+    end
+    alias next_sibling following_sibling
+
+    #
+    # Returns collection of following sibling elements of current element.
+    #
+    # @example
+    #   browser.text_field(name: "new_user_first_name").following_siblings.size
+    #   #=> 55
+    #
+
+    def following_siblings(opt = {})
+      raise ArgumentError, '#next_siblings can not take an index value' if opt[:index]
+
+      xpath_adjacent(opt.merge(adjacent: :following, plural: true))
+    end
+    alias next_siblings following_siblings
+
+    #
+    # Returns collection of siblings of current element, including current element.
+    #
+    # @example
+    #   browser.text_field(name: "new_user_first_name").siblings.size
+    #   #=> 59
+    #
+
+    def siblings(opt = {})
+      parent.children(opt)
+    end
+
+    #
+    # Returns element of direct child of current element.
+    #
+    # @example
+    #   browser.form(id: "new_user").child == browser.fieldset
+    #   #=> true
+    #
+
+    def child(opt = {})
+      xpath_adjacent(opt.merge(adjacent: :child, plural: false))
+    end
+
+    #
+    # Returns collection of elements of direct children of current element.
+    #
+    # @example
+    #   children = browser.select_list(id: "new_user_languages").children
+    #   children == browser.select_list(id: "new_user_languages").options.to_a
+    #   #=> true
+    #
+
+    def children(opt = {})
+      raise ArgumentError, '#children can not take an index value' if opt[:index]
+
+      xpath_adjacent(opt.merge(adjacent: :child, plural: true))
+    end
+
+    private
+
+    def xpath_adjacent(opt = {})
+      plural = opt.delete(:plural)
+      opt[:index] ||= 0 unless plural || opt.values.any?(Regexp)
+      if !plural
+        el = Watir.element_class_for(opt[:tag_name] || '').new(self, opt)
+        el.is_a?(Input) ? el.to_subtype : el
+      elsif opt[:tag_name]
+        Watir.const_get("#{Watir.element_class_for(opt[:tag_name])}Collection").new(self, opt)
+      else
+        HTMLElementCollection.new(self, opt)
+      end
+    end
+  end # Adjacent
+end # Watir

data/lib/watir/after_hooks.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Watir
+  #
+  # After hooks are blocks that run after certain browser events.
+  # They are generally used to ensure application under test does not encounter
+  # any error and are automatically executed after following events:
+  #   1. Open URL.
+  #   2. Refresh page.
+  #   3. Click, double-click or right-click on element.
+  #   4. Alert closing.
+  #
+
+  class AfterHooks
+    include Enumerable
+
+    def initialize(browser)
+      @browser = browser
+      @after_hooks = []
+    end
+
+    #
+    # Adds new after hook.
+    #
+    # @example
+    #   browser.after_hooks.add do |browser|
+    #     browser.text.include?("Server Error") and puts "Application exception or 500 error!"
+    #   end
+    #   browser.goto "watir.com/404"
+    #   "Application exception or 500 error!"
+    #
+    # @param [#call] after_hook Object responding to call
+    # @yield after_hook block
+    # @yieldparam [Watir::Browser]
+    #
+
+    def add(after_hook = nil, &block)
+      if block
+        @after_hooks << block
+      elsif after_hook.respond_to? :call
+        @after_hooks << after_hook
+      else
+        raise ArgumentError, 'expected block or object responding to #call'
+      end
+    end
+    alias << add
+
+    #
+    # Deletes after hook.
+    #
+    # @example
+    #   browser.after_hooks.add do |browser|
+    #     browser.text.include?("Server Error") and puts "Application exception or 500 error!"
+    #   end
+    #   browser.goto "watir.com/404"
+    #   "Application exception or 500 error!"
+    #   browser.after_hooks.delete browser.after_hooks[0]
+    #   browser.refresh
+    #
+
+    def delete(after_hook)
+      @after_hooks.delete(after_hook)
+    end
+
+    #
+    # Runs after hooks.
+    #
+
+    def run
+      # We can't just rescue exception because Firefox automatically closes alert when exception raised
+      return unless @after_hooks.any? && !@browser.alert.exists?
+
+      each { |after_hook| after_hook.call(@browser) }
+    rescue Selenium::WebDriver::Error::NoSuchWindowError => e
+      Watir.logger.info "Could not execute After Hooks because browser window was closed #{e}"
+    end
+
+    #
+    # Executes a block without running error after hooks.
+    #
+    # @example
+    #   browser.after_hooks.without do |browser|
+    #     browser.element(name: "new_user_button").click
+    #   end
+    #
+    # @yield Block that is executed without after hooks being run
+    # @yieldparam [Watir::Browser]
+    #
+
+    def without
+      current_after_hooks = @after_hooks
+      @after_hooks = []
+      yield(@browser)
+    ensure
+      @after_hooks = current_after_hooks
+    end
+
+    #
+    # Yields each after hook.
+    #
+    # @yieldparam [#call] after_hook Object responding to call
+    #
+
+    def each(&block)
+      @after_hooks.each(&block)
+    end
+
+    #
+    # Returns number of after hooks.
+    #
+    # @example
+    #   browser.after_hooks.add { puts 'Some after_hook.' }
+    #   browser.after_hooks.length
+    #   #=> 1
+    #
+    # @return [Integer]
+    #
+
+    def length
+      @after_hooks.length
+    end
+    alias size length
+
+    #
+    # Gets the after hook at the given index.
+    #
+    # @param [Integer] index
+    # @return [#call]
+    #
+
+    def [](index)
+      @after_hooks[index]
+    end
+  end # AfterHooks
+end # Watir

data/lib/watir/alert.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Watir
+  class Alert
+    include Waitable
+    include Exception
+
+    def initialize(browser)
+      @browser = browser
+      @alert = nil
+    end
+
+    #
+    # Returns text of alert.
+    #
+    # @example
+    #   browser.alert.text
+    #   #=> "ok"
+    #
+    # @return [String]
+    #
+
+    def text
+      wait_for_exists
+      @alert.text
+    end
+
+    #
+    # Closes alert or accepts prompts/confirms.
+    #
+    # @example
+    #   browser.alert.ok
+    #   browser.alert.exists?
+    #   #=> false
+    #
+
+    def ok
+      wait_for_exists
+      @alert.accept
+      @browser.after_hooks.run
+    end
+
+    #
+    # Closes alert or cancels prompts/confirms.
+    #
+    # @example
+    #   browser.alert.close
+    #   browser.alert.exists?
+    #   #=> false
+    #
+
+    def close
+      wait_for_exists
+      @alert.dismiss
+      @browser.after_hooks.run
+    end
+
+    #
+    # Enters text to prompt.
+    #
+    # @example
+    #   browser.alert.set "Text for prompt"
+    #   browser.alert.ok
+    #
+    # @param [String] value
+    #
+
+    def set(value)
+      wait_for_exists
+      @alert.send_keys(value)
+    end
+
+    #
+    # Returns true if alert, confirm or prompt is present and false otherwise.
+    #
+    # @example
+    #   browser.alert.exists?
+    #   #=> true
+    #
+
+    def exists?
+      assert_exists
+      true
+    rescue UnknownObjectException
+      false
+    end
+    alias present? exists?
+    alias exist? exists?
+
+    #
+    # @api private
+    # @see Watir::Wait
+    #
+
+    def selector_string
+      'alert'
+    end
+
+    private
+
+    def assert_exists
+      @alert = @browser.driver.switch_to.alert
+    rescue Selenium::WebDriver::Error::NoSuchAlertError
+      raise UnknownObjectException, 'unable to locate alert'
+    end
+
+    def wait_for_exists
+      wait_until(message: 'waiting for alert', &:exists?)
+    rescue Wait::TimeoutError
+      raise UnknownObjectException, 'unable to locate alert'
+    end
+  end # Alert
+end # Watir