testable 0.10.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 025f6e480d7fcc805e5f5315133169d8544210a60107b71436f5eb0564056175
-  data.tar.gz: 0111cd004bfcdcc8f64b889a5edd5728922d77a24349f9e05003422f3b491f55
+  metadata.gz: 7eb4a3420ccd34f95f57425fdd3575900c1c47d46235cba1d0b8554779a0a62a
+  data.tar.gz: 8282d00a7c70a5ccc49a68f1e4eea23c6c0ff94955f6aad9ec4654931e9cd762
 SHA512:
-  metadata.gz: 65992ba040e1175ceded847c9a7024c80e9b52bf0c5f08a51a7ff53964a4cff39a43c9de44d0c6e172b64ea3d31eda09c35066d809e10f7260743aee86b14440
-  data.tar.gz: a1f782e5b1f3a7d19247b2e02e7b415061de7e4be4a24a8593e7173ebf81a33e5499b86c3cc85826445eef58281904ffe7cea64a2e69c581e44e942e81b5a59f
+  metadata.gz: b4f74bec001c20d76044ea642f8686b49ef4171ea6e71548516627adcdbc6a52f3fb17ed2c2ec43b78a4d1d85fd3022a3cf10e17a2fcd841f89a34a174fe66f1
+  data.tar.gz: a10187fd520ee7c7cc22b8c4cc6b4d6f622410f305d6ff1a1587ba0f4ae4047e4d409fc5e17e45f909828355337be312fcdbcb1465357a5340eb8e9e8d99a00f

data/.hound.yml

@@ -1,9 +1,22 @@
 AllCops:
+  EnabledByDefault: true
   Exclude:
     - testable.gemspec
     - spec/**/*
     - examples/**/*
 
+# For now, it is permissible to disable and enable Rubocop checks.
+Style/DisableCopsWithinSourceCodeDirective:
+  Enabled: false
+
+# Do not require parentheses with methods that take arguments.
+Style/MethodCallWithArgsParentheses:
+  Enabled: false
+
+# Do not enforce copyright messaging.
+Style/Copyright:
+  Enabled: false
+
 # Removing need for frozen string literal comment.
 Style/FrozenStringLiteralComment:
   Enabled: false
@@ -30,11 +43,11 @@ Style/SignalException:
   Enabled: false
 
 # This never works for validations.
-Layout/AlignHash:
+Layout/HashAlignment:
   EnforcedLastArgumentHashStyle: ignore_implicit
 
 # Align multi-line params with previous line.
-Layout/AlignParameters:
+Layout/ParameterAlignment:
   EnforcedStyle: with_fixed_indentation
 
 # Indent `when` clause one step from `case`.
@@ -59,7 +72,7 @@ Metrics/MethodLength:
 
 # Encourage short (as possible) modules.
 Metrics/ModuleLength:
-  Max: 100
+  Max: 105
 
 # Encourage fewer parameters.
 Metrics/ParameterLists:
@@ -69,11 +82,19 @@ Metrics/ParameterLists:
 Lint/ScriptPermission:
   Enabled: false
 
+# Not requiring fully qualified constants.
+Lint/ConstantResolution:
+  Enabled: false
+
+# Do not require gem descriptions
+Bundler/GemComment:
+  Enabled: false
+
 # Testable Exceptions
 
 # Allow methods with has_ for predicates.
 Naming/PredicateName:
-  NameWhitelist:
+  AllowedMethods:
     - has_correct_title?
     - has_correct_url?
 

data/Gemfile

@@ -1,6 +1,4 @@
 source "https://rubygems.org"
 
-gem "coveralls", require: false
-
 # Specify your gem's dependencies in testable.gemspec
 gemspec

data/README.md

@@ -14,7 +14,7 @@
 [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/jeffnyman/testable/master/frames)
 [![Inline docs](http://inch-ci.org/github/jeffnyman/testable.png)](http://inch-ci.org/github/jeffnyman/github)
 
-Testable is an automated test micro-framework that provides a thin wrapper around [Watir](http://watir.com/) and [Capybara](http://teamcapybara.github.io/capybara/). Testable is based on many ideas from tools like [SitePrism](https://github.com/natritmeyer/site_prism) and [Watirsome](https://github.com/p0deje/watirsome), while also being a logical evolution of my own tool, [Tapestry](https://github.com/jeffnyman/tapestry).
+Testable is an automated test micro-framework that provides a thin wrapper around [Watir](http://watir.com/). Testable is based on many ideas from tools like [SitePrism](https://github.com/natritmeyer/site_prism) and [Watirsome](https://github.com/p0deje/watirsome), while also being a logical evolution of my own tool, [Tapestry](https://github.com/jeffnyman/tapestry).
 
 One of the core goals of Testable is to be a mediating influence between higher-level tests (acceptance criteria) and lower-level implementations of those tests. You can see some of the design principles for more details on what guided construction.
 
@@ -60,7 +60,15 @@ An automated test framework provides a machine-executable abstraction around tes
 
 One of the obstacles to covering the gap between principles of testing and the practice of testing is the mechanics of writing tests. These mechanics are focused on abstractions. A lot of the practice of testing comes down to that: finding the right abstractions.
 
-An automated test framework should be capable of consuming your preferred abstractions because ultimately the automation is simply a tool that supports testing, which means how the framework encourages tests to be expressed should have high fidelity with how human tests would be expressed.
+An automated test framework should be capable of consuming your preferred abstractions because ultimately the automation is simply a tool that supports testing, which means how the framework encourages tests to be expressed should have high fidelity with how human tests would be expressed. The execution of tests, whether automated or not, is often secondary to the design of those tests in the first place. Testable was designed around a couple of truisms:
+
+* When tests become automation:
+  * We risk turning testing into a programming problem.
+
+* When tests become automation:
+  * We risk the mechanisms overwhelming the meaning.
+
+This is why Testable is designed as a _micro_-framework rather than a framework.
 
 Testable is built around the the idea that automation should largely be small-footprint, low-fiction, and high-yield.
 
@@ -68,6 +76,21 @@ The code that a test-supporting micro-framework allows should be modular, promot
 
 That makes the automation code less expensive to maintain and easier to change. That, ultimately, has a positive impact on the cost of change but, more importantly, allows Testable to be fit within a cost of mistake model, where the goal is to get feedback as quickly as possible regarding when mistakes are made.
 
+Some of the core principles of Testable's design are the following:
+
+* Embrace small code.
+* Abstraction encourages clarity.
+* No computation is too small to be put into a helper function.
+* No expression is too simple to be given a name.
+* Small code is more easily seen to be obviously correct.
+* Code that's more obviously correct can be more easily composed.
+
+The above also led to some secondary, but no less important, principles of design:
+
+* Be willing to trade elegance of design for practicality of implementation.
+* Embrace brevity, but do not sacrifice readability. Concise, not terse.
+* Prefer elegance over efficiency where efficiency is less than critical.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec:all` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/testable.rb

@@ -1,6 +1,7 @@
 require "testable/version"
 require "testable/page"
 require "testable/ready"
+require "testable/region"
 require "testable/logger"
 require "testable/context"
 require "testable/element"
@@ -8,32 +9,71 @@ require "testable/locator"
 require "testable/attribute"
 require "testable/deprecator"
 
-require "testable/capybara/page"
-
 require "testable/extensions/core_ruby"
 require "testable/extensions/data_setter"
 require "testable/extensions/dom_observer"
 
 require "watir"
-require "capybara"
 
 module Testable
+  # This is the core method of Testable which makes the various components
+  # of the framework available to tests.
   def self.included(caller)
     caller.extend Testable::Pages::Attribute
     caller.extend Testable::Pages::Element
+    caller.extend Testable::Pages::Region
     caller.__send__ :include, Testable::Ready
     caller.__send__ :include, Testable::Pages
     caller.__send__ :include, Testable::Element::Locator
     caller.__send__ :include, Testable::DataSetter
   end
 
-  def initialize(browser = nil, &block)
+  # Initialization is used to establish a browser instance within the
+  # context of the framework. The logic here requires determining under
+  # what condition a browser instance may have been set.
+  def initialize(browser = nil, region_element = nil, parent = nil, &block)
     @browser = Testable.browser unless Testable.browser.nil?
     @browser = browser if Testable.browser.nil?
-    begin_with if respond_to?(:begin_with)
+    @region_element = region_element || Testable.browser
+    @parent = parent
+    definition_setup
     instance_eval(&block) if block
   end
 
+  # This method is used to setup any definitions provided as part of the
+  # executable of Testable. This generally means any page definitions that
+  # include Testable.
+  def definition_setup
+    begin_with if respond_to?(:begin_with)
+    initialize_page if respond_to?(:initialize_page)
+    initialize_region if respond_to?(:initialize_region)
+    initialize_regions
+  end
+
+  # This method is used to interate through any definitions that provide
+  # an "initialize_region" method. What happens here is essentially that
+  # new polymorphic modules are created based on classes. This is what
+  # allows a region to be part of a page definition, the latter of which
+  # is nothing more than a standard Ruby class.
+  def initialize_regions
+    @initialized_regions ||= []
+
+    # The goal here is get all included and extended modules.
+    modules = self.class.included_modules + (class << self; self end).included_modules
+    modules.uniq!
+
+    # Then each of those modules can be initialized.
+    modules.each do |m|
+      # First a check is made the that constructor is defined and that it has
+      # not been called before.
+      next if @initialized_regions.include?(m) || !m.instance_methods.include?(:initialize_region)
+
+      m.instance_method(:initialize_region).bind(self).call
+
+      @initialized_regions << m
+    end
+  end
+
   # This accessor is needed so that internal API calls, like `markup` or
   # `text`, have access to the browser instance. This is also necessary
   # in order for element handling to be called appropriately on the a
@@ -41,6 +81,14 @@ module Testable
   # browser Testable is using.
   attr_accessor :browser
 
+  # This accessor is needed so that the region_element is recognized as
+  # part of the overall execution context of Testable.
+  attr_reader :region_element
+
+  # This accessor is needed so that the parent of a region is recognized as
+  # part of the overall execution context of Testable.
+  attr_reader :parent
+
   class << self
     # Provides a means to allow a configure block on Testable. This allows you
     # to setup Testable, as such:
@@ -130,23 +178,29 @@ module Testable
     #
     # Watir.logger.output = "wire.log"
 
+    # Path for the logger to use.
     def wire_path=(logdev)
       Watir.logger.reopen(logdev)
     end
 
+    # Level of logging.
     def wire_level_logging=(value)
       Watir.logger.level = value
     end
 
+    # Report the current logging level.
     def wire_level_logging
       %i[DEBUG INFO WARN ERROR FATAL UNKNOWN][Watir.logger.level]
     end
 
+    # Returns information about the API that Watir exposes. This does not
+    # include Selenium elements, which Watir is wrapping.
     def watir_api
       browser.methods - Object.public_methods -
         Watir::Container.instance_methods
     end
 
+    # Returns information about the API that is specific to Selenium.
     def selenium_api
       browser.driver.methods - Object.public_methods
     end
@@ -156,6 +210,9 @@ module Testable
     # access to the browser.
     attr_accessor :browser
 
+    # This sets the browser instance so that Testable is aware of what that
+    # instance is. This is how a test, using the Testable framework, will
+    # be able to know which browser to communicate with.
     def set_browser(app = :chrome, *args)
       @browser = Watir::Browser.new(app, *args)
       Testable.browser = @browser
@@ -163,10 +220,15 @@ module Testable
 
     alias start_browser set_browser
 
+    # Generates a quit event on the browser instance. This is passed through
+    # to Watir which will ultimately delegate browser handling to Selenium
+    # and thus WebDriver.
     def quit_browser
       @browser.quit
     end
 
+    # This provides the API that is defined by Testable when you have a
+    # working model, such as a page object.
     def api
       methods - Object.public_methods
     end

data/lib/testable/attribute.rb

@@ -5,31 +5,53 @@ module Testable
     module Attribute
       include Situation
 
+      # This is an attribute that can be specified on a model, such as a page
+      # object. When this attribute is provided, the model will have a URL
+      # that can be navigated to automatically by Testable.
       def url_is(url = nil)
         url_is_empty if url.nil? && url_attribute.nil?
         url_is_empty if url.nil? || url.empty?
         @url = url
       end
 
+      # This allows a test to query for the url attribute that was set on the
+      # model. It's important to note that this is not the actual URL in the
+      # browser, but rather whatever was created on the model.
       def url_attribute
         @url
       end
 
+      # This is an attribute that can be specified on a model, such as a page
+      # object. When this attribute is provided, the model will have a way to
+      # match the URL in the browser with the matcher provided via this
+      # attribute.
       def url_matches(pattern = nil)
         url_match_is_empty if pattern.nil?
         url_match_is_empty if pattern.is_a?(String) && pattern.empty?
         @url_match = pattern
       end
 
+      # This allows a test to query for the url match attribute that was set
+      # on the model. This does not perform a match or do anything to check
+      # if a URL is matching. This simply returns the attribute that was
+      # provided for the URL matching.
       def url_match_attribute
         @url_match
       end
 
+      # This is an attribute that can be specified on a model, such as a page
+      # object. When this attribute is provided, the model will have a bit of
+      # text that provides information about what the title of a browser page
+      # should be. This is not checking the title; it's simply providing the
+      # text that will be checked against the actual title.
       def title_is(title = nil)
         title_is_empty if title.nil? || title.empty?
         @title = title
       end
 
+      # This allows a test to query for the title attribute that was set on
+      # the model. It's important to note that this is not the actual title
+      # in the browser, but rather whatever was created on the model.
       def title_attribute
         @title
       end

data/lib/testable/deprecator.rb

@@ -1,6 +1,8 @@
 module Testable
   class Deprecator
     class << self
+      # This is used to indicate that certain functionality within Testable
+      # has been deprecated and the previous functionality will disappear.
       def deprecate(current, upcoming = nil, known_version = nil)
         if upcoming
           warn(
@@ -16,6 +18,10 @@ module Testable
         ) if known_version
       end
 
+      # This is used to indicate that certain functionality within Testable
+      # has been soft deprecated, meaning that some aspect of how the
+      # framework is configured has changed and that change will become
+      # the new default behavior in a given version.
       def soft_deprecate(current, reason, known_version, upcoming = nil)
         debug("The #{current} method is changing and is now configurable.")
         debug("REASON: #{reason}.")

data/lib/testable/element.rb

@@ -4,19 +4,69 @@ module Testable
   module_function
 
   NATIVE_QUALIFIERS = %i[visible].freeze
+  private_constant :NATIVE_QUALIFIERS
 
+  # This predicate method returns all of the elements that can be recognized
+  # by Watir.
   def elements?
     @elements
   end
 
+  # This predicate method checks if a given element is in the list of known
+  # elements that Watir knows how to interact with.
   def recognizes?(method)
     @elements.include? method.to_sym
   end
 
+  # Provides a list of all elements that Watir knows how to work with. This
+  # is generated from the Watir container itself so the list should always
+  # be up to date.
   def elements
     @elements ||= Watir::Container.instance_methods unless @elements
   end
 
+  # This predicate method checks if a given element is a valid element that
+  # Watir knows how to interact with, but in plural form.
+  #
+  # @example
+  #   Testable.recognizes?(:spans) # => true
+  #   Testable.recognizes?(:divs) # => true
+  #   Testable.recognizes?(:class) # => false
+  #   Testable.recognizes?(:classes) # => false
+  def plural?(method)
+    value = method.to_s
+    plural = value.to_sym
+
+    # Remove the trailing "s" or "es" to de-pluralize.
+    single = value.sub(/e?s$/, '').to_sym
+
+    !value.match(/s$/).nil? &&
+      @elements.include?(plural) &&
+      @elements.include?(single)
+  end
+
+  # This method will allow a particular element name to be pluralized.
+  #
+  # @example
+  #   Empirical.pluralize(:div) => divs
+  #   Empirical.pluralize(:checkbox) => checkboxes
+  def self.pluralize(method)
+    value = method.to_s
+
+    # This bit is not what you would call optimized. Essentially, it just
+    # tries to ppluralize with "s" and see if that method is included in the
+    # Watir methods. If that fails, then an attempt to pluralize with "es" is
+    # tried. If that fails, the assumption is made that a pluralized form of
+    # the Watir method does not exist.
+    if @elements.include?(:"#{value}s")
+      :"#{value}s"
+    elsif @elements.include?(:"#{value}es")
+      :"#{value}es"
+    else
+      raise Testable::Errors::PluralizedElementError, "Unable to find plural form for #{value}!"
+    end
+  end
+
   module Pages
     module Element
       # This iterator goes through the Watir container methods and
@@ -173,14 +223,17 @@ module Testable
       # like this: ["Drag and Drop"].
       def define_element_accessor(identifier, *signature, element, &block)
         locators, qualifiers = accessor_aspects(element, signature)
-        define_method(identifier.to_s) do |*values|
-          if block_given?
-            instance_exec(*values, &block)
-          else
-            locators = values[0] if locators.empty?
-            access_element(element, locators, qualifiers)
+
+        include(Module.new do
+          define_method(identifier.to_s) do |*values|
+            if block_given?
+              instance_exec(*values, &block)
+            else
+              locators = values[0] if locators.empty?
+              access_element(element, locators, qualifiers)
+            end
           end
-        end
+        end)
       end
     end
   end