testable 0.10.0 → 1.0.0

data/lib/testable/errors.rb

@@ -1,3 +1,4 @@
+# rubocop:disable Style/DocumentationMethod
 module Testable
   module Errors
     NoUrlForDefinition = Class.new(StandardError)
@@ -5,6 +6,18 @@ module Testable
     NoUrlMatchPossible = Class.new(StandardError)
     NoTitleForDefinition = Class.new(StandardError)
     PageNotValidatedError = Class.new(StandardError)
+    PluralizedElementError = Class.new(StandardError)
+    RegionNamespaceError = Class.new(StandardError)
+    RegionFinderError = Class.new(StandardError)
+
+    public_constant :NoUrlForDefinition
+    public_constant :NoUrlMatchForDefinition
+    public_constant :NoUrlMatchPossible
+    public_constant :NoTitleForDefinition
+    public_constant :PageNotValidatedError
+    public_constant :PluralizedElementError
+    public_constant :RegionNamespaceError
+    public_constant :RegionFinderError
 
     class PageURLFromFactoryNotVerified < StandardError
       def message
@@ -13,3 +26,4 @@ module Testable
     end
   end
 end
+# rubocop:enable Style/DocumentationMethod

data/lib/testable/extensions/core_ruby.rb

@@ -1,3 +1,5 @@
+# rubocop:disable Style/DocumentationMethod
+
 class String
   # This is only required if using a version of Ruby before 2.4. A match?
   # method for String was added in version 2.4.
@@ -11,3 +13,5 @@ class FalseClass
     false
   end
 end
+
+# rubocop:enable Style/DocumentationMethod

data/lib/testable/extensions/data_setter.rb

@@ -20,9 +20,9 @@ class Object
 
     method_chain.split('.').inject(self) do |o, m|
       if data.nil?
-        o.send(m.intern)
+        o.public_send(m.to_sym)
       else
-        o.send(m.intern, data)
+        o.public_send(m.to_sym, data)
       end
     end
   end
@@ -80,7 +80,7 @@ module Testable
     def use_data_with(key, value)
       value = preprocess_value(value, key)
 
-      element = send(key.to_s.tr(' ', '_'))
+      element = public_send(key.to_s.tr(' ', '_'))
       set_and_select(key, element, value)
       check_and_uncheck(key, element, value)
       click(key, element)
@@ -107,6 +107,8 @@ module Testable
         selected = list.sample.text
         selected = list.sample.text if selected.nil?
         value = selected
+      else # rubocop:disable Style/EmptyElse
+        # Silent pass through.
       end
 
       value
@@ -137,7 +139,7 @@ module Testable
     # visible (meaning, display is not 'none'), and is capable of accepting
     # input, thus being enabled.
     def object_enabled_for(key)
-      web_element = send(key.to_s.tr(' ', '_'))
+      web_element = public_send(key.to_s.tr(' ', '_'))
       web_element.enabled? && web_element.present?
     end
   end

data/lib/testable/extensions/dom_observer.rb

@@ -2,6 +2,8 @@ module Watir
   class Element
     OBSERVER_FILE = "/dom_observer.js".freeze
     DOM_OBSERVER = File.read("#{File.dirname(__FILE__)}#{OBSERVER_FILE}").freeze
+    private_constant :OBSERVER_FILE
+    private_constant :DOM_OBSERVER
 
     # This method makes a call to `execute_async_script` which means that the
     # DOM observer script must explicitly signal that it is finished by

data/lib/testable/locator.rb

@@ -45,11 +45,49 @@ module Testable
       # validation. That's necessary because a ready validation has to find
       # an element in order to determine the ready state, but that element
       # might not be present.
-      def access_element(element, locators, _qualifiers)
-        if element == "element".to_sym
-          @browser.element(locators).to_subtype
+
+      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/MethodLength
+      def access_element(element, locators, qualifiers)
+        if qualifiers.empty?
+          if element == "element".to_sym
+            @browser.element(locators).to_subtype
+          else
+            region_element.__send__(element, locators)
+          end
         else
-          @browser.__send__(element, locators)
+          # If the qualifiers are not empty, then that means the framework
+          # has to consider a given set of elements so that it can check
+          # the qualifier against them.
+          plural = Testable.plural?(element)
+          element = Testable.pluralize(element) unless plural
+
+          elements = region_element.__send__(element, locators)
+
+          # Consider the following element definition:
+          #
+          # select_list :car_make, name: 'car', selected: 'Audi', enabled: true
+          #
+          # In this case, the qualifiers will be `selected` (with a value of)
+          # "Audi") and `enabled` (with a value of true. The arity of the
+          # `selected` method would be 1 while the arity of the `enabled`
+          # method would be 0.
+          qualifiers.each do |qualifier, value|
+            elements.to_a.select! do |ele|
+              if ele.public_method(:"#{qualifier}?").arity.zero?
+                ele.__send__(:"#{qualifier}?") == value
+              else
+                ele.__send__(:"#{qualifier}?", value)
+              end
+            end
+          end
+
+          # If the locator passed in was plural, then any elements matching
+          # the locator and qualifier have to be returned. Otherwise, it will
+          # just be the first item of the elements found.
+          plural ? elements : elements.first
         end
       rescue Watir::Exception::UnknownObjectException
         return false if caller_locations.any? do |str|
@@ -58,6 +96,10 @@ module Testable
 
         raise
       end
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/MethodLength
     end
   end
 end

data/lib/testable/logger.rb

@@ -2,13 +2,17 @@ require "logger"
 
 module Testable
   class Logger
+    # Creates a logger instance with a predefined set of configuration
+    # options. This logger instance will be available to any portion of
+    # tests that are using the framework.
     def create(output = $stdout)
       logger = ::Logger.new(output)
       logger.progname = 'Testable'
       logger.level = :UNKNOWN
-      logger.formatter = proc do |severity, time, progname, msg|
-        "#{time.strftime('%F %T')} - #{severity} - #{progname} - #{msg}\n"
-      end
+      logger.formatter =
+        proc do |severity, time, progname, msg|
+          "#{time.strftime('%F %T')} - #{severity} - #{progname} - #{msg}\n"
+        end
 
       logger
     end

data/lib/testable/region.rb

@@ -0,0 +1,173 @@
+module Testable
+  module Pages
+    module Region
+      # Allows for a "has_one" method to be declared on a model, like a page
+      # object to specify that the model has a region associated with it. In
+      # this case, that would be a single region that can be located by a
+      # reference to a specific class (which is also a model) and, relative
+      # to that model, is within some specific means of identification.
+      # rubocop:disable Naming/PredicateName
+      def has_one(identifier, **context, &block)
+        within = context[:in] || context[:within]
+        region_class = context[:class] || context[:region_class]
+        define_region_accessor(identifier, within: within, region_class: region_class, &block)
+      end
+
+      # Allows for a "has_many" method to be declared on a model, like a poage
+      # object to specify that the model was a certain region associated with
+      # it, but where that region occurs more than once.
+      def has_many(identifier, **context, &block)
+        region_class = context[:class] || context[:region_class]
+        collection_class = context[:through] || context[:collection_class]
+        each = context[:each] || raise(ArgumentError, 'the "has_many" method requires an "each" param')
+        within = context[:in] || context[:within]
+        define_region_accessor(
+          identifier,
+          within: within,
+          each: each,
+          region_class: region_class,
+          collection_class: collection_class,
+          &block
+        )
+        define_finder_method(identifier)
+      end
+      # rubocop:enable Naming/PredicateName
+
+      private
+
+      # Defines an accessor method for an region.
+      # ..........................
+      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable Metrics/BlockLength
+      # rubocop:disable Metrics/BlockNesting
+      # def define_region_accessor(identifier, within: nil, each: nil, collection_class: nil, region_class: nil, &block)
+      def define_region_accessor(identifier, within: nil, each: nil, region_class: nil, collection_class: nil, &block)
+        include(Module.new do
+          define_method(identifier) do
+            # The class path is what essentially determines the model to
+            # reference that the region is a part of. However, it is possible
+            # to define an inline region, which would effectively make the
+            # class anonymous, and thus not having an actual name. Thus is it
+            # necessary to provide a stand-in name for those cases.
+            class_path = self.class.name ? self.class.name.split('::') : ['TestableRegion']
+
+            # Namespacing is needed in cases where there are nested classes.
+            # It's important to get the full namespace of any classes that are
+            # said to reference the region.
+            namespace =
+              if class_path.size > 1
+                class_path.pop
+                Object.const_get(class_path.join('::'))
+              elsif class_path.size == 1
+                self.class
+              else
+                raise Testable::Errors::RegionNamespaceError, "Cannot understand namespace from #{class_path}"
+              end
+
+            # A copy of the passed-in region class is necessary because the
+            # `region_class` is declared outside of this defined function.
+            # And the function could change that class. Thus a reference is
+            # needed to the original `region_class` but also allowing for that
+            # class to be changed.
+            region_single_class = region_class
+
+            unless region_single_class
+              if block_given?
+                region_single_class = Class.new
+                region_single_class.class_eval { include(Testable) }
+                region_single_class.class_eval(&block)
+              else
+                singular_klass = identifier.to_s.split('_').map(&:capitalize).join
+
+                # rubocop:disable Style/MissingElse
+                if each
+                  collection_class_name = "#{singular_klass}Region"
+                  singular_klass = singular_klass.sub(/s\z/, '')
+                end
+                # rubocop:enable Style/MissingElse
+
+                singular_klass << 'Region'
+                region_single_class = namespace.const_get(singular_klass)
+              end
+            end
+
+            # The scope is used to provide a reference to the element that
+            # is said to act as a container for the region.
+            scope =
+              case within
+                when Proc
+                  instance_exec(&within)
+                when Hash
+                  region_element.element(within)
+                else
+                  region_element
+              end
+
+            if each
+              # The `elements` will be a `Watir::HTMLElementCollection`.
+              elements = (scope.exists? ? scope.elements(each) : [])
+
+              if collection_class_name && namespace.const_defined?(collection_class_name)
+                region_collection_class = namespace.const_get(collection_class_name)
+              elsif collection_class
+                region_collection_class = collection_class
+              else
+                return elements.map { |element| region_single_class.new(@browser, element, self) }
+              end
+
+              region_collection_class.class_eval do
+                include Enumerable
+
+                attr_reader :region_collection
+
+                define_method(:initialize) do |browser, region_element, region_elements|
+                  super(browser, region_element, self)
+
+                  @region_collection =
+                    if region_elements.all? { |element| element.is_a?(Watir::Element) }
+                      region_elements.map { |element| region_single_class.new(browser, element, self) }
+                    else
+                      region_elements
+                    end
+                end
+
+                def each(&block)
+                  region_collection.each(&block)
+                end
+              end
+
+              region_collection_class.new(@browser, scope, elements)
+            else
+              region_single_class.new(@browser, scope, self)
+            end
+          end
+        end)
+      end
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:enable Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/ParameterLists
+      # rubocop:enable Metrics/BlockLength
+      # rubocop:enable Metrics/BlockNesting
+
+      def define_finder_method(identifier)
+        finder_method_name = identifier.to_s.sub(/s\z/, '')
+
+        include(Module.new do
+          define_method(finder_method_name) do |**opts|
+            __send__(identifier).find do |entity|
+              opts.all? do |key, value|
+                entity.__send__(key) == value
+              end
+            end || raise(Testable::Errors::RegionFinderError, "No #{finder_method_name} matching: #{opts}.")
+          end
+        end)
+      end
+    end
+  end
+end

data/lib/testable/version.rb

@@ -1,23 +1,27 @@
 module Testable
   module_function
 
-  VERSION = "0.10.0".freeze
+  VERSION = "1.0.0".freeze
+  public_constant :VERSION
 
+  # Returns version information about Testable and its core dependencies.
   def version
     """
 Testable v#{Testable::VERSION}
 watir: #{gem_version('watir')}
 selenium-webdriver: #{gem_version('selenium-webdriver')}
-capybara: #{gem_version('capybara')}
     """
   end
 
+  # Returns a gem version for a given gem, assuming the gem has
+  # been loaded.
   def gem_version(name)
     Gem.loaded_specs[name].version
   rescue NoMethodError
     puts "No gem loaded for #{name}."
   end
 
+  # Returns all of the dependencies that Testable relies on.
   def dependencies
     Gem.loaded_specs.values.map { |spec| "#{spec.name} #{spec.version}\n" }
        .uniq.sort.join(",").split(",")

data/testable.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Jeff Nyman"]
   spec.email         = ["jeffnyman@gmail.com"]
 
-  spec.summary       = %q{Web and API Automation, using Capybara and Watir}
+  spec.summary       = %q{Web and API Automation, using Watir}
   spec.description   = %q{Provides a semantic DSL to construct fluent interfaces for test execution logic.}
   spec.homepage      = "https://github.com/jeffnyman/testable"
   spec.license       = "MIT"
@@ -31,12 +31,10 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", ">= 12.3.3"
   spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "simplecov"
   spec.add_development_dependency "rubocop"
   spec.add_development_dependency "pry"
 
   spec.add_runtime_dependency "watir", ["~> 6.16"]
-  spec.add_runtime_dependency "capybara", [">= 2", "< 4"]
 
   spec.post_install_message = %{
 (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: testable
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Jeff Nyman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-11 00:00:00.000000000 Z
+date: 2020-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,20 +52,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -108,26 +94,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.16'
-- !ruby/object:Gem::Dependency
-  name: capybara
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4'
 description: Provides a semantic DSL to construct fluent interfaces for test execution
   logic.
 email:
@@ -148,9 +114,6 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- examples/testable-capybara-context.rb
-- examples/testable-capybara-rspec.rb
-- examples/testable-capybara.rb
 - examples/testable-info.rb
 - examples/testable-watir-context.rb
 - examples/testable-watir-datasetter.rb
@@ -160,9 +123,6 @@ files:
 - examples/testable-watir.rb
 - lib/testable.rb
 - lib/testable/attribute.rb
-- lib/testable/capybara/dsl.rb
-- lib/testable/capybara/node.rb
-- lib/testable/capybara/page.rb
 - lib/testable/context.rb
 - lib/testable/deprecator.rb
 - lib/testable/element.rb
@@ -175,6 +135,7 @@ files:
 - lib/testable/logger.rb
 - lib/testable/page.rb
 - lib/testable/ready.rb
+- lib/testable/region.rb
 - lib/testable/situation.rb
 - lib/testable/version.rb
 - testable.gemspec
@@ -186,7 +147,7 @@ metadata:
   source_code_uri: https://github.com/jeffnyman/testable
   changelog_uri: https://github.com/jeffnyman/testable/blob/master/CHANGELOG.md
 post_install_message: "\n(::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)\n
-  \ Testable 0.10.0 has been installed.\n(::) (::) (::) (::) (::) (::) (::) (::) (::)
+  \ Testable 1.0.0 has been installed.\n(::) (::) (::) (::) (::) (::) (::) (::) (::)
   (::) (::) (::)\n  "
 rdoc_options: []
 require_paths:
@@ -205,5 +166,5 @@ requirements: []
 rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: Web and API Automation, using Capybara and Watir
+summary: Web and API Automation, using Watir
 test_files: []