rtml 2.0.3 → 2.0.4

data/lib/rtml/test/simulator_post_processors/base.rb

@@ -0,0 +1,7 @@
+class Rtml::Test::SimulatorPostProcessors::Base < Rtml::Widget
+  delegate :variables, :process, :on_current_screen, :current_screen, :current_screen_id, :to => :parent
+
+  def continue_forward
+    process(:forward => true)
+  end
+end

data/lib/rtml/test/simulator_post_processors/card_parsers.rb

@@ -0,0 +1,32 @@
+class Rtml::Test::SimulatorPostProcessors::CardParsers < Rtml::Test::SimulatorPostProcessors::Base
+  affects 'Rtml::Test::Simulator', 'simulator'
+  entry_point :check_card_parsers
+
+  def check_card_parsers
+    if !(card_readers = current_screen.card_readers).empty?
+      card_readers.each do |card_reader|
+        case card_reader['parser']
+          when 'mag'
+            process_mag_reader(card_reader['parser_params'])
+          when 'emv'
+            process_emv_reader(card_reader['parser_params'])
+          else raise ""
+        end
+      end
+    end
+  end
+
+  def process_mag_reader(params)
+    case params
+      when 'read_data' ; # nothing because this needs user input
+      when 'risk_mgmt'
+        variables['card.parser.verdict'] = 'online'
+        continue_forward
+      else raise Rtml::Errors::SimulatorError, "Invalid mag params: #{params}"
+    end
+  end
+
+  def process_emv_reader(params)
+    raise "EMV params not supported: #{params}"
+  end
+end

data/lib/rtml/test/simulator_post_processors/receipt.rb

@@ -0,0 +1,15 @@
+class Rtml::Test::SimulatorPostProcessors::Receipt < Rtml::Test::SimulatorPostProcessors::Base
+  affects 'Rtml::Test::Simulator', 'simulator'
+  entry_point :check_print_directive
+
+  def check_print_directive
+    if print = on_current_screen("print").first
+      # We reconstruct it because changing its child <getvar>'s will change the XML itself, which we don't want.
+      print = Hpricot::XML(print.to_s).root
+      ((print / "getvar") || []).each { |getvar| getvar.inner_html = variables.literal_value(variables[getvar['name']]) }
+
+      parent.receipt << print.inner_html
+      parent.process(true)
+    end
+  end
+end

data/lib/rtml/test/simulator_post_processors/submit.rb

@@ -0,0 +1,15 @@
+class Rtml::Test::SimulatorPostProcessors::Submit < Rtml::Test::SimulatorPostProcessors::Base
+  affects 'Rtml::Test::Simulator', 'simulator'
+  entry_point :check_submit_directive
+
+  def check_submit_directive
+    if submit = on_current_screen("submit").first
+      target = submit['tgt']
+      getvars = ((submit / "getvar") || []).inject({}) do |hash, getvar|
+        hash[variables.literal_value(getvar['name'])] = variables.literal_value(variables[getvar['name']])
+        hash
+      end
+      parent.post_data variables.literal_value(target), getvars
+    end
+  end
+end

data/lib/rtml/test/spec.rb

@@ -1,14 +1,21 @@
 begin
   require 'webrat'
 rescue LoadError
-  # optional. Or should it be?
+  # optional. Really should be phased out completely.
 end
 
-class RtmlExampleGroup < (defined?(Test::Unit::TestCase) ? Test::Unit::TestCase : Object)
-  extend Spec::Example::ExampleGroupMethods
-  include Spec::Example::ExampleMethods
-  include(Webrat::Matchers) if defined?(Webrat)
-  include(Rtml::Rules::DomValidation)
+module Rtml::Test::Spec
+  class RtmlExampleGroup < (defined?(Test::Unit::TestCase) ? Test::Unit::TestCase : Object)
+    extend Spec::Example::ExampleGroupMethods
+    include Spec::Example::ExampleMethods
+    include(Webrat::Matchers) if defined?(Webrat)
+    include(Rtml::Rules::DomValidation)
+    include Rtml::Test::Spec::Matchers
+  end
 end
 
-Spec::Example::ExampleGroupFactory.register(:rtml, RtmlExampleGroup)
+Spec::Runner.configure do |config|
+  config.include Rtml::Test::Spec::Matchers
+end
+
+Spec::Example::ExampleGroupFactory.register(:rtml, Rtml::Test::Spec::RtmlExampleGroup)

data/lib/rtml/test/spec/matchers.rb

@@ -0,0 +1,24 @@
+module Rtml::Test::Spec::Matchers
+  class ResemblanceMatcher
+    def initialize(expected_hash)
+      @expected_hash = expected_hash
+    end
+
+    def matches?(target)
+      @test = Rtml::Test::ResemblanceTest.new(@expected_hash, target)
+      @test.pass?
+    end
+
+    def failure_message
+      "Expected to resemble #{@expected_hash.inspect}; found:\n#{@test.tml}"
+    end
+
+    def negative_failure_message
+      "Expected to not resemble #{@expected_hash.inspect}; found:\n#{@test.tml}"
+    end
+  end
+
+  def resemble_tml(expectation)
+    Rtml::Test::Spec::Matchers::ResemblanceMatcher.new(expectation)
+  end
+end

data/lib/rtml/test/tml_application.rb

@@ -0,0 +1,331 @@
+# Loads a TML application and performs automated processing when told to do so.
+#
+# Note that at any given time, the "current" screen has already been processed. For
+# example, calling #current_screen immediately after loading a document will
+# return the first screen that appears in the document, but that screen will have
+# already been processed. When you call #step or #continue, the next screen will
+# be processed, and calling #current_screen again will return the name of that screen.
+#
+# Whenever user input would be required, the program halts, waiting for you to
+# simulate that input. This class does not provide a direct interface to simulating
+# user interaction; instead you should set the related variables if applicable, and
+# jump directly to the desired screen.
+#
+# For a proper high-level simulator that allows you to call methods like #follow_link
+# and #swipe_card, see Rtml::Test::Simulator instead.
+#
+# It is important to bear in mind that for the purposes of this class, "user input"
+# refers to anything that can't be calculated directly, such as EMV app selection.
+#
+class Rtml::Test::TmlApplication
+  include Rtml::Test::BuiltinVariables
+  class SimulationError < StandardError; end
+
+  # A list of TML elements which generally require user input. This doesn't count
+  # elements that *optionally* require input such as +variant+ -- only those that
+  # usually *require* input such as card parser.
+  USER_INPUT_ELEMENTS = %w(card form submit print)
+
+  attr_reader :screenflow, :variable_scope, :receipt
+
+  # accepts the raw TML document.
+  def initialize(tml)
+    @tml = Hpricot::XML(tml)
+    @variable_scope = Rtml::Test::VariableScope.new
+    @screenflow = []
+    @receipt = Receipt.new
+    declare_variables!
+  end
+
+  def screens
+    @screens ||= ((@tml / "screen") || [])
+  end
+
+  def current_screen_id
+    current_screen ? current_screen['id'] : nil
+  end
+
+  def current_screen
+    return @current_screen if defined?(@current_screen)
+    raise SimulationError, "No screens in current document" if screens.empty?
+    @current_screen = Rtml::Test::Screen.new(screens.first)
+    process_current_screen!
+    @current_screen
+  end
+
+  def stop_execution!
+    @current_screen = nil
+  end
+
+  # Returns true if user input is expected at this time. If true, program flow will not proceed.
+  def waiting_for_input?
+    current_screen.input?
+  end
+
+  # Takes a single "step" in the execution of the program. This has no effect and
+  # returns :waiting if user input is required.
+  #
+  # A step is taken even if the #current_state is :looping, so this can be used to force
+  # execution even if #continue normally wouldn't proceed.
+  #
+  # Returns the ID of the current screen as a string otherwise.
+  def step
+    return current_state if ![:running, :looping].include?(current_state)
+    perform_step!
+  end
+
+  # Like #step, except that user interaction is ignored as if the user had just pressed
+  # the "enter" button.
+  def step_forward
+    return current_state if ![:running, :looping, :waiting, :display].include?(current_state)
+    perform_step!(:ignore_interaction => true)
+  end
+
+  def current_state
+    if current_screen.nil?
+      :stopped
+    elsif waiting_for_input?
+      :waiting
+    elsif looping?
+      :looping
+    elsif displaying_content? && !timeout?
+      :display
+    else
+      :running
+    end
+  end
+
+  def timeout?
+    current_screen.timeout > 0
+  end
+
+  def displaying_content?
+    current_screen.display?
+  end
+
+  # Processes screens until a non-running state is achieved, and
+  # then returns that state.
+  #
+  # If :breakpoint is specified, execution will be suspended at the specified screen and
+  # :break will be returned.
+  #
+  # If :ignore_display is specified, then execution will continue past any <display> elements
+  # that would normally cause execution to halt. Normally, this only occurs if there is a
+  # timeout on the screen displaying the content, since a timeout implies automatic
+  # progression.
+  def continue(options = {})
+    options = { :breakpoint => options } unless options.kind_of?(Hash)
+    breakpoint = options.delete(:breakpoint)
+    breakpoint = breakpoint.to_s if breakpoint && !breakpoint.kind_of?(String)
+    ignore_display = options.delete(:ignore_display)
+    while (state = current_state) == :running || (ignore_display && state == :display)
+      return :break if current_screen_id == breakpoint
+      if ignore_display && state == :display
+        step_forward
+      else
+        step
+      end
+    end
+    return state
+  end
+
+  # Forces execution to continue to the next screen, even if the current screen is waiting
+  # for something to happen.
+  def continue_forward(options = {})
+    continue(options) unless step_forward == :display
+  end
+
+  alias_method :process, :continue
+
+  def jump_to_screen(id)
+    unmemoize!
+    id = id.to_s unless id.kind_of?(String)
+    if id[/^tmlvar:(.*)$/]
+      id = variable_scope[$~[1]]
+    end
+    @current_screen = find_screen(id) || raise(Rtml::Errors::ApplicationError, "Tried to jump to missing screen #{id.inspect}")
+    process_current_screen!
+  end
+
+  def trigger_button_press(which)
+    assert_screen_present
+    which = which.to_s unless which.kind_of?(String)
+    which.downcase!
+    which = 'enter' if which == 'ok'
+
+    if (uri = current_screen.uri_for_hotkey(which))
+      jump_to_uri uri
+    elsif which == 'enter' # a special case: it makes the terminal continue forward under most conditions.
+      if uri = current_screen.autoselect_hyperlink
+        visit uri
+      else
+        continue_forward
+      end
+    elsif (defaults = ((@tml / "defaults") || []).first) && %w(cancel menu).include?(which)
+      jump_to_uri defaults[which]
+    else
+      raise Rtml::Errors::ApplicationError, "Keypress has no effect on screen #{current_screen_id.inspect}"
+    end
+  end
+
+  # If the path resembles a screen name that can be found within the current document, then
+  # #jump_to_screen is called. Otherwise, :new_document is thrown with this path as the argument.
+  #
+  # This is mostly for internal processing, such as for hyperlinks.
+  #
+  # (Does this belong in Rtml::Test::Simulator instead? Time will tell as that class is developed.)
+  #
+  def jump_to_uri(path)
+    if find_screen(path)
+      jump_to_screen path
+    else
+      throw :new_document, path
+    end
+  end
+
+  def find_screen(id)
+    id = id.to_s unless id.kind_of?(String)
+    id = id[1..-1] if id[0] == ?#
+    (screen_element = screens.select { |s| s['id'] == id }.first) ? Rtml::Test::Screen.new(screen_element) : nil
+  end
+
+  # Returns an array containing which of the possible screens following this one meet
+  # the current constraints. If there are no screens available, or if user intervention
+  # is required at this time, then an empty array is returned.
+  #
+  # See also Rtml::Test::Screen#choices
+  #
+  # options may include :ignore_interaction => true/false, defaults to false
+  def destinations(options = {})
+    return @destinations if @destinations
+    return [] if !current_screen.choices.empty? && !options[:ignore_interaction]
+    @destinations = possible_variants.select { |dest| conditions_match?(dest) }
+  end
+
+  # Returns the first element returned by #destinations, or nil if an empty array would
+  # be returned.
+  #
+  # options may include :ignore_interaction => true/false, defaults to false
+  def next_screen_id(options = {})
+    (nxt = destinations(options).first) ? nxt[:uri] : nil
+  end
+
+  # Analyzes a hash as returned by #possible_variants and returns true if the conditions
+  # match the current application state (mostly involving the current value of TML variables).
+  # Conditions based on hotkeys return false since this implies user interaction, and
+  # conditions based on timeouts return true since this implies user interaction never
+  # took place.
+  def conditions_match?(hash)
+    if hash.key?(:hotkey) || hash.key?(:key)
+      false
+    elsif hash.key?(:timeout)
+      true
+    elsif hash.keys == [:uri] # a <next> element should always be true, but evaluated as a last resort
+      true
+    else
+      variable_scope.true_condition?(hash)
+    end
+  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
+    current_screen.possible_variants
+  end
+
+  def declare_variable(name, options = {})
+    variable_scope.declare_variable(name, options)
+  end
+
+  def update_variables(hash)
+    variable_scope.update_with(hash)
+  end
+
+  # Returns true if this application seems to be in an endless loop.
+  def looping?
+    snapshot_matches_previous?
+  end
+  
+  private
+  def assert_screen_present
+    unless current_screen
+      raise Rtml::Errors::ApplicationError,
+            "Could not complete action: no screen. (Has processing been terminated by a dead end?)"
+    end
+  end
+
+  # Called just before moving from one screen to the next, this method sets the various memoized objects
+  # back to nil so that they are re-evaluated for the next screen.
+  def unmemoize!
+    @possible_variants = nil
+    @destinations = nil
+    @current_screen = nil
+  end
+
+  def declare_variables!
+    declare_builtin_variables!
+    (@tml / "vardcl").each do |vardec|
+      options = { }
+      %w(type value format perms).each { |key| options[key] = vardec[key] if vardec[key] }
+      declare_variable(vardec['name'], options)
+    end
+  end
+
+  def process_current_screen!
+    current_screen.setvars.each do |setvar|
+      #screenflow.clear
+      variable_scope.perform_operation_on(setvar['name'],
+                                          {:lo => setvar['lo'], :op => setvar['op'], :ro => setvar['ro']}.optionalize)
+    end
+  end
+
+  # see #step, except no state checking whatsoever is performed.
+  # options may include :ignore_interaction => true/false, defaults to false
+  def perform_step!(options = {})
+    take_snapshot!
+    if next_screen_id(options)
+      jump_to_uri(next_screen_id(options))
+    else # dead end
+      stop_execution!
+    end
+    current_screen_id
+  end
+
+  # Takes a snapshot and stores it in the screenflow.
+  def take_snapshot!
+    screenflow << Snapshot.new(current_screen, variable_scope)
+  end
+
+  # Returns true if a new snapshot would be identical to any previous snapshot.
+  def snapshot_matches_previous?
+    screenflow.include?(Snapshot.new(current_screen, variable_scope))
+  end
+
+  class Snapshot
+    attr_reader :screen, :variables
+    
+    def initialize(screen, variables)
+      @screen = screen
+      @variables = variables.snapshot
+    end
+
+    def ==(a_snapshot)
+      @screen == a_snapshot.screen && @variables == a_snapshot.variables
+    end
+  end
+
+  class Receipt < String
+    def clear
+      replace("")
+    end
+  end
+end