page_record 0.0.1

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.gitignore

@@ -0,0 +1,5 @@
+/coverage/
+/doc/
+/.yardoc/
+/pkg/
+*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  # - jruby-19mode
+  - rbx-19mode
+script: bundle exec rspec spec
+# matrix:
+#   allow_failures:
+#     -rvm: jruby-19mode

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private
+--markup markdown

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in page_record.gemspec
+gemspec
+gem 'coveralls', require: false

data/Gemfile.lock

@@ -0,0 +1,72 @@
+PATH
+  remote: .
+  specs:
+    page_record (0.0.1)
+      activesupport
+      capybara (~> 2.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (3.2.13)
+      i18n (= 0.6.1)
+      multi_json (~> 1.0)
+    capybara (2.1.0)
+      mime-types (>= 1.16)
+      nokogiri (>= 1.3.3)
+      rack (>= 1.0.0)
+      rack-test (>= 0.5.4)
+      xpath (~> 2.0)
+    colorize (0.5.8)
+    coveralls (0.6.7)
+      colorize
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      thor
+    diff-lcs (1.2.4)
+    i18n (0.6.1)
+    mime-types (1.23)
+    mini_portile (0.5.0)
+    multi_json (1.7.7)
+    nokogiri (1.6.0)
+      mini_portile (~> 0.5.0)
+    rack (1.5.2)
+    rack-protection (1.5.0)
+      rack
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rake (10.0.4)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    sinatra (1.3.6)
+      rack (~> 1.4)
+      rack-protection (~> 1.3)
+      tilt (~> 1.3, >= 1.3.3)
+    thor (0.18.1)
+    tilt (1.4.1)
+    xpath (2.0.0)
+      nokogiri (~> 1.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  coveralls
+  page_record!
+  rake
+  rspec
+  sinatra

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Bert Hajee
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,210 @@
+[![Code Climate](https://codeclimate.com/github/appdrones/page_record.png)](https://codeclimate.com/github/appdrones/page_record) [![Build Status](https://travis-ci.org/appdrones/page_record.png)](https://travis-ci.org/appdrones/page_record) [![Dependency Status](https://gemnasium.com/appdrones/page_record.png)](https://gemnasium.com/appdrones/page_record) [![Coverage Status](https://coveralls.io/repos/appdrones/page_record/badge.png)](https://coveralls.io/r/appdrones/page_record)
+
+# PageRecord
+
+You've probably been there. You're building your killer Web Application. You, being a responsible developer, your code is thoroughly tested. You are using the likes of cucumber and Rspec to do so. Besides your unit-tests, you also have integration tests doing a full stack test. You are using Capybara to read, parse and test the rendered pages. You use all kinds of selectors to select different parts of the page. Slowly but surely your test code becomes less and less readable.
+
+## PageRecord can help.
+There are a lot of ways you can do this. PageRecord is one of these ways. PageRecord is an ActiveRecord like abstraction for information on the HTML page. You can use `TeamRecord.find(1)` and `TeamRecord.find_by_name('Barcelona')` like functions to find a record on an HTML page. When you've found the record you need, you can use easy accessors to access the attributes. `TeamRecord.find(1).name` returns the name of the team.
+
+TODO explain how it helps in testing
+
+##Documentation
+Look at {http://rubydoc.info/github/appdrones/page_record the yard documentation} for details.
+
+##Markup
+For {PageRecord} to recognise the data on the page, the page __must__ follow certain `html` formatting guidelines.
+
+__Every__ record on the page __must__ have a `data-type-id='x'` attribute. 
+
+```html
+<tag data-type-id='x'>
+...
+<tag>
+```
+Where `1` is the `id` of the record and `type` is the type of record. See {PageRecord::PageRecord.type} for infrmation regarding the `type`.
+
+__Every__ attribute of a record, __must__ have a `data-attribute-for='name'` attribute. This tag __must__ be contained inside a tag contaning the `data-type-id='x'` 
+
+```html
+<tag data-team-id='1'>
+  <tag data-attribute-for='attr'>Ajax</tag>
+...
+<tag>
+```
+
+Where `attr` is the name of the attribute.
+
+##attributes
+
+###reading the attributes
+With {PageRecord}, you can easily access the attributes of a record on the page. After you've got a valid instance of {PageRecord::PageRecord}, you can access all attributes in a normal ruby-like way.
+
+```ruby
+  champion = TeamPage.find(1)
+  expect(champion.name).to eq('Ajax')
+```
+###setting the attributes
+Not only can you access the attributes for reading, you can also set the attributes. This only works if the attribute is modifiable, like in an `INPUT` or a `TEXTFIELD` tag.
+
+```ruby
+  champion = TeamPage.find(1)
+  champion.name = 'Ajax'
+```
+
+###specifying the attributes
+When you define you page class as a subclass of {PageRecord::PageRecord}, it automagicaly looks for a host class. To get the name of your host class, PageRecord removes the `Page` part of you class name and tries to use that class as a host class.
+
+Example:
+
+```ruby
+class TeamPage < PageRecord::PageRecord
+end
+```
+
+will result in a host class of `Team`
+
+####what is the host class
+The host class is a class who's attributes are mirrored by PageRecord. At this point in time PageRecord only has support for `ActiveRecord` host classes. To be more specific: To be used as a host class, the class must support the method `attribute_names` to return an {::Array} of {::String} of {::Symbol}.
+
+Example:
+
+Given the following host class and PageRecord class
+
+```ruby
+class Team < ActiveRecord::Base
+# The database defines the following records
+# name, position, points
+#
+end
+
+class TeamPage < PageRecord::PageRecord
+end
+```
+
+Then a record from the TeamPage responds to the attributes: `name`, `position`, `points`
+
+##actions
+PageRecord support record actions and page actions. 
+
+###record actions
+A record action is an action that is found within a `data-type-id=` tag. To define an action, you can use the `data-action-for='create'` tag.
+
+An example:
+
+```html
+<form data-team-id='1'>
+  Name: <input data-attribute-for='name'>
+  Position: <input data-attribute-for='position'>
+  <button data-action-for='save'>Create</button>
+</form>
+```
+
+with this markup on your page, you can use the following ruby code:
+
+```ruby
+team = TeamPage.find(1)
+team.name = 'Ajax'
+team.position = 1
+team.save
+```
+
+When you call an action method, PageRecord automagicaly clicks the specified HTML element.
+
+Sometimes you don't want to click the element. PageRecord supports this by calling the action routine with a `?`. This returns the {http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Result Capybara Result}. You can do with this element whatever you can do with this element what you want.
+
+```ruby
+TeamPage.save?
+```
+
+###page actions
+Sometimes you need to have an action that is not related to a record. An example is the creation of a new record. But in fact, any `data-action-for` tag, outside of a record, can be called as a page action.
+
+An example:
+
+```html
+<form data-team-id='1'>
+  Name: <input data-attribute-for='name'>
+  Position: <input data-attribute-for='position'>
+  <button data-action-for='save'>
+</form>
+<button data-action-for='create'>New Team</button>
+```
+
+```ruby
+TeamPage.create
+```
+
+When you call an action method, PageRecord automagicaly clicks the specfied HTML element.
+
+Sometimes you don't want to click the element. PageRecord supports this by calling the action routine with a `?`. This returns the Capybara Element. You can do with this element whatever you can do with this element what you want.
+
+```ruby
+TeamPage.save?
+```
+
+##Using PageRecord together with Rspec
+To use {PageRecord} with Rspec, you need to require it in your `spec_helper.rb` file. To make it work, it needs to be required __after__ capybara.
+
+```ruby
+require 'capybara'
+require 'page_record/rspec'
+```
+
+Also, you need te make sure your page definitions are included. A good place to store them would be in your support directory.
+
+##Using PageRecord together with Cucumber
+To use {PageRecord} with Cucumber, you need to require it in your `env.rb` file. To make it work, it needs to be required __after__ capybara.
+
+```ruby
+require 'capybara'
+require 'page_record/cucumber'
+```
+Also, you need te make sure your page definitions are included. A good place to store them would be in your support directory.
+
+##Using PageRecord standalone
+If you are using {PageRecord} outside of Rspec or Cucumber, you also need to require the right files.
+
+```ruby
+require 'capybara'
+require 'page_record/rspec'
+```
+
+You also need te make sure, you set the page variable before you start.
+
+```ruby
+PageRecord::PageRecord.page = session
+```
+
+Also, you need te make sure your page definitions are included. 
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'page_record', :require => false
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install page_record
+
+## Usage
+
+TODO explain how to use it
+
+## Example
+
+TODO show an example
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+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

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/page_record/attribute_accessors.rb

@@ -0,0 +1,60 @@
+module PageRecord
+	class PageRecord
+		##
+		# Searches the record for the specified attribute and returns the {http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Result Capybara Result}.
+		# This method is called when you access an attribute with a `?` of a record
+		# 
+		# @return [Capybara::Result] the text content of the specified attribute
+		#
+		# @raise [AttributeNotFound] when the attribute is not found in the record
+		#
+		def read_attribute?(attribute)
+			begin
+				@record.find("[data-attribute-for='#{attribute}']")
+			rescue Capybara::ElementNotFound
+				raise AttributeNotFound, "#{@type} record with id #{@id} doesn't contain attribute #{attribute}"
+			end
+		end
+
+		##
+		# Searches the record for the specified attribute and returns the text content.
+		# This method is called when you access an attribute of a record
+		# 
+		# @return [String] the text content of the specified attribute
+		#
+		# @raise [AttributeNotFound] when the attribute is not found in the record
+		#
+		def read_attribute( attribute)
+			element = self.send("#{attribute}?")
+			tag = element.tag_name
+			textelement?(tag) ? element.value : element.text
+		end
+
+		##
+		# Searches the record for the specified attribute and sets the value of the attribute
+		# This method is called when you set an attribute of a record
+		# 
+		# @return [Capybara::Result] the text content of the specified attribute
+		#
+		# @raise [AttributeNotFound] when the attribute is not found in the record
+		# @raise [NotInputField] when the attribute is not a `TEXTAREA` or `INPUT` tag
+		#
+		def write_attribute( attribute, value)
+			element = self.send("#{attribute}?")
+			tag = element.tag_name
+			raise NotInputField unless textelement?(tag)
+			element.set(value)
+			element
+		end
+
+
+private
+		# @private
+		def textelement?(tag)
+			case tag
+			when 'textarea', 'input' then true
+			else false
+			end
+		end
+	end
+end

data/lib/page_record/class_actions.rb

@@ -0,0 +1,55 @@
+module PageRecord
+	class PageRecord
+		##
+		#
+		# This is the implementation of the page action routine. It has two variants.
+		# it has a `?` variant and a `normal` variant.
+		#
+		# normal variant:
+		# It checks the page for a data-action-for='action' tag somewhere on the page.
+		# If it finds it, it clicks it.
+		#
+		# `?` variant:
+		# It checks the page for a data-action-for='action' tag somewhere on the page.
+		# If it finds it, returns the Capybara result.
+		#
+		# @param action [Symbol] this is the name of the action
+		# 
+		# @return [Capybara::Element]
+		#
+		# @raise [PageRecord::MultipleRecords] when there are more actions with 
+		#   this name on the page
+		#
+		def self.method_missing(action)
+			raw_action = /(.*)\?/.match(action)
+			begin
+				if raw_action
+					action_for?(raw_action[1])
+				else
+					action_for(action)
+				end
+			rescue Capybara::Ambiguous
+				raise MultipleRecords, "Found multiple #{action} tags for #{@type} on page"				
+			rescue Capybara::ElementNotFound
+				super
+			end
+		end
+
+private
+
+		# @private
+		def self.action_for(action)
+			element = action_for?(action)
+			element.click
+			element
+		end
+
+
+		# @private
+		def self.action_for?(action)
+			page.find("[data-action-for='#{action}']")
+		end
+	end
+end
+
+

data/lib/page_record/class_methods.rb

@@ -0,0 +1,214 @@
+module PageRecord
+	class PageRecord
+
+		# @private
+		def self.inherited(base)
+			base.class_eval do
+				set_type_name(base)
+				get_attribute_names
+			end
+			define_class_methods(base)
+			define_instance_methods(base)
+		end
+
+
+		##
+		# Set's the page {PageRecord::PageRecord} uses for all page operations
+		#
+		# @param new_page [Cabybara::Session] The Capybara page	
+		#
+		# @return [Capybara::Session]
+		#
+		def self.page=(new_page)
+			@@page = new_page
+		end
+
+		##
+		# Returns the page page {PageRecord::PageRecord} uses for all page operations
+		#
+		# @return [Capybara::Session]
+		#
+	  def self.page
+	  	@@page
+	  end
+
+		##
+		# Set's the default selector for this class 
+		#
+		# Example:
+		#
+		# ```ruby
+		# class TeamPage < PageRecord::PageRecord
+		#   selector "#first-table" 
+		# end
+		#```
+		# @param new_selector [String] The default selector to be used for all finders	
+		#
+	  def self.selector( new_selector)
+	  	@selector = new_selector
+	  end
+
+		##
+		# Set's the default filter for this class 
+		#
+		#
+		# Example:
+		#
+		# ```ruby
+		# class TeamPage < PageRecord::PageRecord
+		#   filter ".champions-league" 
+		# end
+		#```
+		#
+		# @param new_filter [String] The default filter to be used for all finders	
+		#
+	  def self.filter( new_filter)
+	  	@filter = new_filter
+	  end
+
+		##
+		# Set's the default type for this class 
+		#
+		# @param new_type [Symbol] The default type to be used for all finders	
+		#
+		# Example:
+		#
+		# ```ruby
+		# class TopDivisonPage < PageRecord::PageRecord
+		#   type :team
+		# end
+		#```
+		#
+		#
+	  def self.type( new_type)
+	  	@type = new_type
+	  end
+
+
+		##
+		# Set's the attributes this page recognises. This will override any types 
+		# inherited from the host class 
+		#
+		# @param new_attributes [Array] The attributes the page regognises	
+		#
+		# Example:
+		#
+		# ```ruby
+		# class TopDivisonPage < PageRecord::PageRecord
+		#   attributes [:name, :position, :ranking]
+		# end
+		#```
+		#
+		#
+	  def self.attributes(new_attributes)
+	  	undefine_class_methods(self)
+	  	undefine_instance_methods(self)
+	  	@attributes = new_attributes
+	  	define_class_methods(self)
+	  	define_instance_methods(self)
+	  end
+
+
+private
+
+		# @private
+		def self.set_type_name(base)
+			@base_name =  base.to_s.gsub('Page', '')
+			@type = @base_name.underscore
+		end
+
+		# @private
+		def self.get_attribute_names
+			begin
+				@host_class = @base_name.constantize
+				@attributes = @host_class.attribute_names.clone
+				@attributes.delete('id') # id is a special case attribute
+			rescue NameError
+				@attributes = []
+			end
+		end
+
+
+		# @private
+		def self.define_accessor_methods(base)
+			base.instance_eval do
+				@attributes.each do | attribute |
+					define_method("#{attribute}?") do
+						read_attribute?(attribute)
+					end
+					define_method(attribute) do
+						read_attribute(attribute)
+					end
+					define_method("#{attribute}=") do | value|
+						write_attribute(attribute, value)
+					end
+				end
+			end
+		end
+
+
+		# @private
+		def self.undefine_accessor_methods(base)
+			base.instance_eval do
+				@attributes.each do | attribute |
+					remove_method("#{attribute}?")
+					remove_method(attribute) 
+					remove_method("#{attribute}=")
+				end
+			end
+		end
+
+
+		# @private
+		def self.define_instance_methods(base)
+			define_accessor_methods(base)		
+		end
+
+		# @private
+		def self.undefine_instance_methods(base)
+			undefine_accessor_methods(base)		
+		end
+
+
+		# @private
+		def self.define_class_methods(base)
+			eigenclass = class << base; self; end
+			attributes = base.instance_variable_get('@attributes')
+ 			eigenclass.instance_eval do
+				attributes.each do | attribute|
+					define_method "find_by_#{attribute}" do | value, selector = "", filter = ""|
+						find_by_attribute( attribute, value, selector, filter)
+					end
+				end
+			end
+		end
+
+		# @private
+		def self.undefine_class_methods(base)
+			eigenclass = class << base; self; end
+			attributes = base.instance_variable_get('@attributes')
+ 			eigenclass.instance_eval do
+				attributes.each do | attribute|
+					remove_method "find_by_#{attribute}"
+				end
+			end
+		end
+
+
+		# @private
+		def self.context_for_selector(selector)
+			if selector.blank?
+				page
+			else
+				begin
+					page.find(selector).find(:xpath, "..")
+					rescue Capybara::Ambiguous
+						raise MultipleRecords, "Found multiple HTML segments with selector #{selector} on page"				
+					rescue Capybara::ElementNotFound
+						raise RecordNotFound, "#{selector} not found on page"						
+				end
+			end				
+		end
+
+	end
+end

data/lib/page_record/cucumber.rb

@@ -0,0 +1,5 @@
+require 'page_record'
+
+Before do
+  PageRecord::PageRecord.page = page
+end