watirloo 0.0.7

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+spec/reports
+pkg
+
+## PROJECT::SPECIFIC

data/History.txt

@@ -0,0 +1,44 @@
+== 0.0.6 22Jul2009
+* make page container the receiver of all face methods implicitly
+* some cleanup
+* 117 examples in rspec
+* locker moved to temp. remove log/locker.yml mechanism
+
+== 0.0.5 22Jul2009
+* Page is a module and not a class. include Watirloo::Page in your testcase (rspec group or cucumber feature) to add view methods.
+* Locker uses log/locker.yml by default. If you want your own somewhere in your project update the Watirloo::Locker.locker = "path/to/your/log/locker.yml"
+* multiple browser support with Watirloo::Desktop and Locker
+* 115 examples in rspec
+
+== 0.0.4 16feb2009
+* Radio and Checkbox Groups, UseCase class and reflector
+  * RadioGroups class and enhance radio_group(how, what) method
+  * CheckboxGroups class and enhance checkbox_group(how, what) method
+  * ElementCollections.reflect and Container.reflect method redesign
+  
+== 0.0.3 25jan2009
+
+* implement inheritable class interfaces
+  * subclasses inherit class level interfaces from superclasses
+  * initialize makes a set of interfaces to that instance only but inherits class interfaces from entire tree
+  * adding interfaces to the instance does not leak into classes
+
+== 0.0.2 03jan2009
+
+* implement radio_group and checkbox_group for IE and Firefox
+  * Create RadioGroup and CheckboxGroup class for Watir::IE and FireWatir::Firefox
+  * update tests to run for both browsers unchanged.
+  
+== 0.0.1 22dec2008
+
+* initial merge with newgem generated structure to make it a gem
+  * Patches to Watir and Firewatir
+  * radio_group method added to Watir (not to FireWatir yet)
+  * patch fof Firefox.attach to just attach to the latest window without starting new ff win.
+* tests
+  * built with intent to run unchanged on IE and Firefox
+  * tests run on test/spec gem
+
+== 0.0.0 
+
+* start collecting ideas about building an abstratction layer based on semantic domain model vocabulary customers speak.

data/Manifest.txt

@@ -0,0 +1,59 @@
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile.rb
+lib/watirloo.rb
+lib/watirloo/browsers.rb
+lib/watirloo/desktop.rb
+lib/watirloo/extension/firewatir_ducktape.rb
+lib/watirloo/extension/object.rb
+lib/watirloo/extension/watir_ducktape.rb
+lib/watirloo/extension/watir_reflector.rb
+lib/watirloo/locker.rb
+lib/watirloo/page.rb
+script/console
+script/console.cmd
+script/destroy
+script/destroy.cmd
+script/generate
+script/generate.cmd
+script/reflect.rb
+spec/browser_spec.rb
+spec/browser_threads_spec.rb
+spec/checkbox_group_spec.rb
+spec/checkbox_groups_spec.rb
+spec/checkboxes_value_spec.rb
+spec/desktop_spec.rb
+spec/extra/browser_events_spec.rb
+spec/extra/page_objects_metrics.rb
+spec/face_mixing_spec.rb
+spec/firewatir/attach_instance_test.rb
+spec/firewatir/spec_results.html
+spec/firewatir/spec_results.txt
+spec/firewatir/spec_results_failed.txt
+spec/html/census.html
+spec/html/checkbox_group1.html
+spec/html/frameset1.html
+spec/html/labels.html
+spec/html/no_title.html
+spec/html/person.html
+spec/html/radio_group.html
+spec/html/select_lists.html
+spec/input_element_spec.rb
+spec/label_spec.rb
+spec/locker_spec.rb
+spec/page_spec.rb
+spec/person_def_wrappers_spec.rb
+spec/radio_group_spec.rb
+spec/radio_groups_spec.rb
+spec/reflector_spec.rb
+spec/select_list_options_spec.rb
+spec/select_lists_spec.rb
+spec/spec_helper.rb
+spec/spec_helper_ff.rb
+spec/spec_helper_runner.rb
+spec/spec_results.html
+spec/spec_results.txt
+spec/spec_results_failed.txt
+spec/text_fields_spec.rb
+watirloo.gemspec

data/README.rdoc

@@ -0,0 +1,94 @@
+= Watirloo
+
+* http://github.com/marekj/watirloo
+
+== DESCRIPTION:
+
+Custom Extensions for Watir, Firewatir. Acceptance Test Helper based on semantic page objects modeling customer's domain language
+It helps you write human readable and machine executable browser tests. Isolates GUI from Tests.
+
+The Human Readable part helps you create interfaces to elements on the page and tags them with friendly names 
+based on vocabulary of Business Domain. The Machine Executable parts talk to Watir API hooking into DOM elements. 
+it helps you concentrate in your acceptance tests on the intention and the customer's language and not on implementation of DOM.
+Write customer facing tests hence the metaphor of face for Page Objects of Significance to the Customer.
+
+== FEATURES/PROBLEMS:
+
+* Extensions to Watir and Firewatir gems to ease testing and joy with page objects
+* group radios in #radio_group and checkboxes in #checkbox_group and acts each group as page object
+* Maintains multiple browsers on the desktop and stores window handles so you can reattach to the browser under test later (see Watirloo::Locker)
+* Watches and maintains your desktop for browsers existence. (Watirloo::Desktop)
+* Browser is managed automatically with Watirloo::browser
+* Isolates GUI from tests with face methods that introduce customer facing friendly names for elements
+* add reflect method to generate scaffolding code for your page elements (reflect currently uses browser as container. Alter scaffodling if you use frames)
+* look at spec dir for examples of usage with rspec
+
+
+== SYNOPSIS:
+
+By convention Watirloo::browser attaches itself to the existing IE browser instance on the desktop and maintains the handles to reattach later
+
+Example:
+
+    Given a page with text fields for last name and first name
+    When I want to enter the name 'Kurt Vonnegut'
+    And I don't want to talk to implementation
+    But I want a friendly name of element on the page
+    Then I use Watirloo shortcuts
+    When I define an interface to watir implementation with a semantic key
+    And I define my data as hash with the same semantic key
+    Then I can automatically let watirloo enter my test data on a page
+
+    # rspec as client
+
+    describe "using watirloo page to isolate and bind gui view to data" do
+      include Watirloo::Page
+      face(:last_name) { text_field(:name, 'l_nm') }
+      face(:first_name) { text_field(:name, 'f_nm') }
+
+      it "enters data on the page" do
+        first_name.set "Kurt"
+        last_name.set "Vonnegut"
+      end
+
+      it "sprays data on elements defined" do
+        spray :last_name => 'Vonnegut', :first_name => 'Kurt'
+      end
+
+      it "grabs data from elements and validates" do
+        data = {:first_name => "Kurt", :last_name => 'Vonnegut'}
+        spray data
+        scrape(data.keys).should == data
+      end
+
+    end
+  
+== REQUIREMENTS:
+
+* watir = 1.6.2 
+* firewatir = 1.6.2 if you want to use Firefox
+* rspec gem if you want to run watirloo examples included
+
+== INSTALL:
+
+* Run the following if you haven't already:
+    gem sources -a http://gems.github.com
+
+* Install the gem(s):
+  gem install marekj-watirloo
+
+* or download from : http://github.com/marekj/watirloo/downloads
+
+=== ROADMAP
+
+* add Logging gem and log all actions for audit
+* provide UserStory type of container for exploratory testing (UseCase, Feature, TestScenario etc...)
+* provide examples for Cucumber
+* make specs run with firewatir
+
+== LICENSE
+
+(The MIT License)
+
+Copyright (c) 2008 marekj
+http://www.opensource.org/licenses/mit-license.php

data/Rakefile

@@ -0,0 +1,68 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "watirloo"
+    gem.summary = %Q{small Watir framework based on semantic page object adapters for DOM elements}
+    gem.description = %Q{Helps you write tests in the language of the customer's domain}
+    gem.email = "marekj.com@gmail.com"
+    gem.homepage = "http://github.com/marekj/watirloo"
+    gem.authors = ["marekj"]
+    gem.add_dependency 'watir', '>=1.6.2'
+    gem.add_development_dependency 'rspec', '>= 1.2.7'
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+
+require 'spec/rake/spectask'
+desc "spec with ie browser"
+Spec::Rake::SpecTask.new do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/*_spec.rb']
+  spec.spec_files.exclude('spec/reflector*') #TODO fix reflector feature
+  spec.fail_on_error = false
+  spec.spec_opts = [
+    "--color",
+    "--require spec/spec_helper_runner.rb", # slow execution expected. closes all browsers on desktop before :all
+    "--format specdoc",
+    "--format specdoc:spec/spec_results.txt",
+    "--format failing_examples:spec/spec_results_failed.txt",
+    "--format html:spec/spec_results.html",
+    #"--diff",
+    "--loadby mtime",
+    #"--dry-run", # will overwrite any previous spec_results
+    #"--generate-options spec/spec.opts",
+  ]
+end
+
+# FIXME fix the spec FileList to only include those that execut for firefox. use taglog lib
+desc "spec with ff browser"
+Spec::Rake::SpecTask.new(:spec_ff) do |t|
+  t.spec_files = FileList['spec/*_spec.rb']
+  t.spec_opts = [
+    "--color",
+    "--require spec/spec_helper_ff.rb",
+    "--format specdoc",
+    "--format specdoc:spec/firewatir/spec_results.txt",
+    "--format failing_examples:spec/firewatir/spec_results_failed.txt",
+    "--format html:spec/firewatir/spec_results.html",
+    "--loadby mtime" ]
+end
+
+#task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "watirloo #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.7

data/lib/watirloo/browsers.rb

@@ -0,0 +1,73 @@
+module Watirloo
+
+  # This is 'opinionated' method.
+  # The way I work with browsers is this:
+  # I save the current handle of the browser (ie.hwnd) to the storage yaml file so I can reattach to the same
+  # browser later. Basically in exploratory testing I don't want to start and close browsers. I want to maintain
+  # reference to one (or more) browsers and I have nicknames for them.
+  # on restart of tests useing Watirloo I reuse the browser. If the browser is not there I just start a new browser which
+  # will from now on become my new 'default' test session browser.
+  # In Case of Firefox I attach to the 'one' existing firefox or a start a new one.
+  # So this method either attaches to one that's there or it starts a new one and puts it in Browsers::Storage
+  # this way of working with browsers is opinionated I think.
+  # if you want you can just use Watir::IE.start and reuse that browsers for tests. This here is a convenience method
+  def self.browser(key = 'default')
+    case Browsers.target
+    when :ie then Browsers.ie key
+    when :firefox then Browsers.ff
+    end
+  end
+
+  # manage references to browsers. Currently IE or Firefox.
+  # Safari? Other Browser? not yet
+  module Browsers
+
+    @@target = :ie #by default we talk to IE on Windows.
+    @@targets = [:ie, :firefox]
+
+    class << self
+
+      # set and get the target. by default we talk to :ie.
+      def target
+        return @@target
+      end
+
+      def target=(indicator)
+        if @@targets.include? indicator
+          @@target = indicator
+        else
+          raise Exception, "target indicator #{indicator} is not valid: use :ie or :firefox"
+        end
+      end
+
+
+      # provides browser instance to client.
+      # attaches to the existing 'default' test session browser on the desktop
+      # By convention the mental model here is that we are working
+      # with one browser on the desktop. This is how a person would typically work
+      def ie(key='default')
+        begin
+          Locker.browser key
+        rescue #XXX it's probably a bad practice to use exception for logic control
+          # TODO logger here
+          ie = Watir::IE.start
+          sleep 3
+          Locker.add(ie, key)
+          ie #return newly created browser for the test session and store it for laterusage
+        end
+      end
+
+      def ff
+        require 'watirloo/firewatir_ducktape'
+        # this is a cruch for quick work with pages.
+        # in reality you want to create a browser and pass it as argument to initialize Page class
+        begin
+          FireWatir::Firefox.attach #this attach is a crutch
+        rescue
+          puts 'got to start browser ff dude'
+        end
+
+      end
+    end
+  end
+end

data/lib/watirloo/desktop.rb

@@ -0,0 +1,44 @@
+module Watirloo
+
+  # The browser desktop manager
+  # checks to see what browsers already exist on the dekstop.
+  # compares what is on the desktop to what was there last time
+  module Desktop
+
+    class << self
+
+      # returns browser windows found on the desktop
+      def browsers
+        brs =[]
+        Watir::IE.each {|ie| brs << ie }
+        brs
+      end
+
+      # return handles of Browsers found on desktop
+      def hwnds
+        hs =[]
+        browsers.each {|ie| hs << ie.hwnd}
+        hs
+      end
+
+      # returns handles for browsers that appeared on Desktop since the last scan for browsers
+      def additions(known_hwnds)
+        hwnds.select {|h| !known_hwnds.include?(h)}
+      end
+
+      # returns handles for browsers no longer found on the Desktop since the last scan for browsers
+      def deletions(known_hwnds)
+        known_hwnds.select {|h| !hwnds.include?(h)}
+      end
+
+      # Closes all the browsers on the desktop.
+      # Creats a known clear slate where no browsers exist
+      def clear
+        browsers.each {|ie| ie.close; sleep 3}
+        sleep 3
+        raise Exception, "Failed to clear all the browsers from the desktop" unless browsers.empty?
+      end
+
+    end
+  end
+end

data/lib/watirloo/extension/firewatir_ducktape.rb

@@ -0,0 +1,194 @@
+gem 'firewatir', '>=1.6.2' # dependency
+require 'firewatir'
+
+module FireWatir
+  
+  # duck punch and ducktape Firefox for Watirloo needs
+  # some of it is cosmetic surgery and some new methods with intention of
+  # sending a patch to Watir maintainers
+  class Firefox
+    
+    # attach to the existing Firefox that was already started with JSSH option.
+    # this is a hack for Watirloo. it only attaches to the latest firefox.
+    # it assumes there is only one instance of FF window open on the desktop
+    def self.attach
+      Firefox.new :attach => true
+    end
+    
+    # add option key :attach as a hack
+    # :attach => true to attach to topmost window in getWindows().lenght-1
+    # split up initialize to conditionally start FireFox
+    def initialize(options = {})
+      _start_firefox(options) unless options[:attach]
+      set_defaults()
+      get_window_number()
+      set_browser_document()
+    end
+    
+    # refactor initialize method to move all starting of FF into its own method
+    def _start_firefox(options)
+      if(options.kind_of?(Integer))
+        options = {:waitTime => options}
+      end
+      
+      if(options[:profile])
+        profile_opt = "-no-remote -P #{options[:profile]}"
+      else
+        profile_opt = ""
+      end
+      
+      waitTime = options[:waitTime] || 2
+      
+      case RUBY_PLATFORM 
+      when /mswin/
+        # Get the path to Firefox.exe using Registry.
+        require 'win32/registry.rb'
+        path_to_bin = ""
+        Win32::Registry::HKEY_LOCAL_MACHINE.open('SOFTWARE\Mozilla\Mozilla Firefox') do |reg|
+          keys = reg.keys
+          reg1 = Win32::Registry::HKEY_LOCAL_MACHINE.open("SOFTWARE\\Mozilla\\Mozilla Firefox\\#{keys[0]}\\Main")
+          reg1.each do |subkey, type, data|
+            if(subkey =~ /pathtoexe/i)
+              path_to_bin = data
+            end
+          end
+        end
+        
+      when /linux/i
+        path_to_bin = `which firefox`.strip
+      when /darwin/i
+        path_to_bin = '/Applications/Firefox.app/Contents/MacOS/firefox'
+      when /java/
+        raise "Not implemented: Create a browser finder in JRuby"
+      end
+      
+      @t = Thread.new { system("#{path_to_bin} -jssh #{profile_opt}")}   
+      sleep waitTime
+      
+    end
+    private :_start_firefox
+
+  end
+
+  class SelectList
+    
+    include Watir::SelectListCommonWatir
+    
+        # accepts one text item or array of text items. if array then sets one after another. 
+    # For single select lists the last item in array wins
+    # 
+    # examples
+    #   select_list.set 'bla' # => single option text
+    #   select_list.set ['bla','foo','gugu'] # => set 3 options by text. If 
+    #       this is a single select list box it will set each value in turn
+    #   select_list set 1 # => set the first option in a list
+    #   select_list.set [1,3,5] => set the first, third and fith options
+    def set(item)
+      _set(:text, item)
+    end
+
+    # set item by the option value attribute. if array then set one after anohter.
+    # see examples in set method
+    def set_value(value)
+      _set(:value, value)
+    end
+    
+    # returns array of value attributes
+    # each option usually has a value attribute 
+    # which is hidden to the person viewing the page
+    def values
+      a = []
+      items.each do |item|
+        a << option(:text, item).value
+      end
+      return a
+    end
+    
+    alias clear clearSelection
+    
+    # alias, items or contents return the same visible text items
+    alias items getAllContents
+    
+  end
+
+  # RadioGroup and CheckboxGroup common behaviour
+  module RadioCheckGroup
+    
+    include Watir::RadioCheckGroupCommonWatir
+
+    def values
+      values = []
+      @o.each {|thing| values << thing.value}
+      return values
+    end
+    
+    def get_by_value value
+      if values.member? value
+        @o.find {|thing| thing.value == value}
+      else
+        raise ::Watir::Exception::WatirException, "value #{value} not found in hidden values"
+      end
+    end
+  end
+  
+  class CheckboxGroup
+    
+    include RadioCheckGroup
+    include Watir::CheckboxGroupCommonWatir
+    
+    def initialize(container, name)
+      @container = container
+      @name = name
+      @o = []
+      @container.checkboxes.each do |cb| #TODO find why find_all does not work
+        if cb.name == @name
+          @o << cb
+        end
+      end
+    end
+    
+    # which values are selected?
+    def selected_values
+      values = []
+      selected_checkboxes.each do |cb|
+        values << cb.value
+      end
+      return values
+    end
+  end
+  
+  class RadioGroup
+    
+    include RadioCheckGroup
+    include Watir::RadioGroupCommonWatir
+    
+    def initialize(container, name)
+      @container = container
+      @name = name
+      @o = []
+      @container.radios.each do |r| #TODO find why find_all does not work
+        if r.name == @name
+          @o << r
+        end
+      end
+      return @o
+    end
+    
+    # see Watir::RadioGroup.selected_value
+    def selected_value
+      selected_radio.value
+    end
+    alias selected selected_value
+  end
+  
+  
+  module Container
+    def radio_group(name)
+      RadioGroup.new(self, name)
+    end
+    
+    def checkbox_group(name)
+      CheckboxGroup.new(self, name)
+    end
+  end
+end

data/lib/watirloo/extension/object.rb

@@ -0,0 +1,32 @@
+
+# http://blog.jayfields.com/2006/09/ruby-instanceexec-aka-instanceeval.html # hints on usage
+# http://blog.jayfields.com/2008/02/ruby-dynamically-define-method.html # write up on usage
+# http://eigenclass.org/hiki.rb?instance_exec # more study
+# http://eigenclass.org/hiki.rb?bounded+space+instance_exec # fix for mem leak final used here
+# http://eigenclass.org/hiki.rb?Changes+in+Ruby+1.9#l23
+# http://www.jroller.com/abstractScope/entry/passing_parameters_to_an_instance
+# instance_exec is used for face methods it allows you to pass args and block to be evaled.
+# it works like instance eval but instance eval does not accept arguments
+if VERSION <= '1.8.6'
+  class Object
+    module InstanceExecHelper; end
+    include InstanceExecHelper
+    # instance_exec method evaluates a block of code relative to the specified object, with parameters whom come from outside the object.
+    def instance_exec(*args, &block)
+      begin
+        old_critical, Thread.critical = Thread.critical, true
+        n = 0
+        n += 1 while respond_to?(mname="__instance_exec#{n}")
+        InstanceExecHelper.module_eval{ define_method(mname, &block) }
+      ensure
+        Thread.critical = old_critical
+      end
+      begin
+        ret = send(mname, *args)
+      ensure
+        InstanceExecHelper.module_eval{ remove_method(mname) } rescue nil
+      end
+      ret
+    end
+  end
+end