tapestry 0.1.0 → 0.2.0

data/lib/tapestry/errors.rb

@@ -0,0 +1,16 @@
+module Tapestry
+  module Errors
+    NoUrlForDefinition = Class.new(StandardError)
+    NoUrlMatchForDefinition = Class.new(StandardError)
+    NoTitleForDefinition = Class.new(StandardError)
+    NoUrlMatchPossible = Class.new(StandardError)
+    PageNotValidatedError = Class.new(StandardError)
+    NoBlockForWhenReady = Class.new(StandardError)
+
+    class PageURLFromFactoryNotVerified < StandardError
+      def message
+        'The page URL was not verified during a factory setup.'
+      end
+    end
+  end
+end

data/lib/tapestry/extensions/data_setter.rb

@@ -0,0 +1,106 @@
+class Object
+  # This method is necessary to dynamically chain method calls. The reason
+  # this is necessary the data setter initially has no idea of the actual
+  # object it's going to be dealing with, particularly because part of its
+  # job is to find that object and map a data string to it. Not only this,
+  # but that element will have been called on a specific instance of a
+  # interface class. With the example provide in the comments below for the
+  # `using` method, the following would be the case:
+  #
+  # method_chain: warp_factor.set
+  # o (object):   <WarpTravel:0x007f8b23224218>
+  # m (method):   warp_factor
+  # data:         1
+  #
+  # Thus what you end up with is:
+  #
+  #    <WarpTravel:0x007f8b23224218>.warp_factor.set 1
+  def chain(method_chain, data = nil)
+    return self if method_chain.empty?
+    method_chain.split('.').inject(self) do |o, m|
+      if data.nil?
+        o.send(m.intern)
+      else
+        o.send(m.intern, data)
+      end
+    end
+  end
+end
+
+module Tapestry
+  module DataSetter
+    # The `using` method tells Tapestry to match up whatever data is passed
+    # in via the action with element definitions. If those elements are found,
+    # they will be populated with the specified data. Consider the following:
+    #
+    #    class WarpTravel
+    #      include Tapestry
+    #
+    #      text_field :warp_factor, id: 'warpInput'
+    #      text_field :velocity,    id: 'velocityInput'
+    #      text_field :distance,    id: 'distInput'
+    #    end
+    #
+    # Assuming an instance of this class called `page`, you could do the
+    # following:
+    #
+    #    page.using_data(warp_factor: 1, velocity: 1, distance: 4.3)
+    #
+    # This is based on conventions. The idea is that element definitions are
+    # written in the form of "snake case" -- meaning, underscores between
+    # each separate word. In the above example, "warp_factor: 1" would be
+    # matched to the `warp_factor` element and the value used for that
+    # element would be "1". The default operation for a text field is to
+    # enter the value in. It is also possible to use strings:
+    #
+    #    page.using_data("warp factor": 1, velocity: 1, distance: 4.3)
+    #
+    # Here "warp factor" would be converted to "warp_factor".
+    def using(data)
+      data.each do |key, value|
+        use_data_with(key, value) if object_enabled_for(key)
+      end
+    end
+
+    alias using_data   using
+    alias use_data     using
+    alias using_values using
+    alias use_values   using
+
+    private
+
+    # This is the method that is delegated to in order to make sure that
+    # elements are interacted with appropriately. This will in turn delegate
+    # to `set_and_select` and `check_and_uncheck`, which determines what
+    # actions are viable based on the type of element that is being dealt
+    # with. These aspects are what tie this particular implementation to
+    # Watir.
+    def use_data_with(key, value)
+      element = send(key.to_s.tr(' ', '_'))
+      set_and_select(key, element, value)
+      check_and_uncheck(key, element, value)
+    end
+
+    def set_and_select(key, element, value)
+      key = key.to_s.tr(' ', '_')
+      chain("#{key}.set", value)    if element.class == Watir::TextField
+      chain("#{key}.set")           if element.class == Watir::Radio
+      chain("#{key}.select", value) if element.class == Watir::Select
+    end
+
+    def check_and_uncheck(key, element, value)
+      key = key.to_s.tr(' ', '_')
+      return chain("#{key}.check") if element.class == Watir::CheckBox && value
+      chain("#{key}.uncheck")      if element.class == Watir::CheckBox
+    end
+
+    # This is a sanity check method to make sure that whatever element is
+    # being used as part of the data setting, it exists in the DOM, is
+    # 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.enabled? && web_element.visible?
+    end
+  end
+end

data/lib/tapestry/extensions/dom_observer.js

@@ -0,0 +1,78 @@
+/*
+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 Tapestry 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();
+        callback(true);
+    }, 1000);
+};
+
+var startedUpdating = function() {
+    clearTimeout(notStartedUpdating);
+    observer.disconnect();
+    callback(false);
+};
+
+/*
+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 Tapestry 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);
+
+var notStartedUpdating = notStartedUpdating();

data/lib/tapestry/extensions/dom_observer.rb

@@ -0,0 +1,74 @@
+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)
+      driver.manage.timeouts.script_timeout = delay + 1
+      driver.execute_async_script(DOM_OBSERVER, wd, delay)
+    rescue Selenium::WebDriver::Error::StaleElementReferenceError
+      # This situation can occur when the DOM changes between two calls to
+      # some element or aspect of the page. In this case, we are expecting
+      # the DOM to be different so what's being handled here are those hard
+      # to anticipate race conditions when "weird things happen" and DOM
+      # updating plus script execution get interleaved.
+      retry
+    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
+
+    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/tapestry/extensions/watir_elements.rb

@@ -0,0 +1,16 @@
+module Watir
+  class CheckBox
+    alias check     set
+    alias uncheck   clear
+    alias checked?  set?
+  end
+
+  class Radio
+    alias choose  set
+    alias chosen? set?
+  end
+
+  class TextField
+    alias enter set
+  end
+end

data/lib/tapestry/factory.rb

@@ -0,0 +1,92 @@
+module Tapestry
+  module Factory
+    # Creates a definition context for actions and establishes the context
+    # for execution. Given an interface definition for a page like this:
+    #
+    #    class TestPage
+    #      include Tapestry
+    #
+    #      url_is "http://localhost:9292"
+    #    end
+    #
+    # You can do the following:
+    #
+    #    on_view(TestPage)
+    #
+    # Note that the actual factory creation is handled by `on`. This method
+    # exists as a way to differentiate when an interface needs to be
+    # visited.
+    def on_view(definition, &block)
+      on(definition, true, &block)
+    end
+
+    alias on_visit on_view
+
+    # Creates a definition context for actions. If an existing context
+    # exists, that context will be re-used. You can use this simply to keep
+    # the context for a script clear. For example, say you have the following
+    # interface definitions for pages:
+    #
+    #    class Home
+    #      include Tapestry
+    #      url_is "http://localhost:9292"
+    #    end
+    #
+    #    class Navigation
+    #      include Tapestry
+    #    end
+    #
+    # You could then do this:
+    #
+    #    on_view(Home)
+    #    on(Navigation)
+    #
+    # The Home definition needs the url_is attribute in order for the on_view
+    # factory to work. But Navigation does not because the `on` method is not
+    # attempting to visit, simply to reference. Note that you can use `on`
+    # to visit, just by doing this:
+    #
+    #    on(Home, true)
+    def on(definition, visit = false, &block)
+      unless @context.is_a?(definition)
+        @context = definition.new(@browser) if @browser
+        @context = definition.new unless @browser
+        @context.visit if visit
+      end
+
+      verify_page(@context)
+
+      yield @context if block
+      @context
+    end
+
+    # Creates a definition context for actions. Unlike the `on` factory, the
+    # `on_new` factory will always create a new context and will never re-use
+    # an existing one. The reason for using this factory might be that you
+    # are on the same page, but a given action has changed it so much that
+    # you want to reference it as a new version of that page, meaning a new
+    # context is established.
+    #
+    # It's doubtful that you will want to rely on this factory too much.
+    def on_new(definition, &block)
+      @context = nil
+      on(definition, &block)
+    end
+
+    alias on_page  on
+    alias while_on on
+
+    private
+
+    # This method is used to provide a means for checking if a page has been
+    # navigated to correctly as part of a context. This is useful because
+    # the context signature should remain highly readable, and checks for
+    # whether a given page has been reached would make the context definition
+    # look sloppy.
+    def verify_page(context)
+      return if context.url_match_attribute.nil?
+      return if context.has_correct_url?
+      raise Tapestry::Errors::PageURLFromFactoryNotVerified
+    end
+  end
+end

data/lib/tapestry/interface.rb

@@ -0,0 +1,203 @@
+require "tapestry/situation"
+
+module Tapestry
+  module Interface
+    module Page
+      include Situation
+
+      # 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)
+        no_url_provided if url.nil? && url_attribute.nil?
+        @browser.goto(url) unless url.nil?
+        @browser.goto(url_attribute) if url.nil?
+        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, if any.
+      def url_attribute
+        self.class.url_attribute
+      end
+
+      # 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 `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, if any.
+      def title_attribute
+        self.class.title_attribute
+      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?
+        if url_attribute.nil? && url_match_attribute.nil?
+          no_url_match_is_possible
+        end
+        !(url =~ url_match_attribute).nil?
+      end
+
+      alias displayed? has_correct_url?
+
+      # 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 `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 `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 `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 sends a standard "browser refresh" message to the browser.
+      def refresh
+        browser.refresh
+      end
+
+      alias refresh_page refresh
+
+      # 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
+
+      alias resize_to resize
+
+      # 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, y)
+        browser.window.move_to(x, y)
+      end
+
+      # 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('Tapestry 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 `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.save.screenshot(file)
+      end
+
+      alias save_screenshot screenshot
+
+      # 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
+
+      # 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
+    end
+  end
+end