tryouts 0.4.0

data/lib/tryouts/mixins/hash.rb

@@ -0,0 +1,25 @@
+
+class Hash
+  
+  # A depth-first look to find the deepest point in the Hash. 
+  # The top level Hash is counted in the total so the final
+  # number is the depth of its children + 1. An example:
+  # 
+  #     ahash = { :level1 => { :level2 => {} } }
+  #     ahash.deepest_point  # => 3
+  #
+  def deepest_point(h=self, steps=0)
+    if h.is_a?(Hash)
+      steps += 1
+      h.each_pair do |n,possible_h|
+        ret = deepest_point(possible_h, steps)
+        steps = ret if steps < ret
+      end
+    else
+      return 0
+    end
+    steps
+  end
+
+end
+

data/lib/tryouts/mixins.rb

@@ -0,0 +1,2 @@
+
+require "tryouts/mixins/hash"

data/lib/tryouts/tryout.rb

@@ -0,0 +1,171 @@
+
+class Tryouts
+  
+  # = Tryout
+  #
+  # A Tryout is a set of drills (each drill is a test). 
+  #
+  class Tryout
+  
+    # The name of this tryout
+  attr_reader :name
+  
+    # A Hash of Dream objects for this Tryout. The keys are drill names. 
+  attr_accessor :dreams
+  
+    # An Array of Drill objects
+  attr_reader :drills
+  
+    # A default value for Drill.dtype
+  attr_reader :dtype
+  
+    # For drill type :cli, this is the name of the command to test. It
+    # should be a valid method available to a Rye::Box object.
+    # For drill type :api, this attribute is ignored. 
+  attr_reader :command
+  
+    # A block to executed one time before starting the drills
+  attr_reader :setup
+  
+    # A block to executed one time before starting the drills
+  attr_reader :clean
+  
+  @@valid_dtypes = [:cli, :api]
+  
+  # All :api Drills are run within this context (not used for :cli). 
+  # Each Drill is executed in a new instance of this class. That means
+  # instance variables are not carried through, but class variables are. 
+  # The before and after blocks are also run in this context.
+  class DrillContext; end
+     
+  def initialize(name, dtype, command=nil, *args)
+    raise "Must supply command for dtype :cli" if dtype == :cli && command.nil?
+    raise "#{dtype} is not a valid drill type" if !@@valid_dtypes.member?(dtype)
+    @name, @dtype, @command = name, dtype, command
+    @drills = []
+    @dreams = {}
+  end
+  
+  ## ---------------------------------------  EXTERNAL API  -----
+  
+  # Populate this Tryout from a block. The block should contain calls to 
+  # the external DSL methods: dream, drill, xdrill
+  def from_block(b=nil, &inline)
+    runtime = b.nil? ? inline : b
+    instance_eval &runtime
+  end
+  
+  # Execute all Drill objects
+  def run
+    update_drills!   # Ensure all drills have all known dreams
+    DrillContext.class_eval &setup if setup.is_a?(Proc)
+    puts Tryouts::TRYOUT_MSG % @name
+    @drills.each do |drill|
+      drill.run(DrillContext.new)      # Returns true or false
+    end
+    DrillContext.class_eval &clean if clean.is_a?(Proc)
+  end
+  
+  # Prints error output. If there are no errors, it prints nothing. 
+  def report
+    return true if success?
+    failed = @drills.select { |d| !d.success? }
+    failed.each_with_index do |drill,index|
+      
+      puts '%sERROR %2d/%-2d in "%s"' % [$/, index+1, failed.size, drill.name]
+      
+      if drill.dream
+        puts '%24s: %s (expected %s)' % ["response code", drill.reality.rcode, drill.dream.rcode]
+        puts '%24s: %s' % ["expected output", drill.dream.output.inspect]
+        puts '%24s: %s' % ["actual output", drill.reality.output.inspect]
+        if drill.reality.emsg || (drill.reality.emsg != drill.dream.emsg)
+          puts '%24s: %s' % ["expected error msg", drill.dream.emsg.inspect]
+            puts '%24s: %s' % ["actual error msg", drill.reality.emsg.inspect]
+        end
+      else
+        puts '%24s' % ["[nodream]"]
+        if drill.reality.rcode > 0
+          puts '%24s: %s' % ["rcode", drill.reality.rcode.inspect]
+          puts '%24s: %s' % ["msg", drill.reality.emsg.inspect]
+        end
+      end
+      
+      if drill.reality.rcode > 0
+        puts '%24s: ' % ["backtrace"]
+        puts drill.reality.backtrace, $/
+      end
+    end
+    false
+  end
+  
+  # Did every Tryout finish successfully?
+  def success?
+    return @success unless @success.nil?
+    # Returns true only when every Tryout result returns true
+    @success = !(@drills.collect { |r| r.success? }.member?(false))
+  end
+  
+  # Add a Drill object to the list for this Tryout. If there is a dream
+  # defined with the same name as the Drill, that dream will be given to
+  # the Drill before its added to the list. 
+  def add_drill(d)
+    d.add_dream @dreams[d.name] if !@dreams.nil? && @dreams.has_key?(d.name)
+    drills << d if d.is_a?(Tryouts::Drill)
+    d
+  end
+  
+  # Goes through the list of Drill objects (@drills) and gives each 
+  # one its associated Dream object (if available). 
+  # 
+  # This method is called before Tryout#run, but is only necessary in  
+  # the case where dreams where loaded after the drills were defined. 
+  def update_drills!
+    return if @dreams.nil?
+    @drills.each do |drill|
+      next unless @dreams.has_key?(drill.name)
+      drill.add_dream @dreams[drill.name]
+    end
+  end
+  
+  ## ---------------------------------------  EXTERNAL DSL  -----
+  
+  # A block to executed one time _before_ starting the drills
+  def setup(&block)
+    return @setup unless block
+    @setup = block
+  end
+  
+  # A block to executed one time _after_ the drills
+  def clean(&block)
+    return @clean unless block
+    @clean = block
+  end
+  
+  # +name+ of the Drill associated to this Dream
+  # +output+ A String or Array of expected output. A Dream object will be created using this value (optional)
+  # +definition+ is a block which will be run on an instance of Dream
+  #
+  # NOTE: This method is DSL-only. It's not intended to be used in OO syntax. 
+  def dream(name, output=nil, format=nil, rcode=0, emsg=nil, &definition) 
+    if output.nil?
+      dobj = Tryouts::Drill::Dream.from_block definition
+    else
+      dobj = Tryouts::Drill::Dream.new(output)
+      dobj.format, dobj.rcode, dobj.emsg = format, rcode, emsg
+    end
+    @dreams[name] = dobj
+    dobj
+  end
+
+  # Create and add a Drill object to the list for this Tryout
+  # +name+ is the name of the drill. 
+  # +args+ is sent directly to the Drill class. The values are specific on the Sergeant.
+  def drill(name, *args, &definition)
+    args.unshift(@command) if @dtype == :cli
+    drill = Tryouts::Drill.new(name, @dtype, *args, &definition)
+    add_drill drill
+  end
+  def xdrill(*args, &b); end # ignore calls to xdrill
+  
+  
+end; end

data/lib/tryouts.rb

@@ -0,0 +1,386 @@
+
+require 'rubygems'
+require 'ostruct'
+require 'rye'
+require 'yaml'
+begin; require 'json'; rescue LoadError; end   # json may not be installed
+
+GYMNASIUM_HOME = File.join(Dir.pwd, 'tryouts')
+GYMNASIUM_GLOB = File.join(GYMNASIUM_HOME, '**', '*_tryouts.rb')
+
+
+# = Tryouts
+# 
+# This class has three purposes:
+# * It represents the Tryouts object which is a group of Tryout objects. 
+# * The tryouts and dreams DSLs are executed within its namespace. In general the 
+#   class methods are the handlers for the DSL syntax (some instance getter methods 
+#   are modified to support DSL syntax by acting like setters when given arguments)
+# * It stores all known instances of Tryouts objects in a class variable @@instances.
+#
+# ==== Are you ready to run some drills?
+#
+# May all your dreams come true!
+#
+class Tryouts
+  # = Exception
+  # A generic exception which all other Tryouts exceptions inherit from.
+  class Exception < RuntimeError; end
+  # = BadDreams
+  # Raised when there is a problem loading or parsing a Tryouts::Drill::Dream object
+  class BadDreams < Exception; end
+  
+  VERSION = "0.4.0"
+  
+  require 'tryouts/mixins'
+  require 'tryouts/tryout'
+  require 'tryouts/drill'
+  
+  require 'tryouts/orderedhash'
+  HASH_TYPE = (RUBY_VERSION =~ /1.9/) ? ::Hash : Tryouts::OrderedHash
+  
+  TRYOUT_MSG = "\n  %s "
+  DRILL_MSG  = ' %30s: '
+  DRILL_ERR  = '  %s: '
+  
+    # An Array of +_tryouts.rb+ file paths that have been loaded.
+  @@loaded_files = []
+    # An Hash of Tryouts instances stored under the name of the Tryouts subclass. 
+  @@instances = HASH_TYPE.new
+  
+    # The name of this group of Tryout objects
+  attr_accessor :group
+    # A Symbol representing the default drill type. One of: :cli, :api
+  attr_accessor :dtype
+    # An Array of file paths which populated this instance of Tryouts
+  attr_accessor :paths
+    # A Hash of dreams for all tryouts in this class. The keys should
+    # match the names of each tryout. The values are hashes will drill
+    # names as keys and response
+  attr_accessor :dreams
+    # An Array of Tryout objects
+  attr_accessor :tryouts
+    # A Symbol representing the command taking part in the tryouts. For @dtype :cli only. 
+  attr_accessor :command
+    # A Symbol representing the name of the library taking part in the tryouts. For @dtype :api only.
+  attr_accessor :library
+    # The name of the most recent dreams group (see self.dream)
+  attr_accessor :dream_pointer
+  
+  # Returns +@@instances+
+  def self.instances; @@instances; end
+
+  def initialize(group=nil)
+    @group = group || "Default Group"
+    @tryouts = HASH_TYPE.new
+    @paths = []
+    @command = nil
+    @dreams = HASH_TYPE.new
+    @dream_pointer = nil
+  end
+  
+  # Populate this Tryouts from a block. The block should contain calls to 
+  # the external DSL methods: tryout, command, dreams
+  def from_block(b, &inline)
+    instance_eval &b
+  end
+  
+  # Execute Tryout#report for each Tryout in +@tryouts+
+  def report
+    successes = []
+    @tryouts.each_pair { |n,to| successes << to.report }
+    puts $/, "All your dreams came true" unless successes.member?(false)
+  end
+  
+  # Execute Tryout#run for each Tryout in +@tryouts+
+  def run; @tryouts.each_pair { |n,to| to.run }; end
+  
+  # Add a shell command to Rye::Cmd and save the command name
+  # in @@commands so it can be used as the default for drills
+  def command(name=nil, path=nil)
+    return @command if name.nil?
+    @command = name.to_sym
+    @dtype = :cli
+    Rye::Cmd.module_eval do
+      define_method(name) do |*args|
+        cmd(path || name, *args)
+      end
+    end
+    @command
+  end
+  # Calls Tryouts#command on the current instance of Tryouts
+  #
+  # NOTE: this is a standalone DSL-syntax method. 
+  def self.command(*args)
+    @@instances.last.command(*args)
+  end
+  
+  
+  # Require +name+. If +path+ is supplied, it will "require path". 
+  # * +name+ The name of the library in question (required). Stored as a Symbol to +@library+.
+  # * +path+ Add a path to the front of $LOAD_PATH (optional). Use this if you want to load
+  # a specific copy of the library. Otherwise, it loads from the system path.
+  def library(name=nil, path=nil)
+    return @library if name.nil?
+    @library = name.to_sym
+    @dtype = :api
+    $LOAD_PATH.unshift path unless path.nil?
+    require @library.to_s
+  end
+  # Calls Tryouts#library on the current instance of Tryouts
+  #
+  # NOTE: this is a standalone DSL-syntax method.
+  def self.library(*args)
+    @@instances.last.library(*args)
+  end
+  
+  def group(name=nil)
+    return @group if name.nil?
+    @group = name unless name.nil?
+    # Preload dreams if possible
+    dfile = self.class.find_dreams_file(GYMNASIUM_HOME, @group)
+    self.load_dreams_file(dfile) if dfile
+    @group
+  end
+  # Raises a Tryouts::Exception. +group+ is not support in the standalone syntax
+  # because the group name is taken from the name of the class. See inherited. 
+  #
+  # NOTE: this is a standalone DSL-syntax method.
+  def self.group(*args)
+    raise "Group is already set: #{@@instances.last.group}"
+  end
+  
+  # Create a new Tryout object and add it to the list for this Tryouts class. 
+  # * +name+ is the name of the Tryout
+  # * +type+ is the default drill type for the Tryout. One of: :cli, :api
+  # * +command+ when type is :cli, this is the name of the Rye::Box method that we're testing. Otherwise ignored. 
+  # * +b+ is a block definition for the Tryout. See Tryout#from_block
+  #
+  # NOTE: This is a DSL-only method and is not intended for OO use. 
+  def tryout(name, dtype=nil, command=nil, &block)
+    return if name.nil?
+    dtype ||= @dtype
+    command ||= @command if dtype == :cli
+    to = find_tryout(name, dtype)
+    if to.nil?
+      to = Tryouts::Tryout.new(name, dtype, command)
+      @tryouts[name] = to
+    end
+    # Populate the dreams if they've already been loaded
+    to.dreams = @dreams[name] if @dreams.has_key?(name)
+    # Process the rest of the DSL
+    to.from_block block if block
+    to
+  end
+  # Calls Tryouts#tryout on the current instance of Tryouts
+  #
+  # NOTE: this is a standalone DSL-syntax method.
+  def self.tryout(*args, &block)
+    @@instances.last.tryout(*args, &block)
+  end
+
+  # Find matching Tryout objects by +name+ and filter by 
+  # +dtype+ if specified. Returns a Tryout object or nil.
+  def find_tryout(name, dtype=nil)
+    by_name = @tryouts.values.select { |t| t.name == name }
+    by_name = by_name.select { |t| t.dtype == dtype } if dtype
+    by_name.first  # by_name is an Array. We just want the Object. 
+  end
+  
+  # This method does nothing. It provides a quick way to disable a tryout.
+  #
+  # NOTE: This is a DSL-only method and is not intended for OO use.
+  def xtryout(*args, &block); end
+  # This method does nothing. It provides a quick way to disable a tryout.
+  #
+  # NOTE: this is a standalone DSL-syntax method.
+  def self.xtryout(*args, &block); end
+  
+  # Load dreams from a file or directory or if a block is given
+  # it's processed 
+  # Raises a Tryouts::BadDreams exception when something goes awry. 
+  #
+  # This method is used in two ways:
+  # * In the dreams file DSL
+  # * As a getter method on a Tryouts object
+  def dreams(tryout_name=nil, &definition)
+    return @dreams unless tryout_name
+
+    #
+    # dreams "path/2/dreams"
+    #  OR
+    # dreams "path/2/file_of_dreams.rb"
+    #
+    if File.exists?(tryout_name)
+      dfile = tryout_name
+      # If we're given a directory we'll build the filename using the class name
+      if File.directory?(tryout_name)
+        dfile = self.class.find_dreams_file(tryout_name, @group) 
+      end
+      raise BadDreams, "Cannot find dreams file (#{tryout_name})" unless dfile
+      @dreams = load_dreams_file( dfile) || {}
+    
+    #
+    # dreams "Tryout Name" do
+    #   dream "drill name" ...
+    # end
+    #
+    elsif tryout_name.kind_of?(String) && definition  
+      to = find_tryout(tryout_name, @dtype)
+      
+      if to.nil?
+        @dream_pointer = tryout_name  # Used in Tryouts.dream
+        @dreams[ @dream_pointer ] ||= {}
+        definition.call
+      else
+        to.from_block &definition
+      end
+    else
+      raise BadDreams, tryout_name
+    end
+    @dreams
+  end
+  # Without arguments, returns a Hash of all known dreams.
+  # With arguments, it calls Tryouts#dreams on the current instance of Tryouts. 
+  #
+  # NOTE: this is a standalone DSL-syntax method.
+  def self.dreams(*args, &block)
+    if args.empty? && block.nil?
+      dreams = {}
+      @@instances.each_pair do |name,inst|
+        dreams[name] = inst.dreams
+      end
+      return dreams
+    else
+      # Call the Tryouts#dreams instance method
+      @@instances.last.dreams(*args, &block)
+    end
+  end
+  
+  # +name+ of the Drill associated to this Dream
+  # +output+ A String or Array of expected output. A Dream object will be created using this value (optional)
+  # +definition+ is a block which will be run on an instance of Dream
+  #
+  # This method is different than Tryout#dream because this one stores
+  # dreams inside an instance variable of the current Tryouts object.
+  # This allows for the situation where the dreams block appears before
+  # the tryout block. See Tryouts#tryout
+  #
+  # NOTE: This method is DSL-only. It's not intended to be used in OO syntax. 
+  def dream(name, output=nil, format=nil, rcode=0, emsg=nil, &definition)
+    to = find_tryout(@dream_pointer, @dtype)
+    if to.nil?
+      if output.nil?
+        dobj = Tryouts::Drill::Dream.from_block definition
+      else
+        dobj = Tryouts::Drill::Dream.new(output)
+        dobj.format, dobj.rcode, dobj.emsg = format, rcode, emsg
+      end
+      @dreams[@dream_pointer][name] = dobj
+    else
+      # Let the Tryout object process the dream DSL.
+      # We'll get here if the dream is placed after 
+      # the drill with the same name in the same block.
+      to.dream name, output, format, rcode, emsg, &definition
+    end
+  end
+  # Calls Tryouts#dream on the current instance of Tryouts
+  #
+  # NOTE: this is a standalone DSL-syntax method.
+  def self.dream(*args, &block)
+    @@instances.last.dream(*args, &block)
+  end
+  
+  # Populate @@dreams with the content of the file +dpath+. 
+  #
+  # NOTE: this is an OO syntax method
+  def load_dreams_file(dpath)
+    type = File.extname dpath
+    if type == ".yaml" || type == ".yml"
+      @dreams = YAML.load_file dpath
+    elsif type == ".json" || type == ".js"
+      @dreams = JSON.load_file dpath
+    elsif type == ".rb"
+      @dreams = instance_eval File.read(dpath)
+    else
+      raise BadDreams, "Unknown kind of dream: #{dpath}"
+    end
+    @dreams
+  end
+  
+  # Parse a +_tryouts.rb+ file. See Tryouts::CLI::Run for an example. 
+  #
+  # NOTE: this is an OO syntax method
+  def self.parse_file(fpath)
+    raise "No such file: #{fpath}" unless File.exists?(fpath)
+    file_content = File.read(fpath)
+    to = Tryouts.new
+    to.instance_eval file_content, fpath
+    if @@instances.has_key? to.group
+      to = @@instances[to.group]
+      to.instance_eval file_content, fpath
+    end
+    to.paths << fpath
+    @@instances[to.group] = to
+  end
+  
+  # Run all Tryout objects in +@tryouts+
+  #
+  # NOTE: this is an OO syntax method
+  def self.run
+    @@instances.each_pair do |group, inst|
+      inst.tryouts.each_pair do |name,to|
+        to.run
+        to.report
+        STDOUT.flush
+      end
+    end
+  end
+  
+  # Called when a new class inherits from Tryouts. This creates a new instance
+  # of Tryouts, sets group to the name of the new class, and adds the instance
+  # to +@@instances+. 
+  #
+  # NOTE: this is a standalone DSL-syntax method.
+  def self.inherited(klass)
+    to = @@instances[ klass ]
+    to ||= Tryouts.new
+    to.paths << __FILE__
+    to.group = klass
+    @@instances[to.group] = to
+  end
+  
+  
+  ##---
+  ## Is this wacky syntax useful for anything?
+  ##    t2 :set .
+  ##       run = "poop"
+  ## def self.t2(*args)
+  ##   OpenStruct.new
+  ## end
+  ##+++
+  
+  # Find a dreams file in the directory +dir+ based on the current group name.
+  # The expected filename format is: groupname_dreams.ext where "groupname" is
+  # the lowercase name of the Tryouts group (spaces removed) and "ext" is one 
+  # of: yaml, js, json, rb. 
+  #
+  #     e.g.
+  #     Tryouts.find_dreams_file "dirpath"   # => dirpath/tryouts_dreams.rb
+  #
+  def self.find_dreams_file(dir, group=nil)
+    dpath = nil
+    group ||= @@instances.last.group
+    group = group.to_s.downcase.tr(' ', '')
+    [:rb, :yaml].each do |ext|
+      tmp = File.join(dir, "#{group}_dreams.#{ext}")
+      if File.exists?(tmp)
+        dpath = tmp
+        break
+      end
+    end
+    dpath
+  end
+  
+
+end

data/tryouts/mockoutcli_dreams.rb

@@ -0,0 +1,19 @@
+
+dreams "Common Usage" do
+  dream "No args" do
+    output inline(%Q{
+         Date:                                   2009-02-16
+       Owners:            greg, rupaul, telly, prince kinko
+      Players:            d-bam, alberta, birds, condor man
+    })
+  end
+  dream "YAML Output" do
+    format :yaml
+    output ({
+      "Date" => "2009-02-16",
+      "Players" => ["d-bam", "alberta", "birds", "condor man"],
+      "Owners" => ["greg", "rupaul", "telly", "prince kinko"]
+    })
+  end
+end
+

data/tryouts/mockoutcli_dreams.yaml

@@ -0,0 +1,10 @@
+common usage: 
+  yaml output: 
+    :format: :yaml
+    :rcode: 0
+  no args: 
+    :rcode: 0
+    :output: 
+    - "    Date:                                   2009-02-16\n"
+    - " Players:            d-bam, alberta, birds, condor man\n"
+    - " Coaches:               greg|rupaul|telly|prince kinko\n"

data/tryouts/mockoutcli_tryouts.rb

@@ -0,0 +1,26 @@
+
+TRYOUTS_HOME = File.expand_path(File.join(File.dirname(__FILE__), ".."))
+MOCKOUT_PATH = File.join(TRYOUTS_HOME, "bin", "mockout")
+
+group "mockout cli"
+command :mockout, MOCKOUT_PATH
+
+tryout "Common Usage" do
+  drill  "No Command"
+  drill     "No args",            :info
+  drill "YAML Output", :f, :yaml, :info
+  drill "JSON Output", :f, :json, :info
+end
+
+tryout "inline dream that passes", :cli, :mockout do
+  output = ["we expect mockout to", "echo these lines back"]
+
+  # $ bin/mockout sergeant -e "we expect mockout to" "echo these lines back"
+  drill "echo arguments", :info, :e, output[0], output[1]
+  dream "echo arguments", output
+end
+
+tryout "inline dream that fails", :cli, :mockout do
+  dream "echo arguments", "The dream does"
+  drill "echo arguments", :info, :e, "not match reality"
+end