symbiont 0.0.2 → 0.0.3

data/.gitignore

@@ -1,10 +1,21 @@
-.bundle/*
-output/*
-.idea/*
-pkg/*
 *.gem
+*.rbc
 *.swo
 *.swp
+.bundle
+.config
+.yardoc
 .DS_Store
 Gemfile.lock
-
+InstalledFiles
+_yardoc
+coverage
+output/
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/HISTORY.md

@@ -1,6 +1,12 @@
 Change Log and History
 ======================
 
+Version 0.0.3 / 2012-04-11
+--------------------------
+
+Symbiont went in a different direction, which is excluding Selenium and focusing on Watir. Watir is simply a cleaner API that makes for a more consistent implementation. The focus here was on getting the basis for the generators and enclosers in place. The idea of page and activity definitions that serve as action contexts was also put in place.
+
+
 Version 0.0.2 / 2012-03-15
 --------------------------
 

data/README.md

@@ -8,6 +8,20 @@ The Symbiont gem is designed to provide an open framework for running automated
 
 Right now the best information on the purpose of this project and how it works can be found on [my Symbiont-tagged blog posts](http://testerstories.com/?cat=16).
 
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    gem 'symbiont'
+    
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install symbiont
 
 Meaning
 -------
@@ -18,8 +32,16 @@ Symbiotic relationships include associations in which one organism lives on anot
 
 So, with that bit of context, think of this gem as a facultative, endosymbiotic organism that lives within your test logic, giving it strength and sustenance.
 
+Contributing
+------------
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
 
 Copyright
 ---------
 
-See the LICENSE file for details.
+See the LICENSE file for details.

data/Rakefile

@@ -1,3 +1,4 @@
+#!/usr/bin/env rake
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 

data/lib/symbiont/enclosers.rb

@@ -0,0 +1,26 @@
+module Symbiont
+  module Enclosers
+    
+    # Used to identify a web object as existing within an enclosing object
+    # like a frame or an iframe. It is possible to nest by passing in parent
+    # enclosers as the second parameter.
+    #
+    # @param [String] locator how an encloser will be referenced; the
+    # only valid locators here are :id, :index, and :name
+    # @param encloser a parent encloser that is passed from a previous call
+    # @param [optional] block that contains calls to web objects within the
+    # encloser
+    #
+    # @example
+    #   within_frame(id: "loginSection") do |encloser|
+    #     text_field :username, id: "userName", frame: encloser
+    #     button :login, id: "btnSubmit", frame: encloser
+    #   end
+    def within_frame(locator, encloser=nil, &block)
+      encloser = [] if encloser.nil?
+      encloser << locator
+      block.call(encloser)
+    end
+    
+  end # module: Enclosers
+end # module: Symbiont

data/lib/symbiont/factory.rb

@@ -0,0 +1,33 @@
+module Symbiont
+  module Factory
+    
+    # Creates a definition context for actions.
+    #
+    # @param [Class] definition The name of a definition class
+    # @param [optional] block Logic to execute within the context of the
+    # definition
+    # @return [Object] instance of the definition
+    def on(definition, &block)
+      @active = definition.new(@browser)
+      block.call @active if block
+      @active
+    end
+    
+    # Creates a definition context for actions and establishes the
+    # context for display.
+    #
+    # @param [Class] definition The name of a definition class
+    # @param [optional] block Logic to execute within the context of the
+    # definition
+    # @return [Object] instance of the definition
+    def on_view(definition, &block)
+      @active = definition.new(@browser, true)
+      block.call @active if block
+      @active
+    end
+    
+    alias :during :on
+    alias :start_activity :on_view
+    
+  end # module: Factory
+end # module: Symbiont

data/lib/symbiont/generators.rb

@@ -28,10 +28,49 @@ module Symbiont
       end
     end
 
+    # This method allows for a title_is() method in definitions. The idea
+    # is that you can specify the title of a page. This title can then be
+    # checked on. Note that the assumption here is that the title will
+    # be static. The argument to the method can, however, be a
+    # regular expression.
+    #
+    # @param [String] title the literal string of the expected title
+    # @param [Regexp] title the pattern string of the expected title
+    # @return [Nil]
+    # @raise exception if the title found does not match the title expected
+    def title_is(title)
+      define_method('has_title?') do
+        valid_title = title =~ @browser.title if title.kind_of?(Regexp)
+        valid_title = title == @browser.title if title.kind_of?(String)
+        raise "Expected title: '#{title}'; Actual title: '#{@browser.title}'" unless valid_title
+        valid_title
+      end
+    end
+    
+    # This method allows for a look_for() method in definitions. The idea
+    # is that you can specify an object that should appear on a given page
+    # when that page appears.
+    #
+    # @param [Symbol] widget the friendly name of the object declaration
+    # @param [optional, Integer] timeout the time to wait for the object to appear
+    # @return [Boolean] true if object was found
+    def look_for(widget, timeout=5)
+      define_method('has_object?') do
+        if self.respond_to? "#{widget}_object"
+          self.send("#{widget}_object").when_actionable(timeout)
+        else
+          puts "The #{widget} object was not declared and could not be checked."
+        end
+      end
+    end
+    
     # Definition method for links. Methods for the following actions will
     # be created:
     # * reference a link (identifier_object, identifier_link)
+    # * check text of link (identifier_text)
     # * click a link (identifier)
+    # * check for existence (identifier?, identifier_exists?)
+    # * check for visibility (identifier_?, identifier_visible?)
     # @param [Symbol] identifier the friendly name of the web object
     # @param [optional, Hash] locator the key/values that identify the object
     # @return [Object] instance of Symbiont::WebObjects::Link
@@ -41,16 +80,36 @@ module Symbiont
       end
 
       alias_method "#{identifier}_link".to_sym, "#{identifier}_object".to_sym
-
+      
+      define_method("#{identifier}_text") do
+        @platform.get_link_text_for(locator.clone)
+      end
+      
       define_method(identifier) do
         @platform.click_link_for(locator.clone)
       end
+
+      define_method("#{identifier}_exists?") do
+        @platform.check_link_for_existence(locator.clone)
+      end
+      
+      alias_method "#{identifier}?".to_sym, "#{identifier}_exists?".to_sym
+      
+      define_method("#{identifier}_visible?") do
+        @platform.check_link_for_visibility(locator.clone)
+      end
+      
+      alias_method "#{identifier}_?".to_sym, "#{identifier}_visible?".to_sym
     end
 
     # Definition method for buttons. Methods for the following actions will
     # be created:
     # * reference a button (identifier_object, identifier_button)
+    # * get text from button (identifier_text)
     # * click a button (identifier)
+    # * check for existence (identifier?, identifier_exists?)
+    # * check for visibility (identifier_?, identifier_visible?)
+    # * check for enabled (identifier!, identifier_enabled?)
     # @param [Symbol] identifier the friendly name of the web object
     # @param [optional, Hash] locator the key/values that identify the object
     # @return [Object] instance of Symbiont::WebObjects::Button
@@ -60,17 +119,42 @@ module Symbiont
       end
 
       alias_method "#{identifier}_button".to_sym, "#{identifier}_object".to_sym
-
+      
+      define_method("#{identifier}_text") do
+        @platform.get_button_text_for(locator.clone)
+      end
+      
       define_method(identifier) do
         @platform.click_button_for(locator.clone)
       end
+
+      define_method("#{identifier}_exists?") do
+        @platform.check_button_for_existence(locator.clone)
+      end
+      
+      alias_method "#{identifier}?".to_sym, "#{identifier}_exists?".to_sym
+      
+      define_method("#{identifier}_visible?") do
+        @platform.check_button_for_visibility(locator.clone)
+      end
+      
+      alias_method "#{identifier}_?".to_sym, "#{identifier}_visible?".to_sym
+      
+      define_method("#{identifier}_enabled?") do
+        @platform.check_button_for_enabled(locator.clone)
+      end
+      
+      alias_method "#{identifier}!".to_sym, "#{identifier}_enabled?".to_sym
     end
 
     # Definition method for text fields. Methods for the following actions
     # will be created:
-    # * reference a text field (identifier_object, identifier_button)
+    # * reference a text field (identifier_object, identifier_text_field)
     # * get text from a text field (identifier)
     # * set text in a text field (identifier=)
+    # * check for existence (identifier?, identifier_exists?)
+    # * check for visibility (identifier_?, identifier_visible?)
+    # * check for enabled (identifier!, identifier_enabled?)
     # @param [Symbol] identifier the friendly name of the web object
     # @param [optional, Hash] locator the key/values that identify the object
     # @return [Object] instance of Symbiont::WebObjects::TextField
@@ -88,7 +172,25 @@ module Symbiont
       define_method("#{identifier}=") do |value|
         @platform.set_text_field_value_for(locator.clone, value)
       end
+
+      define_method("#{identifier}_exists?") do
+        @platform.check_text_field_for_existence(locator.clone)
+      end
+      
+      alias_method "#{identifier}?".to_sym, "#{identifier}_exists?".to_sym
+      
+      define_method("#{identifier}_visible?") do
+        @platform.check_text_field_for_visibility(locator.clone)
+      end
+      
+      alias_method "#{identifier}_?".to_sym, "#{identifier}_visible?".to_sym
+      
+      define_method("#{identifier}_enabled?") do
+        @platform.check_text_field_for_enabled(locator.clone)
+      end
+      
+      alias_method "#{identifier}!".to_sym, "#{identifier}_enabled?".to_sym
     end
 
   end # module: Generators
-end # module: Symbiont
+end # module: Symbiont

data/lib/symbiont/logger.rb

@@ -0,0 +1,5 @@
+module Symbiont
+  def self.trace(message, level=1)
+    puts("*" * level + " #{message}") if ENV['TRACE'] == 'on'
+  end
+end

data/lib/symbiont/platform_watir/platform_object.rb

@@ -13,53 +13,154 @@ module Symbiont
         def visit(url)
           @browser.goto(url)
         end
-
+        
         # Platform method to return a link object.
         # Link objects are of type: Symbiont::WebObjects::Link
         # @see Symbiont::Generators#link
         def get_link_for(locator)
-          web_object = @browser.instance_eval "link(locator)"
-          WebObjects::Link.new()
+          reference_web_object("link(locator)", WebObjects::Link, locator)
+        end
+        
+        # Platform method to get text of link object.
+        # @see Symbiont::Generators#link
+        def get_link_text_for(locator)
+          access_web_object("link(locator).text", locator)
         end
 
         # Platform method to click a link object.
         # @see Symbiont::Generators#link
         def click_link_for(locator)
-          @browser.instance_eval "link(locator).click"
+          access_web_object("link(locator).click", locator)
         end
 
+        # Platform method to check if link object exists.
+        # @see Symbiont::Generators#link
+        def check_link_for_existence(locator)
+          access_web_object("link(locator).exists?", locator)
+        end
+        
+        # Platform method to check if link object is visible.
+        # @see Symbiont::Generators#link
+        def check_link_for_visibility(locator)
+          access_web_object("link(locator).visible?", locator)
+        end
+        
         # Platform method to return a button object.
         # Button objects are of type: Symbiont::WebObjects::Button
         # @see Symbiont::Generators#button
         def get_button_for(locator)
-          web_object = @browser.instance_eval "button(locator)"
-          WebObjects::Button.new()
+          reference_web_object("button(locator)", WebObjects::Button, locator)
         end
-
+        
+        # Platform method to get text of button object.
+        # @see Symbiont::Generators#button
+        def get_button_text_for(locator)
+          access_web_object("button(locator).text", locator)
+        end
+        
         # Platform method to click a button object.
         # @see Symbiont::Generators#button
         def click_button_for(locator)
-          @browser.instance_eval "button(locator).click"
+          access_web_object("button(locator).click", locator)
+        end
+
+        # Platform method to check if button object exists.
+        # @see Symbiont::Generators#button
+        def check_button_for_existence(locator)
+          access_web_object("button(locator).exists?", locator)
+        end
+        
+        # Platform method to check if button object is visible.
+        # @see Symbiont::Generators#button
+        def check_button_for_visibility(locator)
+          access_web_object("button(locator).visible?", locator)
+        end
+        
+        # Platform method to check if button object is enabled.
+        # @see Symbiont::Generators#button
+        def check_button_for_enabled(locator)
+          access_web_object("button(locator).enabled?", locator)
         end
 
         # Platform method to return a text field object.
         # Text field objects are of type: Symbiont::WebObjects::TextField
         # @see Symbiont::Generators#text_field
         def get_text_field_for(locator)
-          @browser.instance_eval "text_field(locator)"
-          WebObjects::TextField.new()
+          reference_web_object("text_field(locator)", WebObjects::TextField, locator)
         end
 
         # Platform method to retrieve text from a text field object.
         # @see Symbiont::Generators#text_field
         def get_text_field_value_for(locator)
-          @browser.instance_eval "text_field(locator).value"
+          access_web_object("text_field(locator).value", locator)
         end
 
         # Platform method to enter text into a text field object.
         # @see Symbiont::Generators#text_field
         def set_text_field_value_for(locator, value)
-          @browser.instance_eval "text_field(locator).set(value)"
+          access_web_object("text_field(locator).set(value)", locator, value)
+        end
+
+        # Platform method to check if text field object exists.
+        # @see Symbiont::Generators#text_field
+        def check_text_field_for_existence(locator)
+          access_web_object("text_field(locator).exists?", locator)
+        end
+        
+        # Platform method to check if text field object is visible.
+        # @see Symbiont::Generators#text_field
+        def check_text_field_for_visibility(locator)
+          access_web_object("text_field(locator).visible?", locator)
+        end
+        
+        # Platform method to check if text field object is enabled.
+        # @see Symbiont::Generators#text_field
+        def check_text_field_for_enabled(locator)
+          access_web_object("text_field(locator).enabled?", locator)
+        end
+        
+        private
+        
+        # This method is called by any platform methods that require getting
+        # an object reference.
+        #
+        # @param [String] action the driver logic to be sent to the browser
+        # @param [Object] object_type the type of web object that will receive the action
+        # @param [Hash] locator the specific web object selector, mainly for parsing
+        # @return [Object] the web object identified by the action
+        def reference_web_object(action, object_type, locator)
+          enclosers = locator.delete(:frame)
+          web_object = @browser.instance_eval "#{enclosed_by(enclosers)}#{action}"
+          object_type.new(web_object)
+        end
+        
+        # This method is called by any platform methods that require accessing
+        # a web object with the intent of manipulating it or getting information
+        # from it.
+        #
+        # @param [String] action the driver logic to be sent to the browser
+        # @param [Hash] locator the specific web object selector, mainly for parsing
+        # @param [String] value any specific information that must be sent to the
+        # web object
+        # @return [Any] the information or object returned by the action
+        def access_web_object(action, locator, value=nil)
+          enclosers = locator.delete(:frame)
+          @browser.instance_eval "#{enclosed_by(enclosers)}#{action}"
+        end
+        
+        # This method is used to wrap a web object locator within the locator for an
+        # enclosing web object. Currently the only enclosing objects this makes sense
+        # for are iframes and frames.
+        #
+        # @param [Hash] enclosers locator information for enclosing web objects
+        # @return [Hash] driver-specific frame selector
+        def enclosed_by(enclosers)
+          return if enclosers.nil?
+          
+          key = enclosers[0].keys.first
+          value = enclosers[0].values.first
+          
+          encloser_locator = "frame(:#{key} => '#{value}')."
         end
       end # class: PlatformObject
 
@@ -67,4 +168,4 @@ module Symbiont
   end # module: Platforms
 end # module: Symbiont
 
-Dir["#{File.dirname(__FILE__)}/../web_objects/**/*.rb"].sort.each { |file| require file }
+Dir["#{File.dirname(__FILE__)}/../web_objects/**/*.rb"].sort.each { |file| require file }

data/lib/symbiont/platforms.rb

@@ -2,16 +2,13 @@ module Symbiont
   module Platforms
 
     require 'watir-webdriver'
-    require 'selenium-webdriver'
 
     # This module determines what execution platform Symbiont will use.
     # The decision is based on the browser that has been established for
-    # the execution profile
+    # the execution profile.
     def get_platform_for(browser)
       if browser.is_a?(Watir::Browser)
         return @platform = Symbiont::Platforms::WatirWebDriver::PlatformObject.new(@browser)
-      elsif browser.is_a?(Selenium::WebDriver::Driver)
-        return @platform = Symbiont::Platforms::SeleniumWebDriver::PlatformObject.new(@browser)
       else
         raise "Unable to create a platform object for #{browser}"
       end
@@ -21,4 +18,3 @@ module Symbiont
 end # module: Symbiont
 
 require_relative 'platform_watir'
-require_relative 'platform_selenium'

data/lib/symbiont/version.rb

@@ -1,3 +1,3 @@
 module Symbiont
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/symbiont/web_objects/_common.rb

@@ -2,8 +2,19 @@ module Symbiont
   module WebObjects
 
     class WebObject
-
+      def initialize(web_object)
+        @web_object = web_object
+      end
+      
+      def text
+        @web_object.text
+      end
+      
+      def when_actionable(timeout)
+        @web_object.wait_until_present(timeout)
+        self
+      end
     end # class: WebObject
 
   end # module: WebObjects
-end # module: Symbiont
+end # module: Symbiont

data/lib/symbiont.rb

@@ -1,14 +1,15 @@
 require 'symbiont/version'
+require 'symbiont/logger'
 require 'symbiont/platforms'
 require 'symbiont/generators'
+require 'symbiont/enclosers'
 
 module Symbiont
   include Platforms
-
+  
   # Used to make a platform object accessible. Will hold object
   # references like these:
   # <Symbiont::Platforms::WatirWebDriver::PlatformObject:0x2cbe8a0>
-  # <Symbiont::Platforms::SeleniumWebDriver::PlatformObject:0x2cb9608>
   attr_reader :platform
 
   def self.version
@@ -21,8 +22,9 @@ module Symbiont
   # available as class methods. Those methods will be available only in
   # the context of the class (definition) that included Symbiont.
   def self.included(caller)
-    puts("#{caller.class} #{caller} attached the Symbiont")
+    Symbiont::trace("#{caller.class} #{caller} attached the Symbiont")
     caller.extend Symbiont::Generators
+    caller.extend Symbiont::Enclosers
   end
 
   # The initialize method will be invoked when a page definition includes
@@ -32,10 +34,13 @@ module Symbiont
   #   (2) A platform object is created for that browser.
   #
   # @param [Object] browser a browser instance with a tool driver
-  def initialize(browser)
-    puts("Symbiont attached to browser: #{browser}")
+  # @param [boolean] visit if true, a definition will be navigated to
+  def initialize(browser, visit=nil)
+    Symbiont::trace("Symbiont attached to browser: #{browser}")
     @browser = browser
     establish_platform_object_for(browser)
+    view if visit && respond_to?(:view)
+    start if visit && respond_to?(:start)
   end
 
   private

data/spec/spec_helper.rb

@@ -16,22 +16,21 @@ class DefinitionTest
 
   url_is "http://localhost:4567"
   begin_at "http://localhost:4567"
-
+  
+  title_is "Title of Page"
+  look_for :testPage
+  
   link :reset_password, id: "resetPassword"
   button :submit, id: "btnSubmit"
   text_field :login_name, id: "loginName"
+  
+  within_frame(id: "frame") do |frame|
+    text_field :framedLoginName, id: "framedLoginName", frame: frame
+  end
 end
 
 def mock_browser_for_watir
   watir_browser = double('watir')
   watir_browser.stub(:is_a?).with(Watir::Browser).and_return(true)
-  watir_browser.stub(:is_a?).with(Selenium::WebDriver::Driver).and_return(false)
   watir_browser
 end
-
-def mock_browser_for_selenium
-  selenium_browser = double('selenium')
-  selenium_browser.stub(:is_a?).with(Watir::Browser).and_return(false)
-  selenium_browser.stub(:is_a?).with(Selenium::WebDriver::Driver).and_return(true)
-  selenium_browser
-end

data/spec/symbiont/enclosers_spec.rb

@@ -0,0 +1,16 @@
+require 'spec_helper'
+
+describe Symbiont::Enclosers do
+  let(:watir_browser) { mock_browser_for_watir }
+  let(:watir_definition) { DefinitionTest.new(watir_browser) }
+  
+  context "a definition using watir-webdriver" do
+    it "should allow frames to act as a context" do
+      watir_browser.should_receive(:frame).with(id: "frame").and_return(watir_browser)
+      watir_browser.should_receive(:text_field).and_return(watir_browser)
+      web_object = watir_definition.framedLoginName_text_field
+      web_object.should_not be_nil
+      web_object.should be_instance_of Symbiont::WebObjects::TextField
+    end
+  end
+end

data/spec/symbiont/factory_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+require 'symbiont/factory'
+
+class TestFactory
+  include Symbiont::Factory
+  
+  attr_accessor :browser
+end
+
+describe Symbiont::Factory do
+  before(:each) do
+    @factory = TestFactory.new
+    @factory.browser = mock_browser_for_watir
+  end
+  
+  it "should create a new definition object" do
+    @factory.on DefinitionTest do |page|
+      page.should be_instance_of DefinitionTest
+    end
+  end
+  
+  it "should create a new definition object and view it" do
+    @factory.browser.should_receive(:goto).twice
+    @factory.on_view DefinitionTest do |page|
+      page.should be_instance_of DefinitionTest
+    end
+  end
+  
+  it "should set a reference to be used outside the factory" do
+    active = @factory.on DefinitionTest
+    current = @factory.instance_variable_get "@active"
+    current.should === active
+  end
+  
+end