page_object_wrapper 0.0.6 → 1.0.0

data/README.md

@@ -1,6 +1,7 @@
 # PageObjectWrapper
 
-Wraps watir-webdriver with convenient testing interface, based on PageObjects automation testing pattern. Simplifies resulting automated test understanding.
+Wraps watir-webdriver with convenient testing interface, based on PageObjects automation testing pattern. Simplifies resulting automated test understanding.  
+*Warning:* version 1.0 and higher are not compatible with older versions
 
 ## Installation
 
@@ -19,354 +20,193 @@ Or install it yourself as:
     $ gem install page_object_wrapper
 
 ## Usage
+#####please look into specs for more detailed usage examples
 
-####please look into specs for more detailed usage examples
-
-#Page object
-
-##PageObjectWrapper
-
-###has .start_browser method which puts Watir::Browser.new to Page.accessor by default
-          PageObjectWrapper.start_browser
-          PageObjectWrapper::Page.accessor.should be_a(Watir::Browser)
-###has .stop_browser method which closes browser
-          PageObjectWrapper.stop_browser
-          PageObjectWrapper::Page.accessor.should_not exist
-###has .restart_browser method which restart current browser
-          PageObjectWrapper.start_browser
-          PageObjectWrapper.restart_browser
-          PageObjectWrapper::Page.accessor.should be_a(Watir::Browser)
-###has .domain= method which reprsents the domain of DUT
-          PageObjectWrapper.domain = 'www.google.com'
-          google_search_page_class.new(true)
-          PageObjectWrapper::Page.accessor.title.should eq('Google')
-###has .timeout= method which sets implicit timeout for webdriver (default is 5 sec)
-    not working yet
-##PageObject class and instance in general
-        let(:page_object){
-          class GoogleSearchPage < PageObjectWrapper::Page
-            attr_accessor :find_form
-            @url="/"
-            def initialize visit=false 
-              super visit
-            end
-          end
-          GoogleSearchPage
-        }
-###PageObject class has @url class variable which can be treated as Page specific path inside current domain
-            page_object.url.should eq('/')
-###init with 'true' is similar to openning page in browser
-          google_search_page = page_object.new(true)
-          page_object.accessor.title.should eq('Google')
-###init with 'false' just returns new instanse, but does not opens browser on that page
-          google_search_page = page_object.new(false)
-          page_object.accessor.title.should_not eq('Google')
-##expected element
-      let(:google_search_with_wrong_expected_element_page_class){
-        class NotGoogleSearchPage < PageObjectWrapper::Page
-          attr_accessor :find_form
-          @url="/"
-          expected_element :text_field, :name => 'some element that does not exist on the page' 
-    
-          def initialize visit=false 
-            super visit
-          end
-        end
-        NotGoogleSearchPage
-      }
-      let(:google_search_with_correct_expected_element_page_class){
-        class GoogleSearchPage < PageObjectWrapper::Page
-          attr_accessor :find_form
-          @url="/"
-          expected_element :text_field, :name => 'q'
-    
-          def initialize visit=false 
-            super visit
-          end
-        end
-        GoogleSearchPage
-      }
-###should raise error when trying to init google_search_with_wrong_expected_element_page_class
-          begin
-          gsearch_page = google_search_with_wrong_expected_element_page_class.new(true) 
-          rescue PageError => e
-            e.should be_a(PageError)
-            e.message.should =~ /PROBLEM:/
-            e.message.should =~ /PAGE:/
-            e.message.should =~ /URL:/
-          end
-###should init google_search_with_correct_expected_element_page_class successfully
-          gsearch_page = google_search_with_correct_expected_element_page_class.new(true)
-          gsearch_page.should be_a(google_search_with_correct_expected_element_page_class)
-##creation of a PageObject method
-        let(:pages_definition){
-          class GoogleAdvancedSearchPage < PageObjectWrapper::Page
-            attr_accessor :as_form
-            @url="/advanced_search"
-            expected_element :text_field, :name => 'as_q'
-            def initialize visit=false
-              super visit
-              @as_form = form(GoogleResultsPage, {:name => 'f'})
-              @as_form.editable(:text_field, {:name => 'as_q'}, :with_words, 'with_words default value', true)
-              @as_form.editable(:text_field, {:name => 'as_epq'}, :with_phrase, 'with_phrase default value', true)
-              @as_form.editable(:text_field, {:name => 'as_oq'}, :with_any_word, 'with_any_word default value', false)
-              @as_form.submitter(:input, {:type => 'submit'})
-            end
-          end
-    
-          class GoogleResultsPage < PageObjectWrapper::Page
-            @url="/"
-            expected_element :button, :name => 'btnG'
-            def initialize visit=false 
-              super visit
-            end
-    
-            def open_advanced_search
-              @@accessor.span(:id => 'ab_opt_icon').when_present.click 
-              @@accessor.a(:id => 'ab_as').when_present.click
-              GoogleAdvancedSearchPage.new 
-            end
-          end
-    
-          class GoogleSearchPage < PageObjectWrapper::Page
-            attr_accessor :find_form
-            @url="/"
-            expected_element :text_field, :name => 'q' 
-            def initialize visit=false 
-              super visit
-              @find_form = form(GoogleResultsPage, {:action => '/search'}) 
-              @find_form.editable(:text_field, {:name => 'q'}, :seach_what, '@find_form default value', true) 
-            end
-          end
-          {:gsearch_page_class => GoogleSearchPage, :gresults_page => GoogleResultsPage, :gadv_page => GoogleAdvancedSearchPage}
-        }
-###return value should be another PageObject instance
-          gsearch_page = pages_definition[:gsearch_page_class].new(true)
-          gsearch_page.find_form.fill_required 
-          gresults_page = gsearch_page.find_form.submit(true) 
-          gadv_page = gresults_page.open_advanced_search
-          gadv_page.should be_a(pages_definition[:gadv_page])
-
-#Form wrapper
-
-##form definition
-        let(:page_objects){
-          class GoogleAdvancedSearchPage < PageObjectWrapper::Page
-            attr_accessor :as_form
-            @url="/advanced_search"
-            expected_element :text_field, :name => 'as_q'
-            def initialize visit=false
-              super visit
-              @as_form = form(GoogleResultsPage, {:name => 'f'})
-              @as_form.editable(:text_field, {:name => 'as_q'}, :with_words, 'with_words default value', true)
-              @as_form.editable(:text_field, {:name => 'as_epq'}, :with_phrase, 'with_phrase default value', true)
-              @as_form.editable(:text_field, {:name => 'as_oq'}, :with_any_word, 'with_any_word default value', false)
-              @as_form.submitter(:input, {:type => 'submit'})
-            end
+### Basic usecase is following
+1. Define page object with PageObjectWrapper.define\_page
+2. Use defined page object inside your tests with usefull page\_object #methods
+
+### Basic principles of a PageObjectWrapper
+- there are following objects: page\_object, elements\_set with elements, table, action, pagination  
+- a page_object contains elements\_sets, tables, actions, paginations
+- an elements\_set contains elements
+- every object has a :label
+- a label identifies the object
+
+Here in the structure of PageObjectWrapper:
+![PageObjectWrapper scheme](page_object_wrapper/blob/master/img/scheme.png)
+
+### Examples
+
+#### definition example
+
+      PageObjectWrapper.define_page(:some_test_page) do
+        locator 'http://www.cs.tut.fi/~jkorpela/www/testel.html'
+        uniq_h1 :text => 'Testing display of HTML elements'
+
+        elements_set(:test_elements) do
+          text_field(:tf) do
+            locator :id => 'f1'
+            missing_food 'some missing food'
+            fresh_food 'some fresh food'
           end
-          class GoogleResultsPage < PageObjectWrapper::Page
-            @url="/"
-            expected_element :button, :name => 'btnG'
-            def initialize visit=false 
-              super visit
-              @find_form = form(GoogleResultsPage, {:action => '/search'}) 
-              @find_form.editable(:text_field, {:name => 'q'}, :seach_what, '@find_form default value', true) 
-            end
+
+          textarea(:ta) do
+            locator :id => 'f2'
           end
-          {:gresults_page_class => GoogleResultsPage, :gadv_page_class => GoogleAdvancedSearchPage}
-        }
-###is defined as #form(TargetPage, how_find_hash)
-              @as_form = form(GoogleResultsPage, {:name => 'f'})
-              @find_form = form(GoogleResultsPage, {:action => '/search'}) 
-###has #editable(:field_type, how_find_hash, :label, default_value, required?) method to set form's fields
-###      :field_type sets corresponding watir element type
-###      how_find_hash is used to locate corresponding watir element on the page
-###      :label is used to reffer to the form field after definition
-###      default_value is used to populate fields with default test data
-###      required = true | false and indicates if the field is required
-###    
-              @as_form.editable(:text_field, {:name => 'as_q'}, :with_words, 'with_words default value', true)
-              @as_form.editable(:text_field, {:name => 'as_epq'}, :with_phrase, 'with_phrase default value', true)
-              @as_form.editable(:text_field, {:name => 'as_oq'}, :with_any_word, 'with_any_word default value', false)
-###has #submitter(:field_type, how_find_hash, how_click_mehtod, click_params) method to set form's submitter
-###      :field_type sets corresponding watir element type
-###      how_find_hash is used to locate corresponding watir element on the page
-###      how_click_mehtod is used to tell Waitr the method which should be applied to click the submitter
-###      click_params set parameters for the how_click_mehtod
-###    
-              @as_form.submitter(:input, {:type => 'submit'})
-##form usage
-        let(:page_objects){
-          class GoogleAdvancedSearchPage < PageObjectWrapper::Page
-            attr_accessor :as_form
-            @url="/advanced_search"
-            expected_element :text_field, :name => 'as_q'
-            def initialize visit=false
-              super visit
-              @as_form = form(GoogleSearchPage, {:name => 'f'})
-              @as_form.editable(:text_field, {:name => 'as_q'}, :with_words, 'with_words default value', true)
-              @as_form.editable(:text_field, {:name => 'as_epq'}, :with_phrase, 'with_phrase default value', true)
-              @as_form.editable(:text_field, {:name => 'as_oq'}, :with_any_word, 'with_any_word default value', false)
-              @as_form.submitter(:input, {:type => 'submit'})
-            end
+          
+          select(:s1) do
+            locator :id => 'f10'
+            fresh_food 'one'
+            missing_food 'three'
           end
-          class GoogleSearchPage < PageObjectWrapper::Page
-            attr_accessor :find_form
-            @url="/"
-            expected_element :text_field, :name => 'q' # tells Watir that we expect this element which identifies the page in a uniq way
-            def initialize visit=false 
-              super visit
-              @find_form = form(GoogleSearchPage, {:action => '/search'}) 
-              @find_form.editable(:text_field, {:name => 'q'}, :search_what, '@find_form default value', true)                                   
-            end
+
+          select(:s2) do
+            locator :id => 'f11'
+            fresh_food 'one'
           end
-          {:gsearch_page_class => GoogleSearchPage, :gadv_page_class => GoogleAdvancedSearchPage}
-        }
-###has #submit(flag) method which submits form
-###      if flag = true than TargetPage instance is returned
-###      if flag = false than CurrentPage instance is returned
-###      if submitter is defined, than it's used to submit the form, otherwise standart Watir::Form submit is used
-###    
-          gadv_page = page_objects[:gadv_page_class].new(true)
-          gsearch_page = gadv_page.as_form.submit(true)
-          gsearch_page.should be_a(GoogleSearchPage)
-          gsearch_page_reloaded = gsearch_page.find_form.submit(false)
-          gsearch_page_reloaded.should be_a(GoogleSearchPage)
-###field's watir elements can be accessed by labels
-          gsearch_page = page_objects[:gsearch_page_class].new(true)
-          gsearch_page.find_form.search_what.should be_a(Watir::TextField)
-###fields default values set during form definition can be retrieved with #default(:label) method
-          gsearch_page = page_objects[:gsearch_page_class].new(true)
-          gsearch_page.find_form.default(:search_what).should eq('@find_form default value')
-###has #each method which allows navigating between form fields
-          gadv_page.as_form.each{|form_field|
-            form_field.should be_a(Editable)
-            form_field.watir_element.should be_a(Watir::TextField)
-###has #each_required method which allows navigating between form required fields
-          gadv_page.as_form.each_required{|form_field|
-            form_field.should be_a(Editable)
-            form_field.watir_element.should be_a(Watir::TextField)
-            form_field.should be_required
-          }
-###has #fill_only(:label => value) method which populated form's :label field with 'value'
-###      method returns form object
-###    
-          form = gadv_page.as_form.fill_only(:with_words => 'some value')
-          gadv_page.as_form.with_words.value.should eq('some value')
-###has #fill_all(:except => labels_array | label) method which populated all form's fields with default values
-###      if except_hash is not nil than provided fields are not populated
-###      method returns form object
-###    
-          form = gadv_page.as_form.fill_all
-          gadv_page.as_form.each{|field|
-            field.watir_element.value.should eq(gadv_page.as_form.default(field.label))
-          }
-###has #fill_required(:except => labels_array | label) method which populated all required form's fields with default values
-###      if except_hash is not nil than provided fields are not populated
-###      method returns form object
-###    
-          gadv_page.as_form.fill_required(:except => :with_words)
-          gadv_page.as_form.each_required{|field|
-            if field.label==:with_words
-              field.watir_element.value.should eq ''
-            else
-              field.watir_element.value.should eq(gadv_page.as_form.default(field.label))
-            end
-          }
-
-#Table wrapper
-      before :all do
-        PageObjectWrapper.domain = 'http://wiki.openqa.org'
+
+          checkbox(:cb){ locator :id => 'f5' }
+          radio(:rb){ locator :id => 'f3' }
+
+        end
+
+        action(:press_cool_button, :test_page_with_table) do
+          button(:name => 'foo').when_present.click
+        end
+
+        action(:fill_textarea, :some_test_page) do |fill_with|
+          data = (fill_with.empty?)? 'Default data' : fill_with
+          textarea(:id => 'f2').set data
+        end
+
+        table(:table_without_header) do
+          locator :summary => 'Each row names a Nordic country and specifies its total area and land area, in square kilometers'
+        end
+
+        table(:table_with_header) do
+          locator :summary => 'Each row names a Nordic country and specifies its total area and land area, in square kilometers'
+          header [:country, :total_area, :land_area]
+        end
+
+        pagination(:some_pagination) do
+          locator :xpath => ''
+        end
       end
-      let(:page_object){
-        class WatirPage < PageObjectWrapper::Page
-          attr_accessor :some_table
-          @url="/display/WTR/HTML+Elements+Supported+by+Watir"
-          expected_element :a, :text => 'HTML Elements Supported by Watir'
-          def initialize visit=false 
-            super visit
-            @some_table = table(:class => 'confluenceTable')
-          end
+
+here we have defined a page object with locator (url) = 'http://www.cs.tut.fi/~jkorpela/www/testel.html'  
+uniq\_xxx is used to define a uniq element on that page, which uniquely identifies the page from other pages  
+uniq\_xxx is being checked when openning the page with PageObjectWrapper.open\_page and when running an page\_object.action  
+
+#### openning the page
+*preconditions*  
+There is a directory, where we've defined a page\_object inside a \*\_page.rb file
+
+1. specify browser to be used by PageObjectWrapper  
+     @b = Watir::Browser.new  
+     PageObjectWrapper.use_browser @b  
+2. load defined pages  
+     PageObjectWrapper.load("path/to/pages/directory")  
+3. open page in browser  
+     test_page = PageObjectWrapper.open_page(:some_test_page)  
+
+*comments*
+- it's possible to use any Watir::Browser with any profile
+- it's possible to use any Webdriver, which behaves like Watir::Browser (meaning that Webdriver uses similar methods for locating elements and working with them)    
+- .load method validates all pages, defined in specified directory inside any \*\_page.rb file
+- it's possible to define several page objects in one file
+- .open\_page method takes page label, directs browser to that page and returns corresponding page\_object
+- PageObjectWrapper.current\_page points to the opened page\_object
+
+#### feed\_xxx
+*preconditions*  
+tp is a :some\_test\_page object opened in the browser
+
+    context "argument = :fresh_food" do
+      it "populates all xxx elements with :fresh_food" do
+        tp = PageObjectWrapper.current_page
+        tp.feed_test_elements(:fresh_food)
+      end
+    end
+
+    context "argument = nil" do
+      it "populates all xxx elements with :fresh_food" do
+        tp = PageObjectWrapper.current_page
+        tp.feed_test_elements
+      end
+    end
+
+    context "argument = :missing_food" do
+      it "populates all xxx elements with :missing_food" do
+        tp = PageObjectWrapper.open_page(:some_test_page)
+        tp.feed_test_elements(:missing_food)
+      end
+    end
+
+
+#### fire\_xxx
+*preconditions*  
+tp is a :some\_test\_page object opened in the browser
+
+    it "executes fire_block in Watir::Browser context" do
+      tp = PageObjectWrapper.open_page(:some_test_page)
+      tp.fire_fill_textarea
+    end
+
+    it "can be invoked with parameters" do
+      tp = PageObjectWrapper.current_page
+      tp.fire_fill_textarea('User defined data')
+    end
+
+    it "returns next_page" do
+      tp = PageObjectWrapper.current_page
+      np = tp.fire_press_cool_button
+    end
+
+#### select\_from\_xxx
+*preconditions*  
+tp is a :some\_test\_page object opened in the browser  
+its syntax is close to SQL *'select column1 from page\_object.some\_table where column2 = string\_or\_regexp'*     
+      page\_object.select\_from\_xxx( :column1, :column2 => 'string\_or\_regexp' )    
+correct arguments are:  
+:column1 is a column value from which you want to receive   
+:column2 is a column which is used to get specific row   
+
+    context "where == nil" do
+      it "returns last row value from provided column" do
+        tp.select_from_table_without_header(:column_0).text.should eq 'Sweden'
+        tp.select_from_table_without_header(:column_1).text.should eq '449,964'
+        tp.select_from_table_without_header(:column_2).text.should eq '410,928'
+      end
+    end
+
+    context "where not nil" do
+      context "found by String" do
+        it "returns found cells" do
+          tp.select_from_table_without_header(:column_0, :column_1 => '103,000').text.should eq 'Iceland'
+          tp.select_from_table_with_header(:country, :total_area => '337,030').text.should eq 'Finland'
+        end
+        it "returns nil" do
+          tp.select_from_table_without_header(:column_0, :column_1 => '123').should eq nil
+          tp.select_from_table_with_header(:country, :total_area => '123').should eq nil
         end
-        WatirPage
-      }
-##table definition
-     
-###has #table(how_find_hash) method to define a table on the page
-            @some_table = table(:class => 'confluenceTable')
-##table usage
-      before :all do
-        PageObjectWrapper.domain = 'http://wiki.openqa.org'
       end
-      let(:page_object){
-        class WatirPage < PageObjectWrapper::Page
-          attr_accessor :some_table
-          @url="/display/WTR/HTML+Elements+Supported+by+Watir"
-          expected_element :a, :text => 'HTML Elements Supported by Watir'
-          def initialize visit=false 
-            super visit
-            @some_table = table(:class => 'confluenceTable')
-          end
+      context "found by Regexp" do
+        it "returns found cells" do
+          tp.select_from_table_without_header(:column_0, :column_1 => /103/).text.should eq 'Iceland'
+          tp.select_from_table_with_header(:country, :total_area => /337/).text.should eq 'Finland'
         end
-        WatirPage
-      }
-###has #cells method which returns all Watir table cells
-          page = page_object.new(true)
-          page.some_table.cells.first.should be_a(Watir::TableCell)
-###has #has_cell?(text) method wich returns true if the table has a cell with specified text
-          page = page_object.new(true)
-          page.some_table.should have_cell('<td>')
-###has #select(column_name, where_hash) method wich returns cell inside specified column wich corresponds to a specified where_hash
-          page = page_object.new(true)
-          cell = page.some_table.select('HTML tag', :where => {'Watir method' => 'cell'})
-          cell.should be_a(Watir::TableCell)
-          cell.text.should eq '<td>'
-###is possible to specify just parts of column names in #select method
-          cell = page.some_table.select('HTML', :where => {'Watir met' => 'cell'})
-
-#Pagination wrapper
-
-##pagination definition
-
-###TODO
-    Needs to be reimplemented. Current realization is fo rails apps only
-##pagination usage
-
-###TODO
-    Needs to be reimplemented. Current realization is fo rails apps only
-
-#TestData class
-    	let(:user1){
-    "login: user1
-    email: user1@example.com
-    password: secret1
-    etc: other data"
-    	}
-    	let(:user2){
-    "login: user2
-    email: user2@example.com
-    password: secret2
-    etc: other data"
-    	}
-##is initialized with hash and generates dynamic attributes for an instance
-    		dynamically_defined_user = PageObjectWrapper::TestData.new(YAML.load(user1))
-    		dynamically_defined_user.login.should eq 'user1'
-    		dynamically_defined_user.email.should eq 'user1@example.com'
-    		dynamically_defined_user.password.should eq 'secret1'
-    		dynamically_defined_user.etc.should eq 'other data'
-##has .find method which allows finding dynamically defined objects
-    		dynamically_defined_user1 = PageObjectWrapper::TestData.new(YAML.load(user1))
-    		dynamically_defined_user2 = PageObjectWrapper::TestData.new(YAML.load(user2))
-    		user1 = PageObjectWrapper::TestData.find(:login,'user1')
-    		user1.email.should eq 'user1@example.com'
-##has .each method which allows navigating between objects
-    		dynamically_defined_user1 = PageObjectWrapper::TestData.new(YAML.load(user1))
-    		dynamically_defined_user2 = PageObjectWrapper::TestData.new(YAML.load(user2))
-    		PageObjectWrapper::TestData.each{|user|
-    			user.etc.should eq 'other data'
-    		}
-
+        it "returns nil" do
+          tp.select_from_table_without_header(:column_0, :column_1 => /123/).should eq nil
+          tp.select_from_table_with_header(:country, :total_area => /123/).should eq nil
+        end
+      end
+    end
 
+#### each\_xxx
+TODO
+#### open\_xxx
+TODO
 ## Contributing
 
 1. Fork it
@@ -374,7 +214,7 @@ Or install it yourself as:
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
-page_object_wrapper
+page\_object\_wrapper
 ===================
 
 Wraps watir-webdriver with convenient testing interface, based on PageObjects automation testing pattern. Simplifies resulting automated test understanding.