Class: DataFactory

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Foundry
Defined in:
lib/test-factory/data_factory.rb

Overview

The Superclass for all of your data objects.

Instance Method Summary collapse

Methods included from Foundry

#create, #make, #on, #visit, #wait_until

Instance Method Details

#collection(name) ⇒ Object

Use for setting a data object’s class instance variable as a nested collection class.

This method assumes your collection class name ends with “Collection”. Therefore, the string you pass in its parameter is the first part of the class name.

E.g., your collection class is called “DataObjectCollection”, so, inside your parent object’s defaults, you’d set the instance variable like this:

Examples:

data_objects: collection('DataObject')


83
84
85
 
# File 'lib/test-factory/data_factory.rb', line 83

def collection(name)
  Kernel.const_get("#{name}Collection").new(@browser)
end

#data_object_copy ⇒ Object

Since Data Objects are not “Marshallable”, and they generally contain lots of types of data in their instance variables, we have this method. This will create and return a ‘deep copy’ of the data object as well as any and all nested data objects and collections it contains.

Please note that this method will fail if you are putting Data Objects into Arrays or Hashes instead of into Collection classes



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/test-factory/data_factory.rb', line 31

def data_object_copy
  opts = {}
  self.instance_variables.each do |var|
    key = var.to_s.gsub('@','').to_sym
    orig_val = instance_variable_get var
    opts[key] = case
                  when orig_val.kind_of?(CollectionsFactory)
                    orig_val.copy
                  when orig_val.instance_of?(Array) || orig_val.instance_of?(Hash)
                    begin
                      Marshal::load(Marshal.dump(orig_val))
                    rescue TypeError
                      raise %{\nKey: #{key.inspect}\nValue: #{orig_val.inspect}\nClass: #{orig_val.class}\n\nThe copying of the Data Object has thrown a TypeError,\nwhich means the object detailed above is not "Marshallable".\nThe most likely cause is that you have put\na Data Object inside an\nArray or Hash.\nIf possible, put the Data Object into a Collection.\n\n}
                    end
                  when orig_val.kind_of?(DataFactory)
                    orig_val.data_object_copy
                  else
                    orig_val
                end
  end
  self.class.new(@browser, opts)
end

#edit_fields(opts, page, *fields) ⇒ Object

Equivalent to #ordered_fill, except that it’s used in the context of a Data Object’s #edit method(s). As such, it requires the #edit method’s hash to be passed as its own first parameter.

Examples:

on PageClass do |page|
  edit_fields opts, page, :text_field_name, :radio_name, :select_list_name, :checkbox_name
end


198
199
200
 
# File 'lib/test-factory/data_factory.rb', line 198

def edit_fields(opts, page, *fields)
  edit_item_fields opts, nil, page, *fields
end

#edit_item_fields(opts, name, page, *fields) ⇒ Object

Equivalent to #ordered_item_fill, except that it’s used in the context of a Data Object’s #edit method(s). As such, it requires the #edit method’s hash to be passed as its own first parameter.

Examples:

on PageClass do |page|
  edit_item_fields opts, 'Joe Schmoe', page, :text_field_name, :radio_name, :select_list_name, :checkbox_name
end


212
213
214
 
# File 'lib/test-factory/data_factory.rb', line 212

def edit_item_fields(opts, name, page, *fields)
  parse_fields(opts, name, page, *fields)
end

#fill_out(page, *fields) ⇒ Object

A shortcut method for filling out fields on a page. The method’s first parameter is the page class that contains the fields you want to fill out. That is followed by the list of field name(s) (as Symbols).

This method has a number of requirements:

1) The field name and the instance variable name in your data object must be identical. For this reason, this method can only be used in your data objects’ create methods.

2) Your checkbox and radio button data object instance variables are either nil, :set, or :clear. Any other values will not be handled correctly.

3) Since the listed fields get filled out in random order, be sure that this is okay in the context of your page–in other words, if field A needs to be specified before field B then having them both in your fill_out step would be inappropriate. If you need a specific order, use #ordered_fill instead.

4) This method supports text fields, select lists, check boxes, and radio buttons, but only if their element definitions don’t take a parameter. Please use the #fill_out_item with elements that do need a parameter defined.

Examples:

on PageClass do |page|
  fill_out page, :text_field_name, :radio_name, :select_list_name, :checkbox_name
end


147
148
149
 
# File 'lib/test-factory/data_factory.rb', line 147

def fill_out(page, *fields)
  f_o_i true, nil, page, *fields
end

#fill_out_item(name, page, *fields) ⇒ Object

Same as #fill_out, but used with methods that take a parameter to identify the target element…

Examples:

on PageClass do |page|
  fill_out_item 'Joe Schmoe', page, :text_field_name, :radio_name, :select_list_name, :checkbox_name
end


171
172
173
 
# File 'lib/test-factory/data_factory.rb', line 171

def fill_out_item(name, page, *fields)
  f_o_i true, name, page, *fields
end

#get_or_select(hash_inst_var, select_list) ⇒ Object

This method accomplishes the same thing as #get_or_select! but is used specifically when the instance variable being used/updated is a Hash and you only need to update one of its key/value pairs.

Pay close attention to the syntax differences between this method and #get_or_select!

First, note that the returned value of this method must be explicitly passed to the relevant key in the Hash instance variable. Note also that, unlike #get_or_select!, this method does not take a symbolized representation of the instance variable.

Examples:

@open[:day] = get_or_select(@open[:day], page.open_day)


278
279
280
281
282
283
284
285
 
# File 'lib/test-factory/data_factory.rb', line 278

def get_or_select(hash_inst_var, select_list)
  if hash_inst_var==nil
    select_list.selected_options[0].text
  else
    select_list.select hash_inst_var
    hash_inst_var
  end
end

#get_or_select!(inst_var_sym, select_list) ⇒ Object

This is a specialized method for use with any select list boxes that exist in the site you’re testing and will contain unpredictable default values.

Admittedly, this is a bit unusual, but one example would be be a “due date” list that changes its default selection based on today’s date. You’re going to want to do one of two things with that select list:

1) Retrieve and store the select list’s value 2) Specify a custom value to select

Enter: #get_or_select!

Assuming you just want to store the default value, then your Data Object’s instance variable for the field will–initially–be nil. In that case, #get_or_select! will grab the select list’s current value and store it in your instance variable.

On the other hand, if you want to update that field with your custom value, then your instance variable will not be nil, so #get_or_select! will take that value and use it to update the select list.

Note that this method only works with select lists that take a single selection. Multi-selects are not supported.

Also note that the first parameter is not the instance variable you need to use/update. It is a symbol that otherwise matches the instance variable.

will either be set or be used to update the page

Examples:

get_or_select! :@num_resubmissions, page.num_resubmissions

Parameters:

  • inst_var_sym (Symbol) —

    A Symbol that must match the instance variable that

  • select_list (Watir::Select) —

    The relevant select list element on the page



254
255
256
257
258
259
260
261
 
# File 'lib/test-factory/data_factory.rb', line 254

def get_or_select!(inst_var_sym, select_list)
  value = instance_variable_get inst_var_sym
  if value==nil
    instance_variable_set inst_var_sym, select_list.selected_options[0].text
  else
    select_list.select value
  end
end

#ordered_fill(page, *fields) ⇒ Object

Use when you need to specify the order that the fields should be updated.

Examples:

on PageClass do |page|
  ordered_fill page, :text_field_name, :radio_name, :select_list_name, :checkbox_name
end


159
160
161
 
# File 'lib/test-factory/data_factory.rb', line 159

def ordered_fill(page, *fields)
  f_o_i false, nil, page, *fields
end

#ordered_item_fill(name, page, *fields) ⇒ Object

Use instead of #fill_out_item when you need to specify the order that the fields should be updated.

Examples:

on PageClass do |page|
  ordered_item_fill 'Joe Schmoe', page, :text_field_name, :radio_name, :select_list_name, :checkbox_name
end


184
185
186
 
# File 'lib/test-factory/data_factory.rb', line 184

def ordered_item_fill(name, page, *fields)
  f_o_i false, name, page, *fields
end

#requires(*elements) ⇒ Object

Items passed to this method are checked to ensure that the associated class instance variable is not nil. If it is, the script is aborted and an error is thrown. Use symbols separated by commas with this method. The symbol(s) should exactly match the name of the instance variable that must not be empty.

NOTE: Currently this is backwards compatible with prior versions, which took the instance variables directly in the parameter. This backwards compatibility will be removed in some future update of the gem.

Examples:

requires :site, :assignment, :document_id

Parameters:

  • elements (Array) —

    the list of items that are required.



101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/test-factory/data_factory.rb', line 101

def requires(*elements)
  elements.each do |inst_var|
    if inst_var.kind_of? Symbol
      string="@#{inst_var.to_s}"
      if instance_variable_get(string)==nil
        raise "You've neglected to define a required variable for your #{self.class}.\n\nPlease ensure you always specify a value for #{string} when you create the data object."
      end
    elsif inst_var.kind_of? String
      warn "<<<<WARNING!>>>>\n\nPlease update the requires method in your\n#{self.class} class to refer to symbols\ninstead of directly referencing the class'\ninstance variables.\n\n  Example:\n\n    This...\n      requires @document_id\n    Should be updated to...\n      requires :document_id\n\nIn future versions of TestFactory the 'requires'\nmethod will only support symbolized references\nto the instance variables. The backwards\ncompatibility will be removed.\n\n<<<<WARNING!>>>>"
    elsif inst_var==nil
      raise "You've neglected to define a required variable for your #{self.class}.\n\n<<<<WARNING!>>>>\n\nPlease update the requires method in your #{self} class to refer to symbols\ninstead of directly referencing the class'\ninstance variables.\n\nIn future versions of TestFactory the 'requires' method\nwill only support symbolized references\nto the instance variables. The backwards\ncompatibility will be removed.\n\n<<<<WARNING!>>>>"
    end
  end
end

#set_options(hash) ⇒ Object Also known as: update_options

Add this to the bottom of your Data Object’s initialize method. This method does 2 things: 1) Converts the contents of the hash into the class’s instance variables. 2) Grabs the names of your collection class instance variables and stores

them in an Array. This is to allow for the data object class to send
any needed updates to its children. See #notify_coolections for more
details.

Parameters:

  • hash (Hash) —

    Contains all options required for creating the needed Data Object



63
64
65
66
67
68
69
 
# File 'lib/test-factory/data_factory.rb', line 63

def set_options(hash)
  @collections ||= []
  hash.each do |key, value|
    instance_variable_set("@#{key}", value)
    @collections << key if value.kind_of?(CollectionsFactory)
  end
end

#update_from_parent(update) ⇒ Object

Define this method in your data object when it has a parent, and that parent may periodically need to send it updated information about itself.



292
293
294
295
296
297
298
299
 
# File 'lib/test-factory/data_factory.rb', line 292

def update_from_parent(update)
  raise %{
  This method must be implemented in your data object
  class if you plan to pass updates from a
  parent object to the members of its
  collections.
         }
end