[rb] update guards to minimize unnecessary execution and allow messages

rb/.rubocop.yml

@@ -46,8 +46,11 @@ Metrics/AbcSize:
     - 'lib/selenium/webdriver/support/color.rb'
 
 Metrics/BlockLength:
+  Max: 18
   Exclude:
     - "**/*_spec.rb"
+    - "**/spec_helper.rb"
+    - 'spec/rspec_matchers.rb'
     - 'selenium-webdriver.gemspec'
 
 Metrics/ClassLength:
@@ -171,3 +174,7 @@ Style/SlicingWithRange:
 
 Style/StringLiterals:
   Enabled: false
+
+Style/SignalException:
+  Exclude:
+    - 'spec/integration/selenium/webdriver/guard_spec.rb'

rb/spec/integration/selenium/webdriver/chrome/driver_spec.rb

@@ -22,7 +22,7 @@
 module Selenium
   module WebDriver
     module Chrome
-      describe Driver, only: {driver: :chrome} do
+      describe Driver, exclusive: {driver: :chrome} do
         it 'gets and sets network conditions' do
           driver.network_conditions = {offline: false, latency: 56, throughput: 789}
           expect(driver.network_conditions).to eq(

rb/spec/integration/selenium/webdriver/chrome/options_spec.rb

@@ -22,7 +22,7 @@
 module Selenium
   module WebDriver
     module Chrome
-      describe Options, only: {browser: :chrome} do
+      describe Options, exclusive: {browser: :chrome} do
         subject(:options) { Options.new }
 
         it 'passes emulated device correctly' do

rb/spec/integration/selenium/webdriver/chrome/profile_spec.rb

@@ -22,7 +22,7 @@
 module Selenium
   module WebDriver
     module Chrome
-      describe Profile do
+      describe Profile, exclusive: {browser: :chrome} do
         let(:profile) { Profile.new }
 
         it 'adds an extension' do

rb/spec/integration/selenium/webdriver/edge/driver_spec.rb

@@ -22,7 +22,7 @@
 module Selenium
   module WebDriver
     module Edge
-      describe Driver, only: {driver: :edge} do
+      describe Driver, exclusive: {driver: :edge} do
         it 'gets and sets network conditions' do
           driver.network_conditions = {offline: false, latency: 56, throughput: 789}
           expect(driver.network_conditions).to eq(

rb/spec/integration/selenium/webdriver/edge/options_spec.rb

@@ -21,8 +21,8 @@
 
 module Selenium
   module WebDriver
-    module EdgeChrome
-      describe Options, only: {browser: :edge} do
+    module Edge
+      describe Options, exclusive: {browser: :edge} do
         subject(:options) { Options.new }
 
         it 'passes emulated device correctly' do
@@ -61,6 +61,6 @@ module EdgeChrome
         #   end
         # end
       end
-    end # Chrome
+    end # Edge
   end # WebDriver
 end # Selenium

rb/spec/integration/selenium/webdriver/edge/profile_spec.rb

@@ -22,7 +22,7 @@
 module Selenium
   module WebDriver
     module Edge
-      describe Profile do
+      describe Profile, exclusive: {browser: :edge} do
         let(:profile) { Profile.new }
 
         it 'adds an extension' do

rb/spec/integration/selenium/webdriver/firefox/driver_spec.rb

@@ -21,7 +21,7 @@
 
 module Selenium
   module WebDriver
-    describe Firefox, only: {browser: %i[firefox]} do
+    describe Firefox, exclusive: {browser: :firefox} do
       it 'creates default capabilities' do
         create_driver! do |driver|
           caps = driver.capabilities

rb/spec/integration/selenium/webdriver/firefox/profile_spec.rb

@@ -22,7 +22,7 @@
 module Selenium
   module WebDriver
     module Firefox
-      describe Profile, only: {browser: %i[firefox]} do
+      describe Profile, exclusive: {browser: :firefox} do
         let(:profile) { Profile.new }
 
         def read_generated_prefs(from = nil)

rb/spec/integration/selenium/webdriver/guard_spec.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# 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.
+
+require_relative 'spec_helper'
+
+module Selenium
+  module WebDriver
+    module SpecSupport
+      describe Guards, exclusive: {driver: :chrome} do
+        describe '#exclude' do
+          it 'ignores an unrecognized guard parameter', invalid: {browser: :chrome} do
+            # pass
+          end
+
+          it 'skips without running', exclude: {browser: :chrome} do
+            puts "This code will not get executed"
+          end
+        end
+
+        describe '#exclusive' do
+          it 'skips without running if it does not match', exclusive: {browser: :not_chrome} do
+            puts "This code will not get executed"
+          end
+
+          it 'does not guard if it does match', exclusive: {browser: :chrome} do
+            # pass
+          end
+        end
+
+        describe '#only' do
+          it 'guards when value does not match', only: {browser: :not_chrome} do
+            fail
+          end
+
+          it 'does not guard when value matches', only: {browser: :chrome} do
+            # pass
+          end
+        end
+
+        describe '#except' do
+          it 'guards when value matches and test fails', except: {browser: :chrome} do
+            fail
+          end
+
+          it 'does not guard when value does not match and test passes', except: {browser: :not_chrome} do
+            # pass
+          end
+        end
+
+        context 'when multiple guards' do
+          it 'guards if neither only nor except match and test fails', only: {browser: :not_chrome},
+                                                                       except: {browser: :not_chrome} do
+            fail
+          end
+
+          it 'guards if both only and except match', only: {browser: :chrome},
+                                                     except: {browser: :chrome} do
+            fail
+          end
+
+          it 'guards if except matches and only does not', only: {browser: :not_chrome},
+                                                           except: {browser: :chrome} do
+            fail
+          end
+
+          it 'does not guard if only matches and except does not', only: {browser: :chrome},
+                                                                   except: {browser: :not_chrome} do
+            # pass
+          end
+        end
+
+        context 'when array of hashes' do
+          it 'guards if any Hash value is satisfied', only: [{browser: :chrome}, {browser: :not_chrome}] do
+            fail
+          end
+        end
+
+        context 'guard messages on failing tests' do
+          it 'gives correct message with single only excludes', except: [{browser: :chrome, message: 'bug1'},
+                                                                         {browser: :not_chrome, message: 'bug2'}] do
+            fail
+          end
+        end
+      end
+    end # SpecSupport
+  end # WebDriver
+end # Selenium

rb/spec/integration/selenium/webdriver/remote/driver_spec.rb

@@ -22,7 +22,7 @@
 module Selenium
   module WebDriver
     module Remote
-      describe Driver, only: {driver: :remote} do
+      describe Driver, exclusive: {driver: :remote} do
         it 'should expose session_id' do
           expect(driver.session_id).to be_kind_of(String)
         end

rb/spec/integration/selenium/webdriver/remote/element_spec.rb

@@ -21,7 +21,7 @@
 
 module Selenium
   module WebDriver
-    describe Element, only: {driver: :remote} do
+    describe Element, exclusive: {driver: :remote} do
       before do
         driver.file_detector = ->(filename) { File.join(__dir__, filename) }
       end

rb/spec/integration/selenium/webdriver/safari/driver_spec.rb

@@ -22,7 +22,7 @@
 module Selenium
   module WebDriver
     module Safari
-      describe Driver, only: {driver: %i[safari safari_preview]} do
+      describe Driver, exclusive: {driver: %i[safari safari_preview]} do
         it 'gets and sets permissions' do
           driver.permissions = {'getUserMedia' => false}
           expect(driver.permissions).to eq('getUserMedia' => false)

rb/spec/integration/selenium/webdriver/spec_helper.rb

@@ -50,10 +50,13 @@
 
   c.before do |example|
     guards = WebDriver::SpecSupport::Guards.new(example)
-    if guards.exclude.any?
-      skip 'Bug Prevents Execution.'
-    elsif guards.except.satisfied.any? || guards.only.unsatisfied.any?
-      ENV['SKIP_PENDING'] ? skip('Skip Guarded Spec') : pending('Guarded.')
+
+    skip_guard = guards.exclusive.unsatisfied.first || guards.exclude.satisfied.first
+    skip skip_guard.message if skip_guard
+
+    matching_guard = guards.except.satisfied.first || guards.only.unsatisfied.first
+    if matching_guard
+      ENV['SKIP_PENDING'] ? skip(matching_guard.message) : pending(matching_guard.message)
     end
   end
 

rb/spec/integration/selenium/webdriver/spec_support/guards.rb

@@ -23,7 +23,7 @@ module SpecSupport
       class Guards
         include Enumerable
 
-        GUARD_TYPES = %i[except only exclude].freeze
+        GUARD_TYPES = %i[except only exclude exclusive].freeze
 
         def initialize(example, guards = nil)
           @example = example
@@ -43,7 +43,11 @@ def only
         end
 
         def exclude
-          self.class.new(@example, @guards.select(&:exclude?)).satisfied
+          self.class.new(@example, @guards.select(&:exclude?))
+        end
+
+        def exclusive
+          self.class.new(@example, @guards.select(&:exclusive?))
         end
 
         def satisfied

rb/spec/integration/selenium/webdriver/spec_support/guards/guard.rb

@@ -22,9 +22,20 @@ module WebDriver
     module SpecSupport
       class Guards
         class Guard
+
+          attr_reader :message
+
           def initialize(guard, type)
             @type = type
 
+            reason = guard.delete(:message) || 'no reason given.'
+            @message = if @type == :exclude
+                         "Test not guarded because it breaks test run; #{reason}."
+                       elsif @type == :exclusive
+                         'Test does not apply to this configuration.'
+                       else
+                         "Test guarded; #{reason}."
+                       end
             @drivers = []
             @browsers = []
             @platforms = []
@@ -35,18 +46,26 @@ def initialize(guard, type)
             expand_platforms(guard)
           end
 
+          # Bug is present on all configurations specified
           def except?
             @type == :except
           end
 
+          # Bug is present on all configurations not specified
           def only?
             @type == :only
           end
 
+          # Bug is present on all configurations specified, but test can not be run because it breaks other tests
           def exclude?
             @type == :exclude
           end
 
+          # Test only applies to configurations specified
+          def exclusive?
+            @type == :exclusive
+          end
+
           def satisfied?
             satisfies_driver? && satisfies_browser? && satisfies_platform? && satisfies_window_manager?
           end