testable 0.3.0 → 0.4.0

data/lib/testable/extensions/dom_observer.rb

@@ -0,0 +1,73 @@
+module Watir
+  class Element
+    OBSERVER_FILE = "/dom_observer.js".freeze
+    DOM_OBSERVER = File.read("#{File.dirname(__FILE__)}#{OBSERVER_FILE}").freeze
+
+    # This method makes a call to `execute_async_script` which means that the
+    # DOM observer script must explicitly signal that it is finished by
+    # invoking a callback. In this case, the callback is nothing more than
+    # a delay. The delay is being used to allow the DOM to be updated before
+    # script actions continue.
+    #
+    # The method returns true if the DOM has been changed within the element
+    # context, while false means that the DOM has not yet finished changing.
+    # Note the wording: "has not finished changing." It's known that the DOM
+    # is changing because the observer has recognized that. So the question
+    # this method is helping to answer is "has it finished?"
+    #
+    # Consider the following element definition:
+    #
+    #    p :page_list, id: 'navlist'
+    #
+    # You could then do this:
+    #
+    #    page_list.dom_updated?
+    #
+    # That would return true if the DOM content for page_list has finished
+    # updating. If the DOM was in the process of being updated, this would
+    # return false. You could also do this:
+    #
+    #    page_list.wait_until(&:dom_updated?).click
+    #
+    # This will use Watir's wait until functionality to wait for the DOM to
+    # be updated within the context of the element. Note that the "&:" is
+    # that the object that `dom_updated?` is being called on (in this case
+    # `page_list`) substitutes the ampersand. You can also structure it like
+    # this:
+    #
+    #    page_list.wait_until do |element|
+    #        element.dom_updated?
+    #    end
+    #
+    # The default delay of waiting for the DOM to start updating is 1.1
+    # second. However, you can pass a delay value when you call the method
+    # to set your own value, which can be useful for particular sensitivities
+    # in the application you are testing.
+    def dom_updated?(delay: 1.1)
+      element_call do
+        begin
+          driver.manage.timeouts.script_timeout = delay + 1
+          driver.execute_async_script(DOM_OBSERVER, wd, delay)
+        rescue Selenium::WebDriver::Error::JavascriptError => e
+          # This situation can occur if the script execution has started before
+          # a new page is fully loaded. The specific error being checked for
+          # here is one that occurs when a new page is loaded as that page is
+          # trying to execute a JavaScript function.
+          retry if e.message.include?(
+            'document unloaded while waiting for result'
+          )
+          raise
+        ensure
+          # Note that this setting here means any user-defined timeout would
+          # effectively be overwritten.
+          driver.manage.timeouts.script_timeout = 1
+        end
+      end
+    end
+
+    alias dom_has_updated? dom_updated?
+    alias dom_has_changed? dom_updated?
+    alias when_dom_updated dom_updated?
+    alias when_dom_changed dom_updated?
+  end
+end

data/lib/testable/locator.rb

@@ -0,0 +1,63 @@
+module Testable
+  module Element
+    module Locator
+      private
+
+      # This method is what actually calls the browser instance to find
+      # an element. If there is an element definition like this:
+      #
+      #    text_field :username, id: 'username'
+      #
+      # This will become the following:
+      #
+      #    browser.text_field(id: 'username')
+      #
+      # Note that the `to_subtype` method is called, which allows for the
+      # generic `element` to be expressed as the type of element, as opposed
+      # to `text_field` or `select_list`. For example, an `element` may be
+      # defined like this:
+      #
+      #    element :enable, id: 'enableForm'
+      #
+      # Which means it would look like this:
+      #
+      #    Watir::HTMLElement:0x1c8c9 selector={:id=>"enableForm"}
+      #
+      # Whereas getting the subtype would give you:
+      #
+      #    Watir::CheckBox:0x12f8b elector={element: (webdriver element)}
+      #
+      # Which is what you would get if the element definition were this:
+      #
+      #    checkbox :enable, id: 'enableForm'
+      #
+      # Using the subtype does get tricky for scripts that require the
+      # built-in sychronization aspects and wait states of Watir.
+      #
+      # The approach being used in this method is necessary to allow actions
+      # like `set`, which are not available on `element`, even though other
+      # actions, like `click`, are. But if you use `element` for your element
+      # definitions, and your script requires a series of actions where elements
+      # may be delayed in appearing, you'll get an "unable to locate element"
+      # message, along with a Watir::Exception::UnknownObjectException.
+      #
+      # A check is made if an UnknownObjectException occurs due to a ready
+      # 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
+        else
+          @browser.__send__(element, locators)
+        end
+      rescue Watir::Exception::UnknownObjectException
+        return false if caller_locations.any? do |str|
+          str.to_s.match?("ready_validations_pass?")
+        end
+
+        raise
+      end
+    end
+  end
+end

data/lib/testable/page.rb

@@ -0,0 +1,216 @@
+require "testable/situation"
+
+module Testable
+  module Pages
+    include Situation
+
+    # This provides a list of the methods that are defined on the page
+    # definition. This is helpful is you need to query the page to see
+    # if an element has been provided since all elements automatically
+    # become methods on a definition instance.
+    def definition_api
+      public_methods(false) - Object.public_methods
+    end
+
+    # The `visit` method provides navigation to a specific page by passing
+    # in the URL. If no URL is passed in, this method will attempt to use
+    # the `url_is` attribute from the interface it is being called on.
+    def visit(url = nil, &block)
+      no_url_provided if url.nil? && url_attribute.nil?
+      @browser.goto(url) unless url.nil?
+      @browser.goto(url_attribute) if url.nil?
+      when_ready(&block) if block_given?
+      self
+    end
+
+    alias view        visit
+    alias navigate_to visit
+    alias goto        visit
+    alias perform     visit
+
+    # A call to `url_attribute` returns what the value of the `url_is`
+    # attribute is for the given interface. It's important to note that
+    # this is not grabbing the URL that is displayed in the browser;
+    # rather it's the one declared in the interface definition, if any.
+    def url_attribute
+      self.class.url_attribute
+    end
+
+    # A call to `url` returns the actual URL of the page that is displayed
+    # in the browser.
+    def url
+      @browser.url
+    end
+
+    alias page_url    url
+    alias current_url url
+
+    # A call to `url_match_attribute` returns what the value of the
+    # `url_matches` attribute is for the given interface. It's important
+    # to note that the URL matching mechanism is effectively a regular
+    # expression check.
+    def url_match_attribute
+      value = self.class.url_match_attribute
+      return if value.nil?
+
+      value = Regexp.new(value) unless value.is_a?(Regexp)
+      value
+    end
+
+    # A call to `has_correct_url?`returns true or false if the actual URL
+    # found in the browser matches the `url_matches` assertion. This is
+    # important to note. It's not using the `url_is` attribute nor the URL
+    # displayed in the browser. It's using the `url_matches` attribute.
+    def has_correct_url?
+      no_url_match_is_possible if url_attribute.nil? && url_match_attribute.nil?
+      !(url =~ url_match_attribute).nil?
+    end
+
+    alias displayed? has_correct_url?
+    alias loaded?    has_correct_url?
+
+    # A call to `title_attribute` returns what the value of the `title_is`
+    # attribute is for the given definition. It's important to note that
+    # this is not grabbing the title that is displayed in the browser;
+    # rather it's the one declared in the interface definition, if any.
+    def title_attribute
+      self.class.title_attribute
+    end
+
+    # A call to `title` returns the actual title of the page that is
+    # displayed in the browser.
+    def title
+      @browser.title
+    end
+
+    alias page_title title
+
+    # A call to `has_correct_title?` returns true or false if the actual
+    # title of the current page in the browser matches the `title_is`
+    # attribute. Notice that this check is done as part of a match rather
+    # than a direct check. This allows for regular expressions to be used.
+    def has_correct_title?
+      no_title_is_provided if title_attribute.nil?
+      !title.match(title_attribute).nil?
+    end
+
+    # A call to `secure?` returns true if the page is secure and false
+    # otherwise. This is a simple check that looks for whether or not the
+    # current URL begins with 'https'.
+    def secure?
+      !url.match(/^https/).nil?
+    end
+
+    # A call to `markup` returns all markup on a page. Generally you don't
+    # just want the entire markup but rather want to parse the output of
+    # the `markup` call.
+    def markup
+      browser.html
+    end
+
+    alias html markup
+
+    # A call to `text` returns all text on a page. Note that this is text
+    # that is taken out of the markup context. It is unlikely you will just
+    # want the entire text but rather want to parse the output of the
+    # `text` call.
+    def text
+      browser.text
+    end
+
+    alias page_text text
+
+    # This method provides a call to the synchronous `execute_script`
+    # action on the browser, passing in JavaScript that you want to have
+    # executed against the current page. For example:
+    #
+    #    result = page.run_script("alert('Cogent ran a script.')")
+    #
+    # You can also run full JavaScript snippets.
+    #
+    #    script = <<-JS
+    #      return arguments[0].innerHTML
+    #    JS
+    #
+    #    page.run_script(script, page.account)
+    #
+    # Here you pass two arguments to `run_script`. One is the script itself
+    # and the other are some arguments that you want to pass as part of
+    # of the execution. In this case, an element definition (`account`) is
+    # being passed in.
+    def run_script(script, *args)
+      browser.execute_script(script, *args)
+    end
+
+    alias execute_script run_script
+
+    # A call to `screen_width` returns the width of the browser screen as
+    # reported by the browser API, using a JavaScript call to the `screen`
+    # object.
+    def screen_width
+      run_script("return screen.width;")
+    end
+
+    # A call to `screen_height` returns the height of the browser screen as
+    # reported by the browser API, using a JavaScript call to the `screen`
+    # object.
+    def screen_height
+      run_script("return screen.height;")
+    end
+
+    # This method provides a means to maximize the browser window. This
+    # is done by getting the screen width and height via JavaScript calls.
+    def maximize
+      browser.window.resize_to(screen_width, screen_height)
+    end
+
+    # This method provides a call to the browser window to resize that
+    # window to the specified width and height values.
+    def resize(width, height)
+      browser.window.resize_to(width, height)
+    end
+
+    # This method provides a call to the browser window to move the
+    # window to the specified x and y screen coordinates.
+    def move_to(x_coord, y_coord)
+      browser.window.move_to(x_coord, y_coord)
+    end
+
+    alias resize_to resize
+
+    # This method sends a standard "browser refresh" message to the browser.
+    def refresh
+      browser.refresh
+    end
+
+    alias refresh_page refresh
+
+    # A call to `get_cookie` allows you to specify a particular cookie, by
+    # name, and return the information specified in the cookie.
+    def get_cookie(name)
+      browser.cookies.to_a.each do |cookie|
+        return cookie[:value] if cookie[:name] == name
+      end
+      nil
+    end
+
+    # A call to `clear_cookies` removes all the cookies from the current
+    # instance of the browser that is being controlled by WebDriver.
+    def clear_cookies
+      browser.cookies.clear
+    end
+
+    alias remove_cookies clear_cookies
+
+    # A call to `screenshot` saves a screenshot of the current browser
+    # page. Note that this will grab the entire browser page, even portions
+    # of it that are off panel and need to be scrolled to. You can pass in
+    # the path and filename of the image that you want the screenshot
+    # saved to.
+    def screenshot(file)
+      browser.screenshot.save(file)
+    end
+
+    alias save_screenshot screenshot
+  end
+end

data/lib/testable/ready.rb

@@ -4,7 +4,15 @@ module Testable
   module Ready
     include Situation
 
-    module ClassMethods
+    # The ReadyAttributes contains methods that can be called directly on the
+    # interface class definition. These are very much like the attributes
+    # that are used for defining aspects of the pages, such as `url_is` or
+    # `title_is`. These attributes are included separately so as to maintain
+    # more modularity.
+    module ReadyAttributes
+      # This method will provide a list of the ready_validations that have
+      # been defined. This list will contain the list in the order that the
+      # validations were defined in.
       def ready_validations
         if superclass.respond_to?(:ready_validations)
           superclass.ready_validations + _ready_validations
@@ -13,41 +21,75 @@ module Testable
         end
       end
 
+      # When this attribute method is specified on an interface, it will
+      # append the validation provided by the block.
       def page_ready(&block)
         _ready_validations << block
       end
 
       alias page_ready_when page_ready
 
+      private
+
       def _ready_validations
         @_ready_validations ||= []
       end
     end
 
-    attr_accessor :ready, :ready_error
-
     def self.included(caller)
-      caller.extend(ClassMethods)
+      caller.extend(ReadyAttributes)
     end
 
-    def when_ready(&_block)
+    # If a ready validation fails, the message reported by that failure will
+    # be captured in the `ready_error` accessor.
+    attr_accessor :ready, :ready_error
+
+    # The `when_ready` method is called on an instance of an interface. This
+    # executes the provided validation block after the page has been loaded.
+    # The Ready object instance is yielded into the block.
+    #
+    # Calls to the `ready?` method use a poor-man's cache approach. The idea
+    # here being that when a page has confirmed that it is ready, meaning that
+    # no ready validations have failed, that information is stored so that any
+    # subsequent calls to `ready?` do not query the ready validations again.
+    def when_ready(simple_check = false, &_block)
       already_marked_ready = ready
 
-      no_ready_check_possible unless block_given?
+      unless simple_check
+        no_ready_check_possible unless block_given?
+      end
 
       self.ready = ready?
+
       not_ready_validation(ready_error || 'NO REASON PROVIDED') unless ready
-      yield self
+      yield self if block_given?
     ensure
       self.ready = already_marked_ready
     end
 
+    def check_if_ready
+      when_ready(true)
+    end
+
+    # The `ready?` method is used to check if the page has been loaded
+    # successfully, which means that none of the ready validations have
+    # indicated failure.
+    #
+    # When `ready?` is called, the blocks that were stored in the above
+    # `ready_validations` array are instance evaluated against the current
+    # page instance.
     def ready?
       self.ready_error = nil
       return true if ready
+
       ready_validations_pass?
     end
 
+    private
+
+    # This method checks if the ready validations that have been specified
+    # have passed. If any ready validation fails, no matter if others have
+    # succeeded, this method immediately returns false.
     def ready_validations_pass?
       self.class.ready_validations.all? do |validation|
         passed, message = instance_eval(&validation)

data/lib/testable/situation.rb

@@ -20,13 +20,6 @@ module Testable
       raise Testable::Errors::NoUrlForDefinition
     end
 
-    def url_match_is_empty
-      puts "PROBLEM: url_matches attribute empty.\n" \
-      "The url_matches attribute is empty on the definition " \
-      "'#{retrieve_class(caller)}'.\n\n"
-      raise Testable::Errors::NoUrlMatchForDefinition
-    end
-
     def no_url_match_is_possible
       puts "PROBLEM: No url_is or url_matches attribute.\n" \
       "You called a '#{retrieve_method(caller)}' action but the " \
@@ -35,6 +28,13 @@ module Testable
       raise Testable::Errors::NoUrlMatchPossible
     end
 
+    def url_match_is_empty
+      puts "PROBLEM: url_matches attribute empty.\n" \
+      "The url_matches attribute is empty on the definition " \
+      "'#{retrieve_class(caller)}'.\n\n"
+      raise Testable::Errors::NoUrlMatchForDefinition
+    end
+
     def title_is_empty
       puts "PROBLEM: title_is attribute empty.\n" \
       "The title_is attribute is empty on the definition " \
@@ -49,13 +49,6 @@ module Testable
       raise Testable::Errors::NoTitleForDefinition
     end
 
-    def no_locator(definition, identifier)
-      puts "PROBLEM: No locator provided.\n" \
-      "You are using '#{identifier}' on '#{definition}'. " \
-      "But there is no locator provided with it.\n\n"
-      raise Testable::Errors::NoLocatorForDefinition
-    end
-
     def not_ready_validation(message)
       puts "PROBLEM: A ready validation error was encountered.\n" \
       "A ready validation failed to validate. The ready check was " \
@@ -65,24 +58,12 @@ module Testable
       raise Testable::Errors::PageNotValidatedError, message
     end
 
-    def no_ready_check_possible
-      puts "PROBLEM: A when ready call has no action.\n" \
-      "You called a when_ready on a definition but did not provide " \
-      "any action for it. Add a block with logic that should be " \
-      "executed if the ready check passes.\n\n"
-      raise Testable::Errors::NoBlockForWhenReady
-    end
-
-    def retrieve_class(caller)
-      caller[1][/`.*'/][8..-3]
-    end
-
     def retrieve_method(caller)
       caller[0][/`.*'/][1..-2]
     end
 
-    def empty_locator(locator, values)
-      locator[0].nil? && values.empty? && !values[0].is_a?(Hash)
+    def retrieve_class(caller)
+      caller[1][/`.*'/][8..-3]
     end
   end
 end

data/lib/testable/version.rb

@@ -1,24 +1,25 @@
 module Testable
   module_function
 
-  VERSION = "0.3.0".freeze
+  VERSION = "0.4.0".freeze
 
   def version
     """
 Testable v#{Testable::VERSION}
 watir: #{gem_version('watir')}
 selenium-webdriver: #{gem_version('selenium-webdriver')}
+capybara: #{gem_version('capybara')}
     """
   end
 
-  def dependencies
-    Gem.loaded_specs.values.map { |spec| "#{spec.name} #{spec.version}\n" }
-       .uniq.sort.join(",").split(",")
-  end
-
   def gem_version(name)
     Gem.loaded_specs[name].version
   rescue NoMethodError
     puts "No gem loaded for #{name}."
   end
+
+  def dependencies
+    Gem.loaded_specs.values.map { |spec| "#{spec.name} #{spec.version}\n" }
+       .uniq.sort.join(",").split(",")
+  end
 end

data/lib/testable.rb

@@ -1,34 +1,55 @@
 require "testable/version"
-
+require "testable/page"
 require "testable/ready"
-require "testable/factory"
+require "testable/context"
 require "testable/element"
-require "testable/interface"
-require "testable/dom_update"
-require "testable/data_setter"
+require "testable/locator"
+require "testable/attribute"
+
+require "testable/extensions/data_setter"
+require "testable/extensions/dom_observer"
 
 require "watir"
-require "selenium-webdriver"
+require "capybara"
+require "webdrivers"
 
 module Testable
   def self.included(caller)
-    caller.extend Testable::Element
-    caller.extend Testable::Interface::Page::Attribute
+    caller.extend Testable::Pages::Attribute
+    caller.extend Testable::Pages::Element
     caller.__send__ :include, Testable::Ready
-    caller.__send__ :include, Testable::DataSetter
-    caller.__send__ :include, Testable::Interface::Page
+    caller.__send__ :include, Testable::Pages
     caller.__send__ :include, Testable::Element::Locator
+    caller.__send__ :include, Testable::DataSetter
   end
 
   def initialize(browser = nil, &block)
     @browser = Testable.browser unless Testable.browser.nil?
     @browser = browser if Testable.browser.nil?
+    begin_with if respond_to?(:begin_with)
     instance_eval(&block) if block
   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
+  # valid browser instance. This is an instance-level access to whatever
+  # browser Testable is using.
   attr_accessor :browser
 
   class << self
+    def watir_api
+      browser.methods - Object.public_methods -
+        Watir::Container.instance_methods
+    end
+
+    def selenium_api
+      browser.driver.methods - Object.public_methods
+    end
+
+    # This accessor is needed so that Testable itself can provide a browser
+    # reference to indicate connection to WebDriver. This is a class-level
+    # access to the browser.
     attr_accessor :browser
 
     def set_browser(app = :chrome, *args)
@@ -36,8 +57,14 @@ module Testable
       Testable.browser = @browser
     end
 
+    alias start_browser set_browser
+
     def quit_browser
       @browser.quit
     end
+
+    def api
+      methods - Object.public_methods
+    end
   end
 end

data/testable.gemspec

@@ -1,7 +1,6 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'testable/version'
+require "testable/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "testable"
@@ -9,25 +8,34 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Jeff Nyman"]
   spec.email         = ["jeffnyman@gmail.com"]
 
-  spec.summary       = %q{Provides a semantic DSL to construct fluent interfaces for test execution logic.}
+  spec.summary       = %q{Web and API Automation, using Capybara and 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"
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/jeffnyman/testable"
+  spec.metadata["changelog_uri"] = "https://github.com/jeffnyman/testable/blob/master/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 10.0"
   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.0"
+  spec.add_runtime_dependency "watir", ["~> 6.4"]
+  spec.add_runtime_dependency "capybara", ["~> 3.0"]
+  spec.add_runtime_dependency "webdrivers", ["~> 4.0"]
 
   spec.post_install_message = %{
 (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)