browsery 0.1.0 → 0.2.0

data/lib/browsery/test_case.rb

@@ -0,0 +1,266 @@
+module Browsery
+
+  # An Browsery-specific test case container, which extends the default ones,
+  # adds convenience helper methods, and manages page objects automatically.
+  class TestCase < Minitest::Test
+    @@selected_methods = []
+    @@runnables_count = 0
+    @@regression_suite = Array.new
+    @@serials = Array.new
+    @@test_suite_data = if File.exist?(Browsery.root.join("config/browsery/test_suite.yml"))
+                          YAML.load_file(Browsery.root.join("config/browsery/test_suite.yml"))
+                        else
+                          default = {"regression"=>{"tag_to_exclude"=>:non_regression}}
+                          if Browsery.root != Browsery.gem_root
+                            # Only necessary to notify gem user, not gem developer
+                            puts "config/browsery/test_suite.yml doesn't exist, using default:\n#{default}"
+                            puts "It's recommended to have this config file as it'll avoid problem when using tapout"
+                          end
+                          default
+                        end
+
+    # Standard exception class that signals that the test with that name has
+    # already been defined.
+    class TestAlreadyDefined < ::StandardError; end
+
+    # Include helper modules
+    include Browsery::Utils::AssertionHelper
+    include Browsery::Utils::DataGeneratorHelper
+    include Browsery::Utils::Loggable
+    include Browsery::Utils::PageObjectHelper
+
+    class <<self
+
+      # @!attribute [rw] options
+      #   @return [Hash] test case options
+      attr_accessor :options
+
+      # Explicitly remove _all_ tests from the current class. This will also
+      # remove inherited test cases.
+      #
+      # @return [TestCase] self
+      def remove_tests
+        klass = class <<self; self; end
+        public_instance_methods.grep(/^test_/).each do |method|
+          klass.send(:undef_method, method.to_sym)
+        end
+        self
+      end
+
+      # Call this at the top of your test case class in order to run all tests
+      # in alphabetical order
+      #
+      # @return [TestCase] self
+      # @example
+      #   class SomeName < TestCase
+      #     run_in_order!
+      #
+      #     test :feature_search_01 { ... }
+      #     test :feature_search_02 { ... }
+      #   end
+      def run_in_order!
+        # `self` is the class, so we want to reopen the metaclass instead, and
+        # redefine the methods there
+        class <<self
+          undef_method :test_order if method_defined? :test_order
+          define_method :test_order do
+            :alpha
+          end
+        end
+
+        # Be nice and return the class back
+        self
+      end
+
+      # Filter out anything not matching our tag selection, if any.
+      #
+      # If it's parallel run,
+      # only add filtered methods from each runnable to a list of to run methods,
+      # instead of running them one by one right away,
+      # and finally when all runnable methods are traversed, call parallel to run that list of methods.
+      #
+      # @return [Enumerable<Symbol>] the methods marked runnable
+      def runnable_methods
+        methods  = super
+        selected = Browsery.settings.tags
+
+        filtered_methods = filter_methods(methods, selected)
+
+        if Browsery.settings.parallel
+          unless filtered_methods.empty?
+            if selected.nil? || selected.empty?
+              @@selected_methods = @@regression_suite
+            else
+              methods_to_add = filtered_methods.map { |method| method.to_sym if @@regression_suite.include?(method.to_sym) }
+              @@selected_methods += methods_to_add
+            end
+          end
+
+          @@runnables_count += 1
+          browsery_runnables = Minitest::Runnable.runnables - [Minitest::Test, Minitest::Unit::TestCase]
+
+          if @@runnables_count == browsery_runnables.size
+            parallel = Parallel.new(Browsery.settings.parallel, @@selected_methods)
+            parallel.clean_result!
+            parallel.run_in_parallel!
+            parallel.remove_redundant_tap if Browsery.settings.rerun_failure
+            parallel.aggregate_tap_results
+            exit
+          end
+
+          return [] # no test will run
+        else
+          filtered_methods
+        end
+      end
+
+      # Filter methods in a runnable based on our tag selection
+      def filter_methods(methods, selected)
+        # If no tags are selected, run all tests
+        if selected.nil? || selected.empty?
+          return methods
+        end
+
+        selected_methods = methods.select do |method|
+          # If the method's tags match any of the tag sets, allow it to run
+          selected.any? do |tag_set|
+            # Retrieve the tags for that method
+            method_options = self.options[method.to_sym] rescue nil
+            tags           = method_options[:tags]       rescue nil
+
+            # If the method's tags match ALL of the tags in the tag set, allow
+            # it to run; in the event of a problem, allow the test to run
+            tag_set.all? do |tag|
+              if tag =~ %r/^!/
+                !tags.include?(tag[%r/^!(.*)/,1].to_sym) || nil
+              else
+                tags.include?(tag.to_sym) || nil
+              end rescue true
+            end
+          end
+        end
+
+        selected_methods
+      end
+
+      # Install a setup method that runs before every test.
+      #
+      # @return [void]
+      def setup(&block)
+        define_method(:setup) do
+          super()
+          instance_eval(&block)
+        end
+      end
+
+      # Install a teardown method that runs after every test.
+      #
+      # @return [void]
+      def teardown(&block)
+        define_method(:teardown) do
+          super()
+          instance_eval(&block)
+        end
+      end
+
+      # Defines a test case.
+      #
+      # It can take the following options:
+      #
+      # * `tags`: An array of any number of tags associated with the test case.
+      #          When not specified, the test will always be run even when only
+      #          certain tags are run. When specified but an empty array, the
+      #          test will only be run if all tags are set to run. When the array
+      #          contains one or more tags, then the test will only be run if at
+      #          least one tag matches.
+      # * `serial`: An arbitrary string that is used to refer to all a specific
+      #            test case. For example, this can be used to store the serial
+      #            number for the test case.
+      #
+      # @param name [String, Symbol] an arbitrary but unique name for the test,
+      #   preferably unique across all test classes, but not required
+      # @param opts [Hash]
+      # @param block [Proc] the testing logic
+      # @return [void]
+      def test(name, **opts, &block)
+        # Ensure that the test isn't already defined to prevent tests from being
+        # swallowed silently
+        method_name = test_name(name)
+        check_not_defined!(method_name)
+
+        # Add an additional tag, which is unique for each test class, to all tests
+        # To allow user to run tests with option '-t class_name_of_the_test' without
+        # duplicate run for all tests in NameOfTheTest. The namespace of the class
+        # is ignored here.
+        opts[:tags] << ('class_'+ self.name.demodulize.underscore).to_sym
+
+        # Flunk unless a logic block was provided
+        if block_given?
+          self.options ||= {}
+          self.options[method_name.to_sym] = opts.deep_symbolize_keys
+          define_method(method_name, &block)
+        else
+          flunk "No implementation was provided for test '#{method_name}' in #{self}"
+        end
+
+        # add all tests to @@regression_suite
+        # excluding the ones with tags in tags_to_exclude defined in config
+        unless exclude_by_tag?('regression', opts[:tags])
+          @@regression_suite << method_name
+          @@serials << opts[:serial]
+        end
+      end
+
+      # @param suite [String] type of test suite
+      # @param tags [Array] an array of tags a test has
+      # @return [Boolean]
+      def exclude_by_tag?(suite, tags)
+        tag_to_exclude = @@test_suite_data[suite]['tag_to_exclude']
+        if tags.include? tag_to_exclude
+          true
+        else
+          false
+        end
+      end
+
+      # Check that +method_name+ hasn't already been defined as an instance
+      # method in the current class, or in any superclasses.
+      #
+      # @param method_name [Symbol] the method name to check
+      # @return [void]
+      protected
+      def check_not_defined!(method_name)
+        already_defined = instance_method(method_name) rescue false
+        raise TestAlreadyDefined, "Test #{method_name} already exists in #{self}" if already_defined
+      end
+
+      # Transform the test +name+ into a snake-case name, prefixed with "test_".
+      #
+      # @param name [#to_s] the test name
+      # @return [Symbol] the transformed test name symbol
+      # @example
+      #   test_name(:search_zip) # => :test_search_zip
+      private
+      def test_name(name)
+        undercased_name = sanitize_name(name).gsub(/\s+/, '_')
+        "test_#{undercased_name}".to_sym
+      end
+
+      # Sanitize the +name+ by removing consecutive non-word characters into a
+      # single whitespace.
+      #
+      # @param name [#to_s] the name to sanitize
+      # @return [String] the sanitized value
+      # @example
+      #   sanitize_name('The Best  Thing [#5]') # => 'The Best Thing 5'
+      #   sanitize_name(:ReallySuper___awesome) # => 'ReallySuper Awesome'
+      private
+      def sanitize_name(name)
+        name.to_s.gsub(/\W+/, ' ').strip
+      end
+
+    end
+
+  end
+
+end

data/lib/browsery/test_cases.rb

@@ -0,0 +1,7 @@
+module Browsery
+
+  # An empty container for actual test cases and test classes.
+  module TestCases
+  end
+
+end

data/lib/browsery/utils.rb

@@ -0,0 +1,10 @@
+module Browsery
+  module Utils; end
+end
+
+require_relative 'utils/assertion_helper'
+require_relative 'utils/castable'
+require_relative 'utils/data_generator_helper'
+require_relative 'utils/loggable'
+require_relative 'utils/page_object_helper'
+require_relative 'utils/overlay_and_widget_helper'

data/lib/browsery/utils/assertion_helper.rb

@@ -0,0 +1,35 @@
+require 'minitest/assertions'
+
+module Browsery
+  module Utils
+
+    # A collection of custom, but frequently-used assertions.
+    module AssertionHelper
+
+      # Assert that an element, specified by `how` and `what`, are absent from
+      # the current page's context.
+      #
+      # @param how [:class, :class_name, :css, :id, :link_text, :link,
+      #   :partial_link_text, :name, :tag_name, :xpath]
+      # @param what [String, Symbol]
+      def assert_element_absent(how, what)
+        assert_raises Selenium::WebDriver::Error::NoSuchElementError do
+          @driver.find_element(how, what)
+        end
+      end
+
+      # Assert that an element, specified by `how` and `what`, are present from
+      # the current page's context.
+      #
+      # @param how [:class, :class_name, :css, :id, :link_text, :link,
+      #   :partial_link_text, :name, :tag_name, :xpath]
+      # @param what [String, Symbol]
+      def assert_element_present(how, what)
+        @driver.find_element(how, what)
+      end
+
+    end
+
+  end
+end
+

data/lib/browsery/utils/castable.rb

@@ -0,0 +1,103 @@
+
+module Browsery
+  module Utils
+
+    module Castable
+
+      module ClassMethods
+
+        # Attempts to create a new page object from a driver state. Use the
+        # instance method for convenience. Raises `NameError` if the page could
+        # not be found.
+        #
+        # @param driver [Selenium::WebDriver] The instance of the current
+        #   WebDriver.
+        # @param name [#to_s] The name of the page object to instantiate.
+        # @return [Base] A subclass of `Base` representing the page object.
+        # @raise InvalidPageState if the page cannot be casted to
+        # @raise NameError if the page object doesn't exist
+        def cast(driver, name)
+          # Transform the name string into a file path and then into a module name
+          klass_name = "browsery/page_objects/#{name}".camelize
+
+          # Attempt to load the class
+          klass = begin
+            klass_name.constantize
+          rescue => exc
+            msg = ""
+            msg << "Cannot find page object '#{name}', "
+            msg << "because could not load class '#{klass_name}' "
+            msg << "with underlying error:\n  #{exc.class}: #{exc.message}\n"
+            msg << exc.backtrace.map { |str| "    #{str}" }.join("\n")
+            raise NameError, msg
+          end
+
+          # Instantiate the class, passing the driver automatically, and
+          # validates to ensure the driver is in the correct state
+          instance = klass.new(driver)
+          begin
+            instance.validate!
+          rescue Minitest::Assertion => exc
+            raise Browsery::PageObjects::InvalidePageState, "#{klass}: #{exc.message}"
+          end
+          instance
+        end
+
+      end
+
+      # Extend the base class in which this module is included in order to
+      # inject class methods.
+      #
+      # @param base [Class]
+      # @return [void]
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # The preferred way to create a new page object from the current page's
+      # driver state. Raises a NameError if the page could not be found. If
+      # casting causes a StaleElementReferenceError, the method will retry up
+      # to 2 more times.
+      #
+      # @param name [String] see {Base.cast}
+      # @return [Base] The casted page object.
+      # @raise InvalidPageState if the page cannot be casted to
+      # @raise NameError if the page object doesn't exist
+      def cast(name)
+        tries ||= 3
+        self.class.cast(@driver, name).tap do |new_page|
+          self.freeze
+          Browsery.logger.debug("Casting #{self.class}(##{self.object_id}) into #{new_page.class}(##{new_page.object_id})")
+        end
+      rescue Selenium::WebDriver::Error::StaleElementReferenceError => sere
+        Browsery.logger.debug("#{self.class}(##{@driver.object_id})->cast(#{name}) raised a potentially-swallowed StaleElementReferenceError")
+        sleep 1
+        retry unless (tries -= 1).zero?
+      end
+
+      # Cast the page to any of the listed `names`, in order of specification.
+      # Returns the first page that accepts the casting, or returns nil, rather
+      # than raising InvalidPageState.
+      #
+      # @param names [Enumerable<String>] see {Base.cast}
+      # @return [Base, nil] the casted page object, if successful; nil otherwise.
+      # @raise NameError if the page object doesn't exist
+      def cast_any(*names)
+        # Try one at a time, swallowing InvalidPageState exceptions
+        names.each do |name|
+          begin
+            return self.cast(name)
+          rescue InvalidPageState
+            # noop
+          end
+        end
+
+        # Return nil otherwise
+        return nil
+      end
+
+    end
+
+  end
+end
+

data/lib/browsery/utils/data_generator_helper.rb

@@ -0,0 +1,145 @@
+
+module Browsery
+  module Utils
+
+    # Useful helpers to generate fake data.
+    module DataGeneratorHelper
+
+      # All valid area codes in the US
+      NPA = ["201", "202", "203", "205", "206", "207", "208", "209", "210", "212", "213", "214", "215", "216", "217", "218", "219", "224", "225", "227", "228", "229", "231", "234", "239", "240", "248", "251", "252", "253", "254", "256", "260", "262", "267", "269", "270", "276", "281", "283", "301", "302", "303", "304", "305", "307", "308", "309", "310", "312", "313", "314", "315", "316", "317", "318", "319", "320", "321", "323", "330", "331", "334", "336", "337", "339", "347", "351", "352", "360", "361", "386", "401", "402", "404", "405", "406", "407", "408", "409", "410", "412", "413", "414", "415", "417", "419", "423", "424", "425", "434", "435", "440", "443", "445", "464", "469", "470", "475", "478", "479", "480", "484", "501", "502", "503", "504", "505", "507", "508", "509", "510", "512", "513", "515", "516", "517", "518", "520", "530", "540", "541", "551", "557", "559", "561", "562", "563", "564", "567", "570", "571", "573", "574", "580", "585", "586", "601", "602", "603", "605", "606", "607", "608", "609", "610", "612", "614", "615", "616", "617", "618", "619", "620", "623", "626", "630", "631", "636", "641", "646", "650", "651", "660", "661", "662", "667", "678", "682", "701", "702", "703", "704", "706", "707", "708", "712", "713", "714", "715", "716", "717", "718", "719", "720", "724", "727", "731", "732", "734", "737", "740", "754", "757", "760", "763", "765", "770", "772", "773", "774", "775", "781", "785", "786", "801", "802", "803", "804", "805", "806", "808", "810", "812", "813", "814", "815", "816", "817", "818", "828", "830", "831", "832", "835", "843", "845", "847", "848", "850", "856", "857", "858", "859", "860", "862", "863", "864", "865", "870", "872", "878", "901", "903", "904", "906", "907", "908", "909", "910", "912", "913", "914", "915", "916", "917", "918", "919", "920", "925", "928", "931", "936", "937", "940", "941", "947", "949", "952", "954", "956", "959", "970", "971", "972", "973", "975", "978", "979", "980", "984", "985", "989"]
+
+      # Easier to assume for now a list of valid exchanges
+      NXX = NPA
+
+      # Generate a string of random digits.
+      #
+      # @param digits [Fixnum] the number of digits in the string
+      # @return [String] the string of digits
+      def generate_digits(digits = 1)
+        Faker::Number.number(digits)
+      end
+
+      # Generate a random email address.
+      #
+      # The specifier portion may be:
+      #
+      # * `nil`, in which case nothing special happens;
+      # * a `String`, in which case the words in the string is shuffled, and
+      #   random separators (`.` or `_`) are inserted between them;
+      # * an `Integer`, in which case a random alpha-string will be created
+      #   with length of at least that many characters;
+      # * a `Range`, in which case a random alpha-string of length within the
+      #   range will be produced.
+      #
+      # @param specifier [nil, String, Integer, Range] a specifier to help
+      #   generate the username part of the email address
+      # @return [String]
+      def generate_email(specifier = nil)
+        Faker::Internet.email(name)
+      end
+
+      # Generate a handsome first name.
+      #
+      # @param length [#to_i, nil]
+      # @return [String]
+      def generate_first_name(length = nil)
+        first_name = ''
+        if length.nil?
+          first_name = Faker::Name.first_name
+        else
+          # Ensure a name with requested length is generated
+          name_length = Faker::Name.first_name.length
+          if length > name_length
+            first_name = Faker::Lorem.characters(length)
+          else
+            first_name = Faker::Name.first_name[0..length.to_i]
+          end
+        end
+        # remove all special characters since name fields on our site have this requirement
+        first_name.gsub!(/[^0-9A-Za-z]/, '')
+        first_name
+      end
+
+      # Generate a gosh-darn awesome last name.
+      #
+      # @param length [#to_i, nil]
+      # @return [String]
+      def generate_last_name(length = nil)
+        last_name = ''
+        if length.nil?
+          last_name = Faker::Name.last_name
+        else
+          # Ensure a name with requested length is generated
+          name_length = Faker::Name.last_name.length
+          if length > name_length
+            last_name = Faker::Lorem.characters(length)
+          else
+            last_name = Faker::Name.last_name[0..length.to_i]
+          end
+        end
+        # remove all special characters since name fields on our site have this requirement
+        last_name.gsub!(/[^0-9A-Za-z]/, '')
+        last_name
+      end
+
+      # Generate a unique random email ends with @test.com
+      def generate_test_email
+        [ "#{generate_last_name}.#{generate_unique_id}", 'test.com' ].join('@')
+      end
+
+      # Generate a random number between 0 and `max - 1` if `max` is >= 1,
+      # or between 0 and 1 otherwise.
+      def generate_number(max = nil)
+        rand(max)
+      end
+
+      # Generates a U.S. phone number (NANPA-aware).
+      #
+      # @param format [Symbol, nil] the format of the phone, one of: nil,
+      #   `:paren`, `:dotted`, or `:dashed`
+      # @return [String] the phone number
+      def generate_phone_number(format = nil)
+        case format
+        when :paren, :parenthesis, :parentheses
+          '(' + NPA.sample + ') ' + NXX.sample + '-' + generate_digits(4)
+        when :dot, :dotted, :dots, :period, :periods
+          [ NPA.sample, NXX.sample, generate_digits(4) ].join('.')
+        when :dash, :dashed, :dashes
+          [ NPA.sample, NXX.sample, generate_digits(4) ].join('-')
+        else
+          NPA.sample + NXX.sample + generate_digits(4)
+        end
+      end
+
+      # Generate a random date.
+      #
+      # @param start_date [Integer] minimum date range
+      # @param end_date [Integer] maximum date range
+      # @return [String] the generated date
+      def generate_date(start_date, end_date)
+        random_date = rand start_date..end_date
+        return random_date.to_formatted_s(:month_day_year)
+      end
+      
+      # Generate a unique id with a random hex string and time stamp string
+      def generate_unique_id
+        SecureRandom.hex(3) + Time.current.to_i.to_s
+      end
+
+      # Generate a random password of a certain length, or default length 12
+      #
+      # @param length [#to_i, nil]
+      # @return [String]
+      def generate_password(length = nil)
+        if length.nil?
+          SecureRandom.hex(6) # result length = 12
+        else
+          chars = (('a'..'z').to_a + ('0'..'9').to_a) - %w(i o 0 1 l 0)
+          (1..length).collect{|a| chars[rand(chars.length)] }.join
+        end
+      end
+
+    end
+
+  end
+end