delano-tryouts 0.4.0

data/lib/tryouts/tryout.rb

@@ -0,0 +1,194 @@
+
+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, &inline)
+    instance_eval &b
+  end
+  
+  # Execute all Drill objects
+  def run
+    update_drills!   # Ensure all drills have all known dreams
+    DrillContext.new.instance_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.new.instance_eval &clean if clean.is_a?(Proc)
+  end
+  
+  # Prints error output. If there are no errors, it prints nothing. 
+  def report
+    if success?
+      puts $/, "All your dreams came true"
+      return
+    end
+    puts $/, "ERRORS:"
+    @drills.each do |drill|
+      next if drill.success?
+      puts Tryouts::DRILL_MSG % drill.name
+      if drill.reality.rcode < 0
+        puts '%24s' % drill.reality.emsg 
+        next
+      end
+      
+      if drill.dream
+        drill.discrepency.each do |d|
+          puts '%24s: %s' % ["dream #{d}", drill.dream.send(d).inspect]
+          puts '%24s: %s' % ["reality #{d}", drill.reality.send(d).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: %s' % ["backtrace", drill.reality.backtrace.inspect]
+      end
+    end
+  end
+  
+  # Did every Tryout finish successfully?
+  def success?
+    # Returns true only when every Tryout result returns true
+    !(@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=:string, 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, &b)
+    args.unshift(@command) if @dtype == :cli
+    drill = Tryouts::Drill.new(name, @dtype, *args, &b)
+    add_drill drill
+  end
+  def xdrill(*args, &b); end # ignore calls to xdrill
+  
+  
+  
+  
+  private
+  
+  # Convert every Hash of dream params into a Tryouts::Drill::Dream object. 
+  # DEPRECATED: This is not used anymore since we have the dreams DSL syntax.
+  def parse_dreams!
+    if @dreams.kind_of?(Hash)
+      #raise BadDreams, 'Not deep enough' unless @@dreams.deepest_point == 2
+      @dreams.each_pair do |tname, drills|
+        drills.each_pair do |dname, dream_params|
+          next if dream_params.is_a?(Tryouts::Drill::Dream)
+          dream = Tryouts::Drill::Dream.new
+          dream_params.each_pair { |n,v| dream.send("#{n}=", v) }
+          @dreams[tname][dname] = dream
+        end
+      end
+    else
+      raise BadDreams, 'Not a kind of Hash'
+    end
+  end
+  
+end; end

data/lib/tryouts.rb

@@ -0,0 +1,334 @@
+
+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'
+  
+  TRYOUT_MSG = "\n     %s "
+  DRILL_MSG  = ' %20s: '
+  
+    # An Hash of Tryouts instances stored under the name of the Tryouts subclass. 
+  @@instances = {}
+    # The most recent tryouts name specified in the DSL
+  @@instance_pointer = nil
+  
+    # The name of this group of Tryout objects
+  attr_accessor :group
+    # An Array of Tryout objects
+  attr_accessor :tryouts
+    # A Hash of Tryout names pointing to index values of :tryouts
+  attr_accessor :map
+    # 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
+    # A Symbol representing the default drill type. One of: :cli, :api
+  attr_accessor :dtype
+  
+    # 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
+    # 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 = []
+    @map = {}
+    @command = nil
+    @dtype = :cli
+    @dreams = {}
+    @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; @tryouts.each { |to| to.report }; end
+  
+  # Execute Tryout#run for each Tryout in +@tryouts+
+  def run; @tryouts.each { |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
+    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[ @@instance_pointer ].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
+    $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[ @@instance_pointer ].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 take 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[ @@instance_pointer ].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, type=nil, command=nil, &block)
+    return if name.nil?
+    type ||= @dtype
+    command ||= @command if type == :cli
+    to = Tryouts::Tryout.new(name, type, command)
+    # 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
+    @tryouts << to
+    @map[name] = @tryouts.size - 1
+    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[ @@instance_pointer ].tryout(*args, &block)
+  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 Hash.
+  # 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 Tryout object
+  def dreams(tryout_name=nil, &definition)
+    return @dreams unless tryout_name
+    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
+    elsif tryout_name.kind_of?(Hash)
+      @dreams = tryout_name
+    elsif tryout_name.kind_of?(String) && definition  
+      @dream_pointer = tryout_name  # Used in Tryouts.dream
+      @dreams[ @dream_pointer ] ||= {}
+      definition.call
+    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
+      @@instances[ @@instance_pointer ].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
+  #
+  #
+  # NOTE: This method is DSL-only. It's not intended to be used in OO syntax. 
+  def dream(name, output=nil, format=:string, 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[@dream_pointer][name] = dobj
+  end
+  # Calls Tryouts#dream on the current instance of Tryouts
+  #
+  # NOTE: this is a standalone DSL-syntax method.
+  def self.dream(*args, &block)
+    @@instances[ @@instance_pointer ].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)
+    to = Tryouts.new
+    to.instance_eval(File.read(fpath), fpath)
+    @@instance_pointer = to.group
+    @@instances[ @@instance_pointer ] = to
+  end
+  
+  # Run all Tryout objects in +@tryouts+
+  #
+  # NOTE: this is an OO syntax method
+  def self.run
+    @@instances.each_pair do |group, inst|
+      puts "-"*60
+      puts "Tryouts for #{group}"
+      inst.tryouts.each do |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 = Tryouts.new
+    to.group = klass
+    @@instance_pointer = to.group
+    @@instances[ @@instance_pointer ] = 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 ||= @@instance_pointer
+    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,11 @@
+common usage: 
+  yaml output: 
+    :format: :yaml
+    :rcode: 0
+  no args: 
+    :format: :string
+    :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

data/tryouts.gemspec

@@ -0,0 +1,75 @@
+@spec = Gem::Specification.new do |s|
+	s.name = "tryouts"
+  s.rubyforge_project = "tryouts"
+	s.version = "0.4.0"
+	s.summary = "Tryouts are high-level tests for your Ruby code. May all your dreams come true!"
+	s.description = s.summary
+	s.author = "Delano Mandelbaum"
+	s.email = "tryouts@solutious.com"
+	s.homepage = "http://github.com/delano/tryouts"
+  
+  # = EXECUTABLES =
+  # The list of executables in your project (if any). Don't include the path, 
+  # just the base filename.
+  s.executables = %w[tryouts]
+  
+  # Directories to extract rdocs from
+  s.require_paths = %w[lib]  
+  
+  # Specific files to include rdocs from
+  s.extra_rdoc_files = %w[README.rdoc LICENSE.txt]
+  
+  # Update --main to reflect the default page to display
+  s.rdoc_options = ["--line-numbers", "--title", "Tryouts: #{s.summary}", "--main", "README.rdoc"]
+  
+  # = DEPENDENCIES =
+  # Add all gem dependencies
+  s.add_dependency 'drydock', '>= 0.6.5'
+  s.add_dependency 'rye', '>= 0.6.6'
+  s.add_dependency 'sysinfo', '>= 0.5.1'
+  
+  # = MANIFEST =
+  # The complete list of files to be included in the release. When GitHub packages your gem, 
+  # it doesn't allow you to run any command that accesses the filesystem. You will get an
+  # error. You can ask your VCS for the list of versioned files:
+  # git ls-files
+  # svn list -R
+  s.files = %w(
+  CHANGES.txt
+  LICENSE.txt
+  README.rdoc
+  Rakefile
+  bin/mockout
+  bin/tryouts
+  lib/tryouts.rb
+  lib/tryouts/cli.rb
+  lib/tryouts/cli/run.rb
+  lib/tryouts/drill.rb
+  lib/tryouts/drill/response.rb
+  lib/tryouts/drill/sergeant/cli.rb
+  lib/tryouts/mixins.rb
+  lib/tryouts/mixins/hash.rb
+  lib/tryouts/tryout.rb
+  tryouts.gemspec
+  tryouts/mockoutcli_dreams.rb
+  tryouts/mockoutcli_dreams.yaml
+  tryouts/mockoutcli_tryouts.rb
+  )
+  
+  s.has_rdoc = true
+  s.rubygems_version = '1.3.0'
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+ 
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<RedCloth>, [">= 4.0.4"])
+    else
+      s.add_dependency(%q<RedCloth>, [">= 4.0.4"])
+    end
+  else
+    s.add_dependency(%q<RedCloth>, [">= 4.0.4"])
+  end
+  
+end