rtml 2.0.3 → 2.0.4

data/lib/rtml/inherited_instance_variables.rb

@@ -2,7 +2,14 @@ module Rtml::InheritedInstanceVariables
   def copy_ivars_from(source)
     ivars = source.instance_variables
     ivars -= source.protected_instance_variables if source.respond_to?(:protected_instance_variables)
-    ivars.each { |ivar| instance_variable_set(ivar, source.instance_variable_get(ivar)) }
+    ivars -= source.rtml_protected_instance_variables if source.respond_to?(:rtml_protected_instance_variables)
+    ivars.each do |ivar|
+      # as time consuming as this may be, it's still faster than eval("defined?(#{ivar})")
+      #  -- and easier to read, too.
+      if !instance_variables.include?(ivar)
+        instance_variable_set(ivar, source.instance_variable_get(ivar))
+      end
+    end
   rescue
     # fail silently if they can't be copied
   end

data/lib/rtml/links.rb

@@ -0,0 +1,17 @@
+module Rtml::Links
+  # str_or_sym is the string or symbol to find
+  # id_ref is a boolean: if true, then # is prepended where necessary
+  def id_for(str_or_sym)
+    tml_id = Rtml::Dom::Element.find_or_create_tml_id(str_or_sym)
+
+    if local?(tml_id)
+      "##{tml_id}"
+    else
+      tml_id
+    end
+  end
+
+  def local?(str_or_sym)
+    !(str_or_sym.kind_of?(String) && (str_or_sym =~ /\// || str_or_sym =~ /#/ || str_or_sym =~ /:/) || str_or_sym.blank?)
+  end
+end

data/lib/rtml/rules/dom_validation.rb

@@ -139,6 +139,7 @@ module Rtml::Rules::DomValidation
     tag_rules = rules.tag_rules(tag_name)
     prev_index = -1
     element.children.each do |child|
+      next if child.kind_of?(Hpricot::Text) || child.kind_of?(Hpricot::Comment)
       chn = child.name
       prn = '[no element]'
       index = tag_rules.order.index(child.name)

data/lib/rtml/test/builtin_variables.rb

@@ -0,0 +1,33 @@
+module Rtml
+  module Test
+    module BuiltinVariables
+      def self.add_variable(name, options) #:nodoc:
+        options = { :type => options } if !options.kind_of?(Hash)
+        BUILTIN_VARIABLES[name] = options
+      end
+
+      BUILTIN_VARIABLES = {}
+      add_variable('card.cardholder_name', :string)
+      add_variable('card.effective_date', :date)
+      add_variable('card.expiry_date', :date)
+      add_variable('card.input_type', :integer)
+      add_variable('card.issue_number', :integer)
+      add_variable('card.issuer_name', :string)
+      add_variable('card.scheme', :string)
+      add_variable('card.pan', :integer)
+      add_variable('card.parser.type', :string)
+      add_variable('card.parser.verdict', :string)
+      add_variable('card.parser.reject_reason', :string)
+      
+      add_variable('payment.amount', :integer)
+      add_variable('payment.amount_other', :integer)
+      BUILTIN_VARIABLES.freeze
+
+      def declare_builtin_variables!
+        BUILTIN_VARIABLES.each do |name, options|
+          declare_variable(name, options)
+        end
+      end
+    end
+  end
+end

data/lib/rtml/test/resemblance_test.rb

@@ -0,0 +1,97 @@
+# Used to see if a specified TML structure (given in the form of a Hash) resembles the
+# overall structure of the given TML document.
+#
+# This is used to validate that the document conforms to a particular set of expectations
+# without the overhead of loading it into the simulator.
+#
+# This class is tied into RSpec with the #resemble_tml method, as well as into Test::Unit
+# with the #assert_tml_resembles method:
+#
+# RSpec Example
+#
+#   get :index
+#   response.should resemble_tml(:tml => { :screen => [ :setvar, :submit => { :getvar } ] })
+#
+#   response.should_not resemble_tml(. . .) # negative test
+#
+# Test::Unit Examples
+#
+#   get :index
+#   assert_tml_resembles(:tml => { :screen => [ :setvar, :submit => { :getvar } ] }, response)
+#   
+#   assert_tml_not_resemble(. . .) # negative test
+#
+class Rtml::Test::ResemblanceTest
+  attr_reader :tml, :expectation
+
+  def pass?
+    pass_recursively?
+  end
+
+  def initialize(expectation, tml)
+    build_expectation(expectation)
+    find_tml(tml)
+    @xml = Hpricot::XML(@tml).root
+  end
+
+  private
+  def pass_recursively?(exp = @expectation.deep_dup, level = @xml)
+    case exp
+      when Hash
+        pass_recursively_with_hash?(exp, level)
+      when Array
+        pass_with_array?(exp, level)
+      else
+        pass_with_object?(exp, level)
+    end
+  end
+
+  def pass_recursively_with_hash?(exp, level)
+    if key_matches = pass_with_array?(exp.keys, level)
+      key_matches.each do |match|
+        if array = pass_with_array?(exp.values, match)
+          return array
+        end
+      end
+    end
+    false
+  end
+
+  def pass_with_array?(exp, level)
+    matches = []
+    exp.each do |item|
+      return false unless object_matches = pass_recursively?(item, level)
+      matches.concat object_matches
+    end
+    matches
+  end
+
+  def pass_with_object?(exp, level)
+    if exp.to_s == level.name
+      [level]
+    elsif (matches = (level / exp)) && !matches.empty?
+      matches
+    else
+      false
+    end
+  end
+
+  def build_expectation(hash)
+    @expectation = hash
+  end
+
+  def find_tml(object)
+    @tml = case object
+      when ActionController::TestResponse
+        object.body
+      when String
+        object
+      when Hpricot::Doc, Hpricot::Elem
+        object.to_s
+      when ActiveRecord::Base, Rtml::DocumentModelObject
+        object.to_tml
+      else
+        object.to_s
+    end
+  end
+end

data/lib/rtml/test/screen.rb

@@ -0,0 +1,126 @@
+# Used for modeling the current screen by Rtml::Test::TmlApplication.
+class Rtml::Test::Screen
+  delegate :[], :[]=, :/, :to_s, :to => :screen
+  
+  def initialize(tml)
+    @screen = tml
+  end
+
+  def ==(screen)
+    id == screen.id
+  end
+
+  def id
+    @screen['id']
+  end
+
+  def display?
+    !((@screen / "display") || []).empty?
+  end
+
+  def variant_with_hotkey(which)
+    possible_variants.each { |variant| return variant[:uri] if variant[:key] == which }
+    nil
+  end
+
+  def card_readers
+    ((@screen / "card") || [])
+  end
+
+  def uri_for_hotkey(which)
+    if variant = variant_with_hotkey(which)
+      return variant
+    end
+    return @screen[which] if @screen[which]
+    nil
+  end
+
+  # Returns the +next+ element for this screen, or nil if there is none.
+  def next_element
+    ((@screen / "next") || []).shift
+  end
+
+  # Returns the hyperlink Hpricot element, if there's only one; nil if there are none; and raises an
+  # Rtml::Errors::ApplicationError if there are multiple links (because there's no inference as to which link to
+  # follow).
+  def autoselect_hyperlink
+    if !(links = hyperlinks).empty?
+      if links.length > 1
+        raise Rtml::Errors::ApplicationError, "Cannot auto-select hyperlink: too many choices on screen #{id.inspect}"
+      end
+      links.shift
+    else
+      nil
+    end
+  end
+
+  def hyperlinks
+    (@screen / "a") || []
+  end
+
+  # Returns true if this screen is an input screen (that is, if it will halt program flow
+  # waiting for user input).
+  def input?
+    return true if !choices.empty?
+    Rtml::Test::TmlApplication::USER_INPUT_ELEMENTS.each { |ele| return true if !(@screen / ele).empty? }
+    false
+  end
+
+  def timeout
+    return @screen['timeout'].to_i if @screen['timeout']
+    nxt = ((@screen / "next") || []).shift
+    if nxt
+      return nxt['timeout'].to_i if nxt['timeout']
+      ((nxt / "variant") || []).each do |var|
+        return var['timeout'].to_i if var['timeout']
+      end
+    end
+    0
+  end
+  
+  def setvars
+    ((@screen / "setvar") || [])
+  end
+
+  # Returns an array of URIs that can be chosen by the user at this time, or an empty
+  # array if none can be chosen. This inversely coincides with #next_screen in that choices
+  # are only available if #next_screen returns an empty array, just as #next_screen will only
+  # return an empty array if choices are available.
+  def choices
+    choices = (@screen / "a").collect do |a|
+      a['href']
+    end
+    ((@screen / "variant") || []).each do |variant|
+      choices << variant['uri'] if variant['key']
+    end
+    choices
+  end
+  
+  
+  # Returns an array of Hashes representing all possible non-user interaction-requiring variants
+  # from this screen. These are returned regardless of whether user interation is required at this time.
+  #
+  # The hashes are laid out thusly:
+  #   { :uri => "destination_uri", :key => "hotkey", :timeout => "seconds", :lo => "left_operand",
+  #     :op => "operation", :ro => "right_operand" }
+  #
+  # Note that some of these keys may be omitted, according to the TML rules for the +variant+ element.
+  #
+  # For TML +next+ elements, all keys except :uri are omitted.
+  #
+  def possible_variants
+    variants = ((@screen / "variant") || []).collect do |variant|
+      { :uri => variant['uri'], :key => variant['key'], :timeout => variant['timeout'],
+        :lo  => variant['lo'],  :op  => variant['op'],  :ro      => variant['ro'] }.optionalize
+    end
+    if !(nxt = (@screen / "next") || []).empty?
+      variants << { :uri => nxt.first['uri'] }
+    else
+      variants << { :uri => @screen['next'] }
+    end
+    variants
+  end
+
+  private
+  attr_reader :screen
+end

data/lib/rtml/test/simulator.rb

@@ -0,0 +1,240 @@
+# FIXME: Is there an easier way to load these other than just force feeding the filenames?
+Rtml::Test::SimulatorPostProcessors::CardParsers
+Rtml::Test::SimulatorPostProcessors::Submit
+Rtml::Test::SimulatorPostProcessors::Receipt
+
+class Rtml::Test::Simulator
+  delegate :response, :request, :controller, :to => :session
+  delegate :screens, :current_screen, :current_screen_id, :next_screen, :next_screen_id, 
+           :waiting_for_input?, :find_screen, :process, :continue, :receipt,
+           :to => :app
+  attr_reader :app, :session
+
+  # Accepts a path to the TML document which should be requested. To pass raw TML,
+  # use this syntax:
+  #   Rtml::Test::Simulator.new(:tml => my_tml_code)
+  def initialize(start_at = nil)
+    @session = ActionController::Integration::Session.new
+    @variables = Rtml::Test::VariableScope.new
+    @headers = HashWithIndifferentAccess.new
+    if start_at.kind_of?(Hash)
+      load_tml! start_at[:tml]
+    else
+      visit(start_at) unless start_at.nil?
+    end
+  end
+
+  def post_data(location, data = {})
+    post(location, data, @headers)
+    load_tml!(response.body)
+  end
+
+  def header(name, value)
+    @headers[name] = value
+  end
+  
+  def headers
+    @headers.dup
+  end
+
+  # Instead of using "visit", this just force-feeds some TML into the simulator. Useful for
+  # hard-coded, quick-and-dirty debug situations, but far less useful for testing a real app
+  # or a large document.
+  def load_tml!(tml)
+    @path = nil
+    build_app(tml)
+    process
+  end
+
+  def process(forward = false, &block)
+    # FIXME: TODO: Refactor, this is too ugly!
+    if block_given?
+      uri = catch(:new_document) { yield; nil }
+    else
+      uri = catch(:new_document) do
+        if forward
+          app.continue_forward
+        else
+          app.continue
+        end
+        nil
+      end
+    end
+
+    if uri
+      if uri =~ /^tmlvar\:(.*)$/ # it's a TML variable referencing a screen ID
+        uri = variables[$~[1]]
+        if uri.blank?
+          raise Rtml::Errors::SimulationError, "Empty screen reference: tmlvar #{$~[1]} on screen #{current_screen_id}"
+        end
+      end
+      if uri == @path && current_screen_id == app.screens.first['id']
+        raise Rtml::Errors::SimulationError,
+              "Circular foreign reference: #{@path}##{current_screen_id}"
+      end
+      visit_uri(uri)
+    end
+
+    do_post_processing!
+  end
+
+  def visit(path, options = {})
+    options.reverse_merge! default_options
+    path = "##{path}" if path.kind_of?(Symbol)
+    if File.file?(path)
+      build_app File.read(@path = path)
+    else
+      path, screen = path_and_screen_from path
+      if !path.blank? && @path != path
+        get_and_build(path)
+      else
+        app.screenflow.clear
+      end
+      if screen && !screen.blank? && screen != '#'
+        app.jump_to_screen screen
+      end
+    end
+    process if options[:process]
+  end
+
+  # Visits the specified URI.
+  # This merely wraps a call to #visit, but is called internally by #process when following
+  # a direction to visit a new URI outside of the current document. This makes it useful for
+  # setting up test expectations because you can make sure that #visit_uri is (or isn't)
+  # called without worrying about breaking #visit.
+  def visit_uri(uri)
+    visit(uri)
+  end
+
+  def follow_link(path_or_text)
+    on_current_screen("a").each do |hyperlink|
+      if hyperlink['href'] == path_or_text || hyperlink.inner_text =~ /#{Regexp::escape path_or_text}/i
+        visit hyperlink['href']
+        return
+      end
+    end
+    raise Rtml::Errors::SimulationError,
+          "Hyperlink not found on screen #{current_screen_id.inspect}: #{path_or_text.inspect}"
+  end
+
+  def press(which_button)
+    process do
+      app.trigger_button_press(which_button)
+      process # FIXME: is this even necessary?
+    end
+  end
+
+  # carrier can be any of :visa, :mastercard, :jcb, :amex, :discover, and :debit.
+  # if it's anything else, the 'card.pan' and 'card.scheme' options must be specified.
+  def swipe_card(carrier, options = {})
+    options.reverse_merge!('card.cardholder_name' => 'Cardholder',
+                           'card.effective_date' => Time.now,
+                           'card.expiry_date' => 1.year.from_now,
+                           'card.input_type' => 1,
+                           'card.issue_number' => 0,
+                           'card.issuer_name' => 'NA',
+                           'card.scheme' => carrier.to_s.upcase,
+                           'card.pan' => case carrier
+                             when :visa then '4111111111111111'
+                             when :mastercard then '5454545454545454'
+                             when :amex then '3434343434343434'
+                             when :discover then '6011000012345678'
+                             when :jcb then '3083000012345678'
+                             when :debit then '1000000012345678'
+                             else nil
+                           end
+    )
+
+    unless options['card.pan'] && options['card.scheme']
+      raise Rtml::Errors::SimulationError, "Carrier not recognized and/or options are invalid"
+    end
+
+    card_parsers = on_current_screen("card")
+    card_parsers.each do |card|
+      if card['parser'] == 'mag' && card['parser_params'] == 'read_data'
+        app.update_variables(options)
+        process(:forward)
+        return
+      end
+    end
+    raise Rtml::Errors::SimulationError,
+          "Could not find a suitable card parser (with parser 'mag' and parser_params 'read_data') on screen #{current_screen_id.inspect}"
+  end
+
+  def fill_in(variable_name, value)
+    variable_name = variable_name.to_s unless variable_name.kind_of?(String)
+    on_current_screen("input").each do |field|
+      if field['name'] == variable_name
+        variables[variable_name] = value
+        return
+      end
+    end
+    raise Rtml::Errors::SimulationError,
+          "Form element for variable #{variable_name.inspect} does not appear on screen #{current_screen_id.inspect}"
+  end
+
+  def variables
+    app.variable_scope
+  end
+
+  private
+  delegate :get, :post, :put, :delete, :to => :session
+
+  def default_options
+    {
+      :process => true
+    }
+  end
+  
+  def on_current_screen(field_name)
+    current_screen ? ((current_screen / field_name) || []) :
+            raise(Rtml::Errors::SimulationError, "Current screen was expected to not be nil")
+  end
+
+  def build_app(tml)
+    @app = Rtml::Test::TmlApplication.new(tml)
+  end
+
+  def get_and_build(path)
+    # set up state mocking
+    unless path =~ /ignore_state/
+      if path =~ /\?/
+        path.concat "&ignore_state=true"
+      else
+        path.concat "?ignore_state=true"
+      end
+    end
+
+    get @path = path, {}, @headers
+    if response # actually the only time there's no response should be during tests which stub #get
+      format = response.template.template_format
+      unless format == :rtml
+        raise Rtml::Errors::InvalidFormat, "Response must be in :rtml format; found #{format.inspect}:\n#{response.body}"
+      end
+      build_app(response.body)
+    end
+  end
+
+  def path_and_screen_from(path)
+    path, screen = path.split(/#/)
+    # query string
+    if screen =~ /\?/
+      screen, query = screen.split(/\?/)
+      path = "#{path}?#{query}"
+    end
+    [path, screen]
+  end
+
+  include Rtml::Widgets
+  
+  # we're almost done. App is likely in a "waiting" state; we need to see if it's "waiting"
+  # for something that the simulator can, er, simulate, such as card risk management or
+  # EMV processing. If it is, then we need to fill out whatever variables are expected, and
+  # then send another call to #process.
+  def do_post_processing!
+    return unless current_screen
+    self.widget_entry_points.each do |entry_point|
+      send(entry_point)
+    end
+  end
+end