page_magic 1.0.0.alpha21 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 115f37789b407f0f922654cec028ab74268132c4
-  data.tar.gz: ad52bf172b7e0ebd649f738c86e418c47c57a70f
+  metadata.gz: 72362e511bc0f363179017fa7363ce20995b28b1
+  data.tar.gz: a7c4b1ba4c85213592217702bedcb0f76080da8e
 SHA512:
-  metadata.gz: 1a3d128c9dbf70e10c7aae8ddef2c48603714b625634639b8b559af1870655a114c9f706447add67e906ed4cd087e905dc827492798b8b71166455e1cade255b
-  data.tar.gz: 6428d9dc270bc4768556e102a68bf0014817c05e3c947e467fc7cad3868b3cf7ad0007cf34a16cab24fc9cb8d23502192509103d6ca9799efe4f8c514c352337
+  metadata.gz: 6c5646258cadec859bfa0923db62334d055ba0ede606d6f62c05e73b21524832a0b4da4be9be2f6dc20f5be47e2c041cf3a1224693b7549ec6db91e45fa9041d
+  data.tar.gz: 6a82e9164bdb65b49cb892ea83f67334ae512b91305974329fa041bf884c63d0145dfde2ac503de133d12c51a8504b85e82d3ce06d851764763bda6631a5d6b5

data/.rubocop.yml

@@ -9,4 +9,7 @@ AllCops:
     - '.idea/**/*'
 
 Metrics/ParameterLists:
-  CountKeywordArgs: false
+  CountKeywordArgs: false
+
+Metrics/MethodLength:
+  Max: 11

data/Gemfile

@@ -1,6 +1,6 @@
 source 'https://rubygems.org'
 
-gem 'capybara', '~> 2'
+gem 'capybara', '2.5.0'
 gem 'activesupport', '~> 4'
 gem 'wait', '~> 0'
 

data/Gemfile.lock

@@ -12,7 +12,7 @@ GEM
     astrolabe (1.3.1)
       parser (~> 2.2)
     builder (3.2.2)
-    capybara (2.1.0)
+    capybara (2.5.0)
       mime-types (>= 1.16)
       nokogiri (>= 1.3.3)
       rack (>= 1.0.0)
@@ -21,7 +21,7 @@ GEM
     certifi (2015.08.10)
     childprocess (0.3.9)
       ffi (~> 1.0, >= 1.0.11)
-    cliver (0.2.2)
+    cliver (0.3.2)
     codeclimate-test-reporter (0.4.8)
       simplecov (>= 0.7.1, < 1.0.0)
     diff-lcs (1.2.5)
@@ -69,9 +69,9 @@ GEM
       rack (~> 1.2)
     parser (2.2.3.0)
       ast (>= 1.1, < 3.0)
-    poltergeist (1.4.1)
-      capybara (~> 2.1.0)
-      cliver (~> 0.2.1)
+    poltergeist (1.7.0)
+      capybara (~> 2.1)
+      cliver (~> 0.3.1)
       multi_json (~> 1.0)
       websocket-driver (>= 0.2.0)
     powerpack (0.1.1)
@@ -131,7 +131,9 @@ GEM
     watir-webdriver (0.6.4)
       selenium-webdriver (>= 2.18.0)
     websocket (1.0.7)
-    websocket-driver (0.3.0)
+    websocket-driver (0.6.3)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.2)
     xpath (2.0.0)
       nokogiri (~> 1.3)
     yard (0.8.7.6)
@@ -141,7 +143,7 @@ PLATFORMS
 
 DEPENDENCIES
   activesupport (~> 4)
-  capybara (~> 2)
+  capybara (= 2.5.0)
   codeclimate-test-reporter
   github-markup (~> 1.4)
   jeweler (~> 2.0)

data/README.md

@@ -5,51 +5,40 @@ PageMagic is an API for testing web applications.
 It has a simple but powerful DSL which makes modelling and interacting with your pages easy.
 
 Wouldn't it be great if there was a framework that could:
-- [Model your pages](#modelling-pages)
-- [Fluently define interaction hooks / waiters on page elements](#interaction-hooks)
+- [Model your pages](#defining-pages)
+- [Fluently define event hooks / waiters on page elements](#hooks)
 - [Map paths to pages so that the correct page object is loaded as you navigate](#page-mapping)
 - [Be super dynamic](#dynamic-selectors)
 
 Well PageMagic might just be the answer!
 
 Give it a try and let us know what you think! There will undoubtedly be things that can be improved and issues that we are not aware of so your feedback/pull requests are greatly appreciated!
+# Contents
+- [Installation](#installation)
+- [Starting a session](#starting-a-session)
+- [Defining Pages](#defining-pages)
+  - [Elements](#elements)
+    - [Interacting with elements](#interacting-with-elements)
+      -  [Multple Results](#multiple-results)
+    - [Sub elements](#sub-elements)
+    - [Custom elements](#custom-elements)
+  - [Hooks](#hooks)
+    - [Element event hooks](#element-event-hooks)
+    - [On load hook](#on-load-hook)
+  - [Helper Methods](#helper-methods)
+  - [Dynamic Selectors](#dynamic-selectors)
+- [Watchers](#watchers)
+  - [Method watchers](#method-watchers)
+  - [Simple watchers](#simple-watchers)
+  - [Custom watchers](#custom-watchers)
+- [Page mapping](#page-mapping)
+- [Drivers](#drivers)
+- [Pulling it all together](#pulling-it-all-together)
 
 # Installation
 `gem install page_magic --pre`
 
-# An Example
-Imagine the scene. You've written a web based mail client and now you want to test it...
-You have a scenario in mind that goes something along the lines of:
-- Send yourself an email with a unique subject
-- Go to the Login page and login
-- Find the message using it's unique subject and read it
-- delete the message
-
-You're mail client is total 21st century so there is loads of lovely ajax etc...
-
-Writing robust, nice looking code for this could be a real pain... 
-Here's how you might do it with PageMagic (note that the following code would work if we you had a compatible mail web app but in this case is purely illustrative)
-
-What we really want to write is something like
-```ruby
-test_subject = send_test_mail('test@21st-century-mail.com')
-#Visit your site using a PageMagic session we prepared earlier
-session.visit(LoginPage)
-
-#Login using some handy helper method on our page object
-session.login('username', 'password')
-
-#Find the message amongst all the other messages that are on screen and read it
-session.message(subject: test_subject).read.click
-
-#Now we are on the message screen lets delete it without having to worry about the ajax.
-session.delete_message
-
-fail "message is still there!" if session.message(subject: test_subject).exists?
-
-# Sweet :)
-```
-## Starting a session
+# Starting a session
 To start a PageMagic session simply decide what browser you want to use and pass it to PageMagic's `.session` method
 ```ruby
 session = PageMagic.session(browser: :chrome, url: 'https://21st-century-mail.com')
@@ -63,8 +52,15 @@ Under the hood, PageMagic is using [Capybara](https://github.com/jnicklas/capyba
 
 **Note:** We don't want to impose particular driver versions so PageMagic does not list any as dependencies. Therefore you will need add the requiste gem to your Gemfile.
 
-## Modeling pages
-To define something that PageMagic can work with, simply include PageMagic in to a class. Your you will also want to model the elements on your page so that you can interact with them. Here are we are modelling the login page we would need for the example above
+# Defining Pages
+To define something that PageMagic can work with, simply include PageMagic in to a class.
+```ruby
+class LoginPage
+  include PageMagic
+end
+```
+## Elements
+Defining elements is easy see the example below.
 
 ```ruby
 class LoginPage
@@ -74,10 +70,9 @@ class LoginPage
   button(:login_button, text: 'login')
 end
 ```
-In the case of the Login page, it's easy to imagine that it will have text fields for a username and password and a button to login in with.
 
-##Interacting with elements
-Elements are defined with a id which is the name of the method you will use to reference it. In the above example, the textfields and button were defined with the id's, `:username`, `:password`, and `:login_button`
+### Interacting with elements
+Elements are defined with an id which is the name of the method you will use to reference it. In the above example, the textfields and button were defined with the id's, `:username`, `:password`, and `:login_button`
 
 After visiting a page with a PageMagic session, you can access all of the elements of that page through the session itself.
 ```ruby
@@ -85,24 +80,67 @@ session.username.set 'joe@blogs.com'
 session.password.set 'passw0rd'
 session.login_button.click
 ```
-
-## Defining Pages
-To define something that PageMagic can work with, simply include PageMagic in to a class. Here are the classes we would need for the example above.
+#### Multple Results
+Where an element has been scoped to return multple results, these will be returned in an array. These elements can be defined
+using all of the same features as described in this readme and behave in exactly the same way.
 ```ruby
 class LoginPage
-  include PageMagic
+  element :links, css: 'a'
 end
 
+session.link => Array<Element> 
+```
+
+### Sub Elements
+If your pages are complex you can use PageMagic to compose pages, their elements and subelements to as many levels as you need to.
+
+```ruby
 class MailBox
   include PageMagic
+  
+  element :message, id: 'message_id' do
+    link(:read, text: 'read')
+  end
+end
+```
+Sub elements can be accessed through their parent elements e.g:
+```
+session.message.read.click
+```
+
+### Custom elements
+PageMagic allows you to define your own custom elements.
+```ruby
+class Nav < PageMagic::Element
+  selector css: '.nav
+  
+  element :options, css: '.options' do
+    link(:link1, id: 'link1')
+    link(:link2, id: 'link2')
+    link(:link3, id: 'link3')
+  end
 end
 
-class MessageView
+class MyPage 
   include PageMagic
+  element Nav
 end
 ```
-### Hooks
-PageMagic lets you define an on_load hook for your pages. This lets you right any custom wait logic you might need 
+If an id is not specified then the name of the element class will be used. The selector for the element can be specified on the class itself or overiden when defining the element on the page. The custom element can also be extended as with other elements.
+```ruby
+class MyPage
+  include PageMagic
+  element Nav, :navigation, selector: '.custom' do
+    link(:extr_link, id: 'extra-link')
+  do
+end
+```
+
+## Hooks
+PageMagic provides hooks to allow you to interact at the right moments with your pages
+
+### On load hook
+PageMagic lets you define an on_load hook for your pages. This lets you write any custom wait logic you might need 
 before letting execution continue.
 ```ruby
 class LoginPage
@@ -114,10 +152,25 @@ class LoginPage
 end
 ```
 
-### Helper methods
+### Element event hooks
+Frequently, you are going to have to work with pages that make heavy use of ajax. This means that just because you've clicked something, it doesn't mean that the action is finished. For these occasions PageMagic provides `before_events` and `after_events` hooks that you use to perform custom actions and wait for things to happen.
+
+```ruby
+class MessagePage
+  include PageMagic
+  ## code defining other elements, such as subject and body
+  
+  link(:delete id: 'delete-message') do
+    after_events do
+      wait_until{fancy_animation_has_disappeared?}
+    end
+  end
+end
+```
+
+## Helper methods
 Using elements that are defined on a page is great, but if you are enacting a procedure through interacting with a few of them then your code could end up with some pretty repetitive code. In this case you can define helper methods instead. 
 
-In the above [example](#an example) we used a helper called `login`.
 ```ruby
 class LoginPage
   # ... code defining elements as shown above
@@ -134,25 +187,9 @@ We can interact with helper in the same way as we did page elements.
 ```ruby
 session.login('joe', 'blogs')
 ```
-##Defining sub elements
-If your pages are complex you can use PageMagic to compose pages, their elements and subelements to as many levels as you need to.
 
-In the example we accessed a read link that resided with a particular message
-```ruby
-class MailBox
-  include PageMagic
-  
-  element :message, id: 'message_id' do
-    link(:read, text: 'read')
-  end
-end
-```
-Sub elements can be accessed through their parent elements e.g:
-```
-session.message.read.click
-```
 ## Dynamic Selectors
-In our scenario we actually selected a message based on a subject that was randomly generated. In this case we would not be able to hard code the selector for our message but instead would need to set the selector dynamically.
+In some cases you will able to specify the selector for an element until runtime. PageMagic allows you to handle such situations with support for dynamic selectors.
 
 ```ruby
 class MailBox
@@ -168,23 +205,60 @@ Here we have defined the 'message' element using a block that takes subject argu
 ```ruby
 session.message(subject: 'test message')
 ```
-## Interaction hooks
-Frequently, you are going to have to work with pages that make heavy use of ajax. This means that just because you've clicked something, it doesn't mean that the action is finished. For these occasions PageMagic provides `before_events` and `after_events` hooks that you use to perform custom actions and wait for things to happen. In the case of our web based mail client, we could imagine that when deleting the email, a fancy spinner is displayed whilst the application sends an ajax request to have the message deleted. In this case we wouldn't want to proceed until this has disappeared.
 
+# Watchers
+PageMagic lets you set a watcher on any of the elements that you have defined on your pages. Use watchers to decide when
+things have changed. 
+
+**Note**: Watchers are not inherited
+
+## Method watchers
+Method watchers watch the output of the given method name.
 ```ruby
-class MessagePage
-  include PageMagic
-  ## code defining other elements, such as subject and body
+button :javascript_button, css: '.fancy_button' do
+  before_events do
+    watch(:url)
+  end
   
-  link(:delete id: 'delete-message') do
-    after_events do
-      wait_until{fancy_animation_has_disappeared?}
+  after_events do
+    wait_until{changed?(:url)}
+  end
+end
+```
+
+## Simple watchers
+Simple watchers use the `watch` method passing two parameters, the first is the name of the element you want to keep an 
+eye and the second is the method that needs to be called to get the value that should be observed.
+```ruby
+element :product_row, css '.cta' do
+  before_events do
+    element(:total, css: '.total')
+  end
+  
+  after_events do
+    wait_until{changed?(:total)}
+  end
+end
+```
+## Custom watchers
+Custom watchers are defined by passing a name and block parameter to the `watch` method. The block returns the value 
+that needs to be observed. Use watch in this way if you need to do something non standard to obtain a value or to 
+access an element not located within the current element but elsewhere within the page.
+```ruby
+element :product_row, css '.cta' do
+  before_events do
+    element(:total) do
+      session.nav.total.text
     end
   end
+  
+  after_events do
+    wait_until{changed?(:total)}
+  end
 end
 ```
-## Page Mapping
-You will have noticed that, that we have been performing actions that would move us from page to page but have not done anything to tell PageMagic to use the `MailBox` or `MessagePage`. With PageMagic you can map which pages should be used to handle which URL paths. This is a pretty killer feature that will remove a lot of the juggling and bring back fluency to your code!
+# Page mapping
+With PageMagic you can map which pages should be used to handle which URL paths. This is a pretty killer feature that will remove a lot of the juggling and bring back fluency to your code!
 ```ruby
 # define what pages map to what
 browser.define_page_mappings %r{/messages/\d+} => MessagePage,
@@ -193,6 +267,7 @@ browser.define_page_mappings %r{/messages/\d+} => MessagePage,
 ```
 You can use even use regular expressions to map multiple paths to the same page. In the above example we are mapping paths that that starts with '/messages/' and are followed by one ore more digits to the `MessagePage` class.
 
+# Drivers
 ## Registering a custom driver
 You can register any Capybara compliant driver as follows
 
@@ -211,6 +286,34 @@ PageMagic.drivers.register Webkit
 #3. Use registered driver
 session = PageMagic.session(browser: webkit, url: 'https://21st-century-mail.com')
 ```
-##What else can you do with PageMagic?
-PageMagic has lots of other useful features. I'm writing up the documentation so check back here soon!
 
+# Pulling it all together
+Imagine the scene. You've written a web based mail client and now you want to test it...
+You have a scenario in mind that goes something along the lines of:
+- Send yourself an email with a unique subject
+- Go to the Login page and login
+- Find the message using it's unique subject and read it
+- delete the message
+
+You're mail client is totally 21st century so there is loads of lovely ajax etc...
+
+Using the PageMagic you can implement an API that might look something like the following to use:
+
+```ruby
+test_subject = send_test_mail('test@21st-century-mail.com')
+#Visit your site using a PageMagic session we prepared earlier
+session.visit(LoginPage)
+
+#Login using some handy helper method on our page object
+session.login('username', 'password')
+
+#Find the message amongst all the other messages that are on screen and read it
+session.message(subject: test_subject).read.click
+
+#Now we are on the message screen lets delete it without having to worry about the ajax.
+session.delete_message
+
+fail "message is still there!" if session.message(subject: test_subject).exists?
+
+# Sweet :)
+```

data/VERSION

@@ -1 +1 @@
-1.0.0.alpha21
+1.0.0

data/lib/page_magic/class_methods.rb

@@ -1,15 +1,9 @@
 module PageMagic
   # module ClassMethods - contains class level methods for PageObjects
   module ClassMethods
+    # Default block to be run when a page is loaded. This is used if a specific handler is not registered
     DEFAULT_ON_LOAD = proc {}
 
-    # getter setter for storing the page url
-    # @param [String] url the url of the page
-    def url(url = nil)
-      @url = url if url
-      @url
-    end
-
     # sets block to run when page has loaded
     # if one has not been set on the page object class it will return a default block that does nothing
     def on_load(&block)
@@ -17,6 +11,13 @@ module PageMagic
       @on_load = block
     end
 
+    # getter setter for storing the page url
+    # @param [String] url the url of the page
+    def url(url = nil)
+      @url = url if url
+      @url
+    end
+
     # Visit this page based on the class level registered url
     # @param [Object] application rack application (optional)
     # @param [Symbol] browser name of browser

data/lib/page_magic/driver.rb

@@ -20,13 +20,6 @@ module PageMagic
       @supported_browsers = supported_browsers
     end
 
-    # Determines if the given browser name is supported by this driver definition
-    # @param [Symbol] browser name of browser
-    # @return [Boolean] true if definition supports the given driver name
-    def support?(browser)
-      supported_browsers.include?(browser)
-    end
-
     # Build a new driver instance based on this definition
     # @param [Object] app - rack compatible application
     # @param [Symbol] browser name of required browser
@@ -35,5 +28,12 @@ module PageMagic
     def build(app, browser:, options:{})
       handler.call(app, options, browser)
     end
+
+    # Determines if the given browser name is supported by this driver definition
+    # @param [Symbol] browser name of browser
+    # @return [Boolean] true if definition supports the given driver name
+    def support?(browser)
+      supported_browsers.include?(browser)
+    end
   end
 end

data/lib/page_magic/drivers.rb

@@ -7,12 +7,6 @@ module PageMagic
       @all ||= []
     end
 
-    # Make a driver available for selection when creating calling {PageMagic.session}
-    # @param [Driver] driver driver definition
-    def register(driver)
-      all << driver
-    end
-
     # Find a driver definition based on its registered name
     # @param [Symbol] browser registered name of the required browser
     def find(browser)
@@ -31,6 +25,12 @@ module PageMagic
       end
     end
 
+    # Make a driver available for selection when creating calling {PageMagic.session}
+    # @param [Driver] driver driver definition
+    def register(driver)
+      all << driver
+    end
+
     # returns true if this driver instance is equal to the supplied object
     # @param [Object] other subject of equality check
     # @return [Boolean] true if the object is a match

data/lib/page_magic/element/locators.rb

@@ -0,0 +1,24 @@
+module PageMagic
+  class Element
+    # contains method for finding element definitions
+    module Locators
+      # message used when raising {ElementMissingException} from methods within this module
+      ELEMENT_NOT_DEFINED_MSG = 'Element not defined: %s'
+
+      # find an element definition based on its name
+      # @param [Symbol] name name of the element
+      # @return [Element] element definition with the given name
+      # @raise [ElementMissingException] raised when element with the given name is not found
+      def element_by_name(name, *args)
+        defintion = element_definitions[name]
+        fail ElementMissingException, (ELEMENT_NOT_DEFINED_MSG % name) unless defintion
+        defintion.call(*args.append(self))
+      end
+
+      # @return [Array] class level defined element definitions
+      def element_definitions
+        self.class.element_definitions
+      end
+    end
+  end
+end

data/lib/page_magic/element/query.rb

@@ -1,3 +1,4 @@
+require 'capybara/query'
 module PageMagic
   class Element
     # class Query - models overall queries for Capybara, queries can include:

data/lib/page_magic/element/selector.rb

@@ -14,6 +14,15 @@ module PageMagic
         end
       end
 
+      attr_reader :name, :formatter, :exact, :supports_type
+
+      def initialize(selector = nil, supports_type: false, exact: false, &formatter)
+        @name = selector
+        @formatter = formatter || proc { |arg| arg }
+        @supports_type = supports_type
+        @exact = exact
+      end
+
       # Build selector query parameters for Capybara's find method
       # @param [Symbol] element_type the type of browser element being found. e.g :link
       # @param [Hash] locator the selection method and its parameter. E.g. text: 'click me'
@@ -22,20 +31,13 @@ module PageMagic
           array << element_type if supports_type
           array << name if name
           array << formatter.call(locator)
+          array << { exact: true } if exact
         end
       end
 
-      attr_reader :name, :formatter, :supports_type
-
-      def initialize(selector = nil, supports_type: false, &formatter)
-        @name = selector
-        @formatter = formatter || proc { |arg| arg }
-        @supports_type = supports_type
-      end
-
       XPATH = Selector.new(:xpath, supports_type: false)
       ID = Selector.new(:id, supports_type: false)
-      LABEL = Selector.new(:field, supports_type: false)
+      LABEL = Selector.new(:field, supports_type: false, exact: true)
 
       CSS = Selector.new(supports_type: false)
       TEXT = Selector.new(supports_type: true)