testable 0.3.0 → 0.8.0

data/lib/testable/extensions/dom_observer.js

@@ -1,8 +1,35 @@
-// WebDriver arguments
-var element = arguments[0];
-var delay = arguments[1] * 1000;
+/*
+This functionality will only work for browsers that support it.
+See: http://caniuse.com/#feat=mutationobserver
+*/
+
+// WebDriver arguments, which are passed to the MutationObserver.
+var element  = arguments[0];
+var delay    = arguments[1] * 1000;
 var callback = arguments[2];
 
+/*
+The two functions below are similar in what they are doing. Both are
+disconneting the observer. Both are also invoking WebDriver's callback
+function.
+
+notStartedUpdating passes true to the callback, which indicates that the
+DOM has not yet begun updating.
+
+startedUpdating passes false to the callback, which indicates that the
+DOM has begun updating.
+
+The disconnect is important. You only want to be listening (observing) for the
+period required, removing the listeners when done. Since there be many DOM
+operations, you want to disconnet when there is interaction with the page by
+the automated scripts.
+
+When observing a node for changes, the callback will not be fired until the
+DOM has finished changing. That is the only granularity that is required for
+the Cogent implementation. What specific events occurred is not important
+because the goal is not to conditionally respond to them; rather just to know
+when the process has completed.
+*/
 var notStartedUpdating = function() {
     return setTimeout(function() {
         observer.disconnect();
@@ -16,7 +43,34 @@ var startedUpdating = function() {
     callback(false);
 };
 
-// Observer
+/*
+Mutation Observer
+The W3C DOM4 specification initially introduced mutation observers as a
+replacement for the deprecated mutation events.
+
+The MutationObserver is a JavaScript native object that allows for observing
+a change on any node-like DOM Element. "Mutation" means the addition or the
+removal of a node as well as changes to the node's attribute and data.
+
+The general approach is to create a MutationObserver object with a defined
+callback function. The function will execute on every mutation observed by
+the MutationObserver. The MutationObserver must be bound to a target, which
+for Cogent would mean the element whose context it is being called upon.
+
+A MutationObserver can be provided with a set of options, which indicate
+what kind of events should be observed.
+
+The childList option checks for additions and removals of the target node's
+child elements, including text nodes. This is basically looking for any
+nodes added or removed from documentElement.
+
+The subtree option checks for mutations to the target as well the target's
+descendants. So that means every child node of documentElement.
+
+The attribute option checks for mutations to the target's attributes.
+
+The characterData option checks for mutations to the target's data.
+*/
 var observer = new MutationObserver(startedUpdating);
 var config = { attributes: true, childList: true, characterData: true, subtree: true };
 observer.observe(element, config);

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/logger.rb

@@ -0,0 +1,16 @@
+require "logger"
+
+module Testable
+  class Logger
+    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
+    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)