graffle 0.1.8 → 0.1.9

data/lib/graphical_tests_for_rails/picture-appliers.rb

@@ -0,0 +1,225 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-21.
+#  Copyright (c) 2007. All rights reserved.
+
+require 'enumerator'
+require 'test/unit/assertionfailederror'
+require 'fluid'
+require 'graphical_tests_for_rails/text-appliers'
+require 'graphical_tests_for_rails/volunteer-pool'
+
+
+module GraphicalTestsForRails
+
+  # A PictureApplier takes an array of graphics and arranges for 
+  # messages derived from them to be sent to a _target_. PictureAppliers
+  # are "programmed" with other objects that handle the details of 
+  # transforming graphics and the text they contain into messages. 
+  #
+  # The 
+  # graphics are processed in order. GraphicOrderer objects should be
+  # used to arrange the array before it's given to PictureApplier.
+  class PictureApplier
+    include Graffle
+    include GraphicalTestsForRails::TextAppliers
+    
+    # The block tells the PictureApplier what to do by sending given,
+    # matching, use, and skip messages. That looks like this:
+    #
+    #  PictureApplier.new {
+    #    given('note').matching('ignore').skip
+    #    given('shaped graphic content').use(ArgsFromQuotedText.new)
+    #  }
+    #
+    # Each declaration sees if it can match a graphical object. If so,
+    # the last action is performed. Declarations are processed in 
+    # order, so one match can be given precedence. Consider this:
+    #
+    #   PictureApplier.new {
+    #     given('note').matching('ignore').skip
+    #     given('shaped graphic content').use(ArgsFromQuotedText.new)
+    #   }
+    #
+    # This means that shaped graphic objects irrelevant to the test
+    # can be ignored by attaching the appropriate annotation.
+    
+    def initialize(&block)
+      @universe = GraphicVolunteerPool.new
+      @mobilized = []
+      instance_eval(&block) if block
+      @mobilized << EagerButUselessVolunteer.new
+    end
+
+    # Claim that the PictureApplier matches graphics matching
+    # the _form_description_, a string. Here are the form descriptions 
+    # currently supported:
+    #
+    # * 'shaped graphic content': A shaped graphic is a rectangle, oval, 
+    #   embedded picture, etc.: anything that is neither a line nor a 
+    #   group. The content is the text you type in when you double-click
+    #   on the object. When given the form description, the PictureApplier
+    #   will match any shaped graphic that contains text.
+    # * 'line label content': This matches any line that has a label.
+    #   (Note: lines can have more than one label. That's not handled.)
+    # * 'note': Matches any object that contains an annotation. (Annotations are
+    #   only available in OmniGraffle Pro. They're arbitrary text
+    #   associated with a line or shaped graphic. You can see the 
+    #   annotations if you hover over the object.)
+    #
+    # The _form_description_ describes the first of two matching steps.
+    # If it matches, it extracts the appropriate text (content or 
+    # annotation) and hands it to the next step, described by given.
+    #
+    # This method returns self so that other methods can be chained onto it.
+    def given(form_description)
+      @mobilized << @universe.mobilize_form_watcher(form_description)
+      self
+    end
+    
+    # Claim that the PictureApplier matches particular text extracted from
+    # a graphical object. These _text_descriptions_ are currently supported:
+    #
+    # * 'text...': match if the text ends in ellipses (ignoring whitespace).
+    # * 'ignore': match if the text ends in the word "ignore" (ignoring whitespace).
+    #
+    # This method returns self so that other methods can be chained onto it.
+    def matching(text_description)
+      @mobilized.last.next = @universe.mobilize_content_watcher(text_description)
+      self
+    end
+    
+    # When a PictureApplier matches an object, the extracted text is 
+    # passed to the _text_applier_ to be turned into messages.
+    def use(text_applier)
+      @mobilized.last.text_applier = text_applier
+    end
+    
+    # After a PictureApplier matches a graphical object, it's ignored. 
+    # This is used to prevent text associated with the object from being
+    # turned into messages.
+    def skip
+      use(TextApplierThatDoesNothing.new)
+    end
+
+    # After the PictureApplier has been programmed, this method 
+    # applies it to the _graphics_, resulting in methods that are sent
+    # to the _target_. 
+    #
+    # If there's a problem, a log of what was sent to the _target_ is 
+    # included in the exception message. The _log_ can be started out with 
+    # the third argument, in which case new entries are appended. This can 
+    # be useful when a single test is made up of several graphics lists.
+    def apply(graphics, target, log=[])
+      while_logging_for_test_errors(log) do
+        graphics.each { |g| find_volunteer_for(g).apply(g, target) }
+      end
+    end
+
+    # Given a _graphic_ find a GraphicVolunteer that can apply it. 
+    # (Probably not for external use.)
+    def find_volunteer_for(graphic)
+      @mobilized.find { | m | m.likes?(graphic) }
+    end
+
+    private
+
+    def while_logging_for_test_errors(log)
+      Fluid.let(:log, log) do
+        begin
+          yield
+        rescue Test::Unit::AssertionFailedError, StandardError, ScriptError => e
+          new_message = %Q{#{e.message} after\n#{Fluid.log.join("\n")}}
+          new_e = e.exception(new_message)
+          new_e.set_backtrace(e.backtrace)
+          raise new_e
+        end
+      end
+    end
+  end
+  
+  # This class is deprecated. See PictureApplier.
+  #
+  # A GraphicInterpreter takes a list of _graphics_, some 
+  # instructions about how to interpret them, and a _target_.
+  # It interprets the instructions to create messages that it then 
+  # sends to the target.
+  #
+  class GraphicInterpreter
+
+    # The _graphics_ are an array of OmniGraffle Graffle::AbstractGraphic objects. The 
+    # _instructions_ map a string to an object that must respond to 
+    # message_and_args_from. (See AbstractTextApplier#message_and_args_from
+    # for more.)
+    #
+    # Here are the available instructions (keys in _instructions_):
+    #
+    # * ['line labels' => ...]: each line within the (single)
+    #   label on the line is to be interpreted as a message-send by an 
+    #   instance of the given class.
+    # * ['shaped graphic text' => ...]: each line of content
+    #   within the graphic is to be interpreted by the given class. The 
+    #   content is the text you type in an object after double-clicking
+    #   on it.
+    # * ['text...' => ...]: a line ending in ellipses is treated this way,
+    #   no matter what other instructions say. 
+    #
+    def initialize(graphics, instructions = {})
+      puts "Warning: #{self.class} is deprecated. Use PictureApplier instead."
+      @graphics = graphics
+      @line_label_strategy = 
+          instructions['line labels'] 
+      @shaped_graphic_text_strategy = 
+          instructions['shaped graphic text']
+          
+      @ellipses_override = instructions['text...']
+    end
+    
+    # Apply the _graphics_, according to the _instructions_, against
+    # the _target_.
+    def run_against(target)
+      @target = target
+      @log = []
+      @graphics.each do |g|
+        case g.stereotype.basename
+        when "ShapedGraphic"
+          process_commands(@shaped_graphic_text_strategy,
+                           g.content.as_lines)
+        when "LineGraphic"
+          process_commands(@line_label_strategy,
+                           g.label_lines)
+        end
+      end
+    end
+        
+    private
+    
+    def process_commands(text_applier, command_lines)
+      return if text_applier.nil?
+      command_lines.each do |line|
+        info = if /\.\.\.\s*$/ =~ line && @ellipses_override
+                 @ellipses_override.message_and_args_from(line)
+               else
+                 text_applier.message_and_args_from(line)
+               end
+        begin
+          @log << readable(*info)
+          @target.send(*info)
+        rescue Test::Unit::AssertionFailedError, StandardError, ScriptError => e
+          new_message = %Q{#{e.message} after\n#{@log.join("\n")}}
+          new_e = e.exception(new_message)
+          new_e.set_backtrace(e.backtrace)
+          raise new_e
+        end
+      end    
+    end
+    
+    def readable(message, *args)
+      inspected = args.collect { |a| a.inspect }
+      "+ #{message}(#{inspected.join(', ')})"
+    end
+      
+  end
+  
+end
+

data/lib/graphical_tests_for_rails/text-appliers.rb

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-21.
+#  Copyright (c) 2007. All rights reserved.
+
+module GraphicalTestsForRails
+  
+  # Just a wrapper module so that classes are grouped nicely in rdoc.
+  # You don't have to include this - that happens if you require
+  # graphical_tests_for_rails.rb.
+  module TextAppliers
+
+    # This is the base class for objects that know how to convert text
+    # into a series of messages and send them to some target.
+    class AbstractTextApplier
+
+      # apply is given an array of text (_lines_). It is to convert
+      # that text into messages and send them to _target_.
+      #
+      def apply(lines, target)
+        message_sends = lines.collect {|line| message_and_args_from(line) }
+        message_sends.each do |m| 
+          Fluid.log << readable(*m)
+          target.send(*m) 
+        end
+      end
+
+      # message_and_args_from is given a string that is derived from some
+      # text. It must answer an array whose first element is a
+      # message name and whose remaining elements are appropriate message
+      # arguments. Must be defined in any subclass.
+      def message_and_args_from; subclass_responsibility; end
+
+      private
+      def readable(message, *args)
+        inspected = args.collect { |a| a.inspect }
+        "+ #{message}(#{inspected.join(', ')})"
+      end
+
+
+    end
+
+
+    # The arguments to apply are quoted within the _string_. 
+    # The message is the text before the first arg, snake-cased.
+    # For example, this:
+    #    paul logs in with "john", password "j"
+    # means this:
+    #    target.paul_logs_in_with("john", "j")
+    #
+    class ArgsFromQuotedText < AbstractTextApplier
+
+      def message_and_args_from(string)
+        quote_marker = '%<<<==-'
+
+        string = string.gsub(/(\w)'(\w)/, "#{quote_marker}\\1\\2#{quote_marker}")
+        tokens = string.split(/['"],?/, allow_trailing_null_fields = -1)
+        message = tokens[0].strip.downcase
+        args = tokens[1..-1]
+
+
+        message.gsub!(/#{quote_marker}(.)(.)#{quote_marker}/, "\\1\\2")
+        message.gsub!(/\s+/,'_')
+        message.gsub!(/-/, '_')
+        message.gsub!(/\W/, '')
+
+
+        args = args.enum_slice(2).collect { |e| e[0] } 
+        args = args.collect do | arg | 
+          arg.gsub(/#{quote_marker}(.)(.)#{quote_marker}/, "\\1'\\2")
+        end
+
+        [message] + args
+      end
+    end
+
+    # Like ArgsFromQuotedText, but the first word (typically a name)
+    # is downcased and used as the first argument. 
+    # For example, this:
+    #    paul logs in with "john", password "j"
+    # means this:
+    #    target.logs_in_with("paul", "john", "j")
+    #
+
+    class PrefixNameAndArgsFromQuotedText < ArgsFromQuotedText
+      def message_and_args_from(string)
+        user_claims(string =~ /^\s*(\w+)\s+(.*)$/) {
+          "'#{string}' cannot be split into a name and an action."
+        }
+        name = $1.downcase
+        rest = super($2)
+        message = rest.shift
+        [message, name, *rest]
+      end
+
+    end
+
+
+    # This AbstractTextApplier is created with the name of a message.
+    # When handed a string to apply, it downcases and strips the string,
+    # then uses it as the single argument to the method. For example, this:
+    #    applier = TextAsNameOfPage.new("assert_on")
+    #    applier.apply("HOME")
+    # turns into this:
+    #    applier.assert_on("home")
+    class TextAsNameOfPage < AbstractTextApplier
+
+      # When producing a method call, objects of this class will 
+      # prepend the _message_ to
+      # a single argument it constructs.
+      def initialize(message)
+        @message = message
+      end
+
+      # All of the text in the _string_ is expected to be the name 
+      # of a page. It is downcased and treated as the single argument to 
+      # the message passed to +new+.
+      def message_and_args_from(string)
+        [@message, string.downcase.strip]
+      end
+    end
+
+    class TextApplierThatDoesNothing # :nodoc:
+      def message_and_args_from(string) 
+        [:object_id] # no_op
+      end
+
+      def apply(lines, target)
+        # do nothing, don't even bother sending a no-op
+      end
+    end
+
+  end
+  
+end

data/lib/graphical_tests_for_rails/volunteer-pool.rb

@@ -0,0 +1,115 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-21.
+#  Copyright (c) 2007. All rights reserved.
+
+require 'graffle'
+require 'graphical_tests_for_rails/graphic-volunteers'
+
+# TODO: Turn these all into one class.
+module GraphicalTestsForRails
+  
+  # A GraphicVolunteerPool describes the ways a PictureApplier
+  # can by programmed with PictureApplier#given statements.
+  # You only care about this if you want to add new ways to use
+  # Graffle pictures in tests.
+  
+  class GraphicVolunteerPool
+    def initialize
+      @graphic_maker = FormFocusedTemplate.new
+      @text_maker = ContentFocusedTemplate.new
+    end
+    
+    def mobilize_form_watcher(description)
+      @graphic_maker.make_applier(description)
+    end
+
+    def mobilize_content_watcher(description)
+      @text_maker.make_applier(description)
+    end
+
+  end
+  
+  # There are two distinct kinds of Templates only so they 
+  # can produce different error messages.
+  class EmptyTemplate # :nodoc:
+    include Graffle
+
+    def initialize
+      @templates = {}
+    end
+    
+    def proclaim(name)
+      prog1(GraphicVolunteer.new(name)) { | t | @templates[name] = t }
+    end
+    
+    def make_applier(name)
+      t = @templates[name]
+      user_claims(t) {
+          "#{name} must be one of #{@templates.keys.inspect}"
+        }
+      t.dup
+    end
+  end
+  
+  class FormFocusedTemplate < EmptyTemplate # :nodoc:
+    def initialize
+      super
+
+      proclaim('shaped graphic content').handles { | graphic |
+        shaped_graphic_with_content?(graphic)
+      }.and_extracts { | graphic | 
+        graphic.content.as_lines
+      }
+
+      proclaim('line label content').handles { | graphic |
+        line_graphic_with_label_content?(graphic)
+      }.and_extracts { | graphic | 
+          graphic.label_lines
+      }
+
+      proclaim('note').handles { | graphic |
+        graphic_with_note?(graphic)
+      }.and_extracts { | graphic | 
+        graphic_note(graphic)
+      }
+    end
+    
+    private
+    def labeled_line?(graphic)
+      return false unless graphic.behaves_like?(LineGraphic)
+      graphic.has_label?
+    end
+    def shaped_graphic_with_content?(graphic)
+      graphic.behaves_like?(ShapedGraphic) && graphic.has_content?
+    end
+    
+    def line_graphic_with_label_content?(graphic)
+      labeled_line?(graphic) && graphic.label.has_content?
+    end
+    
+    def graphic_with_note?(graphic)
+      return true if graphic.behaves_like?(AbstractGraphic) && graphic.has_note?
+      labeled_line?(graphic) && graphic.label.has_note?
+    end
+    
+    def graphic_note(graphic)
+      return graphic.note.as_lines if graphic.has_note?
+      return graphic.label.note.as_lines
+    end
+  end
+  
+  class ContentFocusedTemplate < EmptyTemplate # :nodoc:
+    def initialize
+      super
+      
+      proclaim('text...').handles { | lines | 
+        lines.join.strip =~ /\.\.+$/
+      }
+      
+      proclaim('ignore').handles do | lines | 
+        lines.any? { |l| l.strip.ends_with?("ignore") }
+      end
+    end
+  end
+end