test-factory 0.1.7 → 0.1.8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    test-factory (0.1.7)
+    test-factory (0.1.8)
       watir-webdriver (>= 0.6.1)
 
 GEM

data/README.md

@@ -11,8 +11,11 @@ Use it to abstract away from the underlying [Watir](http://www.watir.com) code a
 With TestFactory you have the ability to...
 
 1. Easily instantiate page classes (described below) in a consistent and readable manner
-2. Concisely describe elements on a page, keeping it DRY by avoiding repetition of element identifiers that may (will) change
-3. Provide higher-level methods that use customizable (and default) data, along with the page classes and elements, to perform user-oriented functions with minimal lines of code
+2. Concisely describe elements on a page, keeping it DRY by avoiding repetition of element
+   identifiers that may (will) change
+3. Provide higher-level methods that use customizable (and default) data, along with the
+   page classes and elements, to perform user-oriented--i.e., behavioral--functions
+   with minimal lines of code
 
 Tremendous thanks is due to [Alister Scott](http://watirmelon.com), whose [custom page object code](https://github.com/alisterscott/wmf-custom-page-object) for the Wikimedia Foundation provided the inspiration for this gem.
 
@@ -21,9 +24,16 @@ Summary
 
 Using the TestFactory properly involves three distinct steps:
 
-1. Creating page classes that contain references to the elements on your web page. For this you use the PageFactory class. Working on page classes requires that you have a strong command of Watir and basic skills with Ruby.
-2. Creating "data objects" that utilize your page classes and elements to build methods that perform user-oriented tasks. For this you use the DataFactory module. Working on data objects requires you have good familiarity with Watir and strong Ruby skills.
-3. Creating test scenarios using your favorite test framework (like Cucumber or Rspec) and your data objects. The methods in the Foundry class are useful here. Working at this level requires only basic skills with Ruby and Watir, but a strong command of your DSL (the thing you're building with TestFactory).
+1. Creating page classes that contain references to the elements on your web page. For this
+   you use the PageFactory class. Working on page classes requires that you have a strong
+   command of Watir and basic skills with Ruby.
+2. Creating "data objects" that utilize your page classes and elements to build methods that
+   perform user-oriented tasks. For this you use the DataFactory module. Working on data
+   objects requires you have good familiarity with Watir and strong Ruby skills.
+3. Creating test scenarios using your favorite test framework (like Cucumber or Rspec) and
+   your data objects. The methods in the Foundry class are useful here. Working at this
+   level requires only basic skills with Ruby and Watir, but a strong command of your DSL
+   (the thing you're building with TestFactory).
 
 How to Start
 ------------
@@ -156,6 +166,66 @@ on MyPage do |page|
 end
 ```
 
+Design Pattern
+--------------
+
+The TestFactory was written assuming the following guiding principles. Any code that does not follow them is probably not DRY.
+
+1.  Page Classes contain methods relating to interactions with page elements only--meaning
+    the getting or setting of values, or the clicking of links or buttons. Any more
+    complicated page interactions are handled in the Data Object classes, or in the test
+    step definitions.
+2.  Data Objects represent definable data structure entities in the system being tested.
+    As data, they fit into the [CRUD Model](http://en.wikipedia.org/wiki/Create,_read,_update_and_delete)
+    and thus have methods that correspond to those basic functions.
+3.  Data Objects have a single method for each of the CRUD functions, and additional
+    custom methods are avoided without compelling arguments for their inclusion in the class.
+4.  When a Data Object is executing its `edit` method, first the data in the
+    system under test is updated, then the data object's instance variables
+    are updated--using `set_options`.
+5.  Site navigation is handled using conditional methods (meaning they only navigate if
+    necessary) inside the Data Object, unless there are specific reasons to explicitly
+    navigate in a step definition. This keeps step definitions from being unnecessarily cluttered.
+6.  Specifying non-default test variables for data objects is done using key/value hash
+    pairs that are parameters of the data object's CRUD methods. It is _not_
+    done by explicitly assigning values to the instance variables. Examples:
+    ```ruby
+    # During object creation, following the name of the class
+    @data_object = make DataObject, :attrib1 => "Custom Value 1", :attrib2 => "Custom Value 2" # etc...
+
+    # When an object is edited (Ruby v1.9.3 Hash syntax optional)
+    @data_object.edit attrib1: "Updated Value 1", attrib2: "Updated Value 2"
+
+    # This is frowned upon:
+    @data_object.attrib1="Another Value"
+
+    ```
+7.  Updates to a data object's instance variables is handled *only* by the `set_options` method, *not* explicitly.
+    ```ruby
+    # This is good
+    def edit opts={}
+      #...
+      page.element.fit opts[:value]
+      #...
+      update_options(opts)
+    end
+
+    # This is not good
+    def edit opts={}
+      #...
+      page.element.fit opts[:value]
+      #...
+      @value=opts[:value] unless @value==opts[:value]
+    end
+    ```
+8.  The setting of random values for select lists in a data object is determined by passing
+    the symbol `:random` in the instance variable or as the value in the key/value pair
+    passed in an `#edit` method's `opts` parameter. The `#create` and `#edit` methods will
+    handle the necessary logic. The purpose is to prevent the need for custom randomizing
+    CRUD methods in the data object.
+9.  See the gem_ext.rb file's discussion of the Watir `#fit` method for additional
+    design pattern rules to follow.
+
 Notice
 ------
 

data/lib/test-factory/gem_ext.rb

@@ -2,29 +2,29 @@
 # which can be used with text fields, select lists, radio buttons,
 # and checkboxes.
 #
-# The purpose of #fit is to allow the creation, in your Data Object classes,
-# of a minimal number of #edit methods (ideally only one) written as
+# The purpose of +#fit+ is to allow the creation, in your Data Object classes,
+# of a minimal number of +#edit+ methods (ideally only one) written as
 # concisely as possible.
 #
-# Without the #fit method, you would either have to write separate edit
+# Without the +#fit+ method, you would either have to write separate edit
 # methods for every possible field you want to edit, or else your
 # edit method would have to contain lots of repetitive conditional code
-# to prevent making edits to those fields that don't need it.
+# to prevent making inadvertent updates to those fields that don't need it.
 #
-# Proper use of the #fit method requires following a particular coding
+# Proper use of the +#fit+ method requires following a particular coding
 # pattern, however:
 #
-# 1. In your Page Classes, define your radio buttons and checkboxes directly. Do not define #set and/or #clear actions there.
-# 2. Your data object's instance variables for radio buttons and checkboxes, when not +nil+, should have the values of +:set+ or +:clear+. If they *need* to be something else, then define a Hash transform method to easily convert the custom values back to +:set+ or +:clear+, then pass that transform to the #fit method.
-# 3. Always remember to end your #edit methods with the #set_options() method, from the DataFactory module. It automatically takes care of updating your data object's instance variables with any new values.
+# 1. In your Page Classes, define your text fields, select lists, radio buttons, and checkboxes directly. Do not define +#select+, +#set+ and/or +#clear+ actions there.
+# 2. Your data object's instance variables for radio buttons and checkboxes, when not +nil+, should have the values of +:set+ or +:clear+. If they *need* to be something else, then define a Hash transform method to easily convert the custom values back to +:set+ or +:clear+, then pass that transform to the +#fit+ method.
+# 3. Always remember to end your +#edit+ methods with the +#set_options()+ method (a.k.a. +#update_options+), from the DataFactory module. It automatically takes care of updating your data object's instance variables with any new values.
 #
 # ==Example
 #
-# Let's take a look at how the proper use of #fit in your code can significantly
-# clean things up, using a checkbox field for our example. Remember that #fit
+# Let's take a look at how the proper use of +#fit+ in your code can significantly
+# clean things up, using a checkbox field for our example. Remember that +#fit+
 # works with radio buttons, text fields, and select lists, too.
 #
-# First, here's some code written without using #fit, and using
+# First, here's some code written without using +#fit+, and using
 # actions for the checkbox page objects, and a Data Object
 # instance variable, +@option+, that is either "YES" or "NO"...
 #
@@ -54,9 +54,9 @@
 #     # ...
 #   end
 #
-# Now, let's take that same code, but this time use the #fit method, assume that
+# Now, let's take that same code, but this time use the +#fit+ method, assume that
 # the data object's +@option+ instance variable will be +:set+, +:clear+, or +nil+, and
-# end the #edit with the DataFactory's #set_options helper method...
+# end the +#edit+ with the DataFactory's +#set_options+ helper method...
 #
 #   class MyPage < BasePage
 #     # ...
@@ -87,7 +87,7 @@
 #     { "YES" => :set, "NO" => :clear }
 #   end
 #
-# Then use that transform with your #fit method, like this:
+# Then use that transform with your +#fit+ method, like this:
 #
 #   page.checkbox.fit checkbox_trans[opts[:option]]
 #

data/test-factory.gemspec

@@ -1,6 +1,6 @@
 spec = Gem::Specification.new do |s|
   s.name = 'test-factory'
-  s.version = '0.1.7'
+  s.version = '0.1.8'
   s.summary = %q{rSmart's framework for creating automated testing scripts}
   s.description = %q{This gem provides a set of modules and methods to help quickly and DRYly create a test automation framework using Ruby and Watir (or watir-webdriver).}
   s.files = Dir.glob("**/**/**")
@@ -8,6 +8,6 @@ spec = Gem::Specification.new do |s|
   s.authors = ["Abraham Heward"]
   s.email = %w{"aheward@rsmart.com"}
   s.homepage = 'https://github.com/rSmart'
-  s.add_dependency 'watir-webdriver', '>= 0.6.1'
+  s.add_dependency 'watir-webdriver', '>= 0.6.2'
   s.required_ruby_version = '>= 1.9.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: test-factory
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-28 00:00:00.000000000 Z
+date: 2013-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: watir-webdriver
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.6.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.6.2
 description: This gem provides a set of modules and methods to help quickly and DRYly
   create a test automation framework using Ruby and Watir (or watir-webdriver).
 email:
@@ -47,7 +47,6 @@ files:
 - lib/test-factory/string_factory.rb
 - lib/test-factory.rb
 - README.md
-- test-factory-0.1.6.gem
 - test-factory.gemspec
 homepage: https://github.com/rSmart
 licenses: []