gamera 0.1.0

data/lib/gamera/exceptions.rb

@@ -0,0 +1,32 @@
+# encoding:utf-8
+#--
+# The MIT License (MIT)
+#
+# Copyright (c) 2015, The Gamera Development Team. See the COPYRIGHT file at
+# the top-level directory of this distribution and at
+# http://github.com/gamera-team/gamera/COPYRIGHT.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#++
+
+module Gamera
+  class NoUrlMatcherForPage < StandardError; end
+  class DatabaseNotConfigured < StandardError; end
+  class WrongPageVisited < StandardError; end
+end

data/lib/gamera/general_proxy.rb

@@ -0,0 +1,83 @@
+# encoding:utf-8
+#--
+# The MIT License (MIT)
+#
+# Copyright (c) 2015, The Gamera Development Team. See the COPYRIGHT file at
+# the top-level directory of this distribution and at
+# http://github.com/gamera-team/gamera/COPYRIGHT.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#++
+
+module Gamera
+  # This implements a specific sub-pattern of the proxy pattern. Rather than
+  # knowing about a specific class's methods, it will add a singleton method to
+  # a given object for each method defined by that method's class or the
+  # method's class and up through a specified class in the ancestor chain.
+  #
+  # Important Note: This module must be *prepended* rather than *included* for
+  # +self+ to refer to the class containing the module. If the proxying isn't
+  # happening, this is likely the problem.
+  #
+  # Usage example:
+  # if you are testing a class +Foo+ with Capybara and you'd like to take a
+  # screenshot everytime a method in that class is called
+  #   class Foo
+  #     prepend Gamera::GeneralProxy
+  #
+  #     def my_method
+  #       # do something interesting in a browser
+  #     end
+  #
+  #     def my_other_method
+  #       # do something else interesting in a browser
+  #     end
+  #   end
+  #
+  # In the spec file
+  #
+  #   describe Foo do
+  #     let(:foo) { Foo.new }
+  #     it "does something"
+  #     foo.start_proxying(->(*args)
+  #       {Capybara::Screenshot.screenshot_and_save_page
+  #         super(*args)})
+  #     foo.my_method # => screenshot taken & method called
+  #     foo.my_other_method # => screenshot taken & method called
+  #     foo.stop_proxying
+  #     foo.my_method # => *crickets* (aka method called)
+  #     foo.my_other_method # => *crickets*
+  #     ...
+  module GeneralProxy
+    def start_proxying(a_lambda = ->(*args) { super(*args) }, top_class = self.class)
+      @top_class = top_class
+      ancestors = self.class.ancestors
+      proxy_target_classes = ancestors[1..ancestors.index(top_class)]
+      proxy_target_classes.each do |klass|
+        klass.instance_methods(false).each do |method|
+          define_singleton_method(method, a_lambda)
+        end
+      end
+    end
+
+    def stop_proxying
+      start_proxying(-> (*args) { super(*args) }, @top_class)
+    end
+  end
+end

data/lib/gamera/page.rb

@@ -0,0 +1,203 @@
+# encoding:utf-8
+#--
+# The MIT License (MIT)
+#
+# Copyright (c) 2015, The Gamera Development Team. See the COPYRIGHT file at
+# the top-level directory of this distribution and at
+# http://github.com/gamera-team/gamera/COPYRIGHT.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#++
+
+require 'capybara'
+require_relative 'exceptions'
+
+module Gamera
+  # This is a base class which implements common methods for page object
+  # classes.
+  #
+  # You can use this to create a Ruby class which wraps a web page, providing
+  # an API for automating elements or processes on the page
+  #
+  # @example Page Object class for registration page
+  #   class NewRegistrationPage < Gamera::Page
+  #     def initialize
+  #       @url = 'http://example.com/registration/new'
+  #       @url_matcher = /registration\/new/
+  #     end
+  #
+  #     # page elements
+  #     def name_field
+  #       find_field('Name')
+  #     end
+  #
+  #     def email_field
+  #       find_field('Email Address')
+  #     end
+  #
+  #     def password_field
+  #       find_field('Password')
+  #     end
+  #
+  #     def password_confirmation_field
+  #       find_field('Confirm Password')
+  #     end
+  #
+  #     def instructions
+  #     def instructions
+  #       find('#instructions')
+  #     end
+  #
+  #     # page processes
+  #     def save
+  #       find_button('Save').click
+  #     end
+  #
+  #     def register_user(name:, email:, password:)
+  #       name_field.set(name)
+  #       email_field.set(email)
+  #       password_field.set(password)
+  #       password_confirmation_field.set(password)
+  #       save
+  #     end
+  #   end
+  #
+  #   # This could be used in a test or automation script, e.g.
+  #   ...
+  #   reg_page = NewRegistrationPage.new
+  #   reg_page.visit
+  #   reg_page.register_user(name: 'Laurence Peltier',
+  #                          email: 'lpeltier@example.com',
+  #                          password: 'super_secret')
+  #   ...
+  #
+  # @example Page class for general Rails page with flash messages
+  #   class RailsPage < Gamera::Page
+  #     def flash_error_css
+  #       'div.flash.error'
+  #     end
+  #
+  #     def flash_notice_css
+  #       'div.flash.notice'
+  #     end
+  #
+  #     def flash_error
+  #       find(flash_error_css)
+  #     end
+  #
+  #     def flash_notice
+  #       find(flash_notice_css)
+  #     end
+  #
+  #     def has_flash_message?(message)
+  #       has_css?(flash_notice_css, text: message)
+  #     end
+  #
+  #     def has_flash_error?(error)
+  #       has_css?(flash_error_css, text: error)
+  #     end
+  #
+  #     def has_no_flash_error?
+  #       has_no_css?(flash_error_css)
+  #     end
+  #
+  #     def has_no_flash_message?
+  #       has_no_css?(flash_notice_css)
+  #     end
+  #
+  #     def has_submission_problems?
+  #       has_flash_error?('There were problems with your submission')
+  #     end
+  #
+  #     def fail_if_submission_problems
+  #       fail(SubmissionProblemsError, flash_error.text) if has_submission_problems?
+  #     end
+  #   end
+  class Page
+    include Capybara::DSL
+
+    attr_reader :url, :url_matcher
+
+    def initialize(url, url_matcher = nil)
+      @url = url
+      @url_matcher = url_matcher
+    end
+
+    # Open the page url in the browser specified in your Capybara configuration
+    #
+    # @raise [WrongPageVisited] if the site redirects to URL that doesn't match
+    #   the url_matcher regex
+    def visit
+      super(url)
+      fail WrongPageVisited, "Expected URL '#{url}', got '#{page.current_url}'" unless displayed?
+    end
+
+    # Check to see if we eventually land on the right page
+    #
+    # @param wait_time_seconds [Integer] How long to wait for the correct page to load
+    # @return [Boolean] true if the url loaded in the browser matches the url_matcher pattern
+    # @raise [NoUrlMatcherForPage] if there's no url_matcher for this page
+    def displayed?(wait_time_seconds = Capybara.default_wait_time)
+      fail Gamera::NoUrlMatcherForPage if url_matcher.nil?
+      start_time = Time.now
+      loop do
+        return true if page.current_url.chomp('/') =~ url_matcher
+        break unless Time.now - start_time <= wait_time_seconds
+        sleep(0.05)
+      end
+      false
+    end
+
+    # A method to wait for slow loading data on a page. Useful, for example,
+    # when waiting on a page that shows the count of records loaded via a slow
+    # web or import.
+    #
+    # @param retries [Integer] Number of times to reload the page before giving up
+    # @param allowed_errors [Array] Array of errors that trigger a refresh, e.g.,  if an ExpectationNotMetError was raised during an acceptance test
+    # @param block [Block] The block to execute after each refresh
+    def with_refreshes(retries, allowed_errors = [RSpec::Expectations::ExpectationNotMetError], &block)
+      retries_left ||= retries
+      visit
+      block.call(retries_left)
+    rescue *allowed_errors => e
+      retries_left -= 1
+      retry if retries_left >= 0
+      raise e
+    end
+
+    # This is a flag for tracking which page object classes don't cover all of
+    # the elements and/or controls on the target web page.
+    #
+    # @return [Boolean] true unless everything's been captured in the page
+    #   object class
+    def sparse?
+      false
+    end
+
+    # This is a utility method to clean up URLs formed by concatenation since we
+    # sometimes ended up with "//" in the middle of URLs which broke the
+    # url_matcher checks.
+    #
+    # @param elements [String] duck types
+    # @return [String] of elements joined by single "/" characters.
+    def path_join(*elements)
+      "/#{elements.join('/')}".gsub(%r(//+}), '/')
+    end
+  end
+end

data/lib/gamera/page_sections/form.rb

@@ -0,0 +1,150 @@
+# encoding:utf-8
+#--
+# The MIT License (MIT)
+#
+# Copyright (c) 2015, The Gamera Development Team. See the COPYRIGHT file at
+# the top-level directory of this distribution and at
+# http://github.com/gamera-team/gamera/COPYRIGHT.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#++
+
+require 'capybara'
+
+module Gamera
+  module PageSections
+    # This class represents an html form on a web page. For example, if you had
+    # a page like
+    #
+    #   <html>
+    #   <body>
+    #     <h2>Example form</h2>
+    #     <form action='/user/register'>
+    #       <label for="name">Name</label><input type="text" name="name" value="" id="name">
+    #       <label for="email">Email</label><input type="text" name="email" value="" id="email">
+    #       <label for="password">Password</label><input type="text" name="password" value="" id="password">
+    #
+    #       <input type="button" name="Register" id="save_button">
+    #       <input type="button" name="Cancel" id="cancel_button">
+    #     </form>
+    #   </body>
+    #   </html>
+    #
+    # you could include this in a page object class like so:
+    #
+    #   class RegistrationPage < Gamera::Page
+    #     include Forwardable
+    #
+    #     attr_reader :registration_form, :table
+    #
+    #     def initialize
+    #       super(path_join(BASE_URL, '/registration/new'), %r{registration/new$})
+    #
+    #       form_fields = {
+    #         name: 'Name',
+    #         email: 'Email',
+    #         password: 'Password'
+    #       }
+    #
+    #       @registration_form = Gamera::PageSections::Form.new(form_fields)
+    #       def_delegators :registration_form, *registration_form.field_method_names
+    #     end
+    #
+    #     def register
+    #       find_button('Register').click
+    #     end
+    #
+    #     def cancel
+    #       find_button('Cancel').click
+    #     end
+    #   end
+    #
+    class Form
+      include Capybara::DSL
+
+      attr_accessor :fields, :field_method_names
+
+      def initialize(fields)
+        @fields = fields
+        @field_method_names = []
+        define_field_methods
+      end
+
+      # Utility method to populate the form based on a hash of field names and
+      # values
+      #
+      # @param fields [Hash] The keys are the [field_name]s and the values are the values to which the fields are to be set.
+      def fill_in_form(fields)
+        fields.each do |field, value|
+          f = send("#{field}_field")
+          f.set(value.to_s) || Array(value).each { |val| f.select(val) }
+        end
+      end
+
+      private
+
+      # Creates methods for the specified form fields of the form "<field_name>_field"
+      # (based on the results of [define_field_name]) that can be called to
+      # interact with form controls on the web page
+      def define_field_methods
+        if fields.is_a?(Array)
+          fields.each do |field_label|
+            field = field_label.downcase.gsub(' ', '_').gsub(/\W/, '').to_sym
+            field_method_name = define_field_name(field)
+            define_field_method(field_method_name, field_label)
+          end
+        elsif fields.is_a?(Hash)
+          fields.each do |field, field_string|
+            field_method_name = define_field_name(field)
+            define_field_method(field_method_name, field_string)
+          end
+        end
+      end
+
+      # converts the provided field string into a suitable method name for
+      # [define_field_methods] to use
+      #
+      # @param field [String] The user-readable name of a control on an html form
+      def define_field_name(field)
+        (field.to_s + '_field').to_sym.tap do |field_method_name|
+          field_method_names << field_method_name
+        end
+      end
+
+      # Defines an instance method named <field_method_name> for a given field
+      #
+      # @param field_method_name [String] Ruby-syntax-friendly name for the method being defined
+      # @param field_string [String] The user-readable name or selector for the html form control
+      def define_field_method(field_method_name, field_string)
+        field_string = field_string.chomp(':')
+        self.class.send(:define_method, field_method_name) do
+          label_before_field_xpath = "//label[contains(., '#{field_string}')]/following-sibling::*[local-name() = 'input' or local-name() = 'textarea' or local-name() = 'select'][1]"
+          label_after_field_xpath = "//label[contains(., '#{field_string}')]/preceding-sibling::*[local-name() = 'input' or local-name() = 'textarea' or local-name() = 'select'][1]"
+          if has_selector?(:field, field_string)
+            find_field(field_string)
+          elsif has_xpath?(label_before_field_xpath)
+            find(:xpath, label_before_field_xpath)
+          else
+            find(:xpath, label_after_field_xpath)
+          end
+        end
+      end
+    end
+  end
+end