rutema 0.1

data/lib/rutema/system.rb

@@ -0,0 +1,599 @@
+#  Copyright (c) 2007 Vassilis Rizopoulos. All rights reserved.
+
+require 'rexml/document'
+
+require 'rutema/specification'
+require 'rutema/configuration'
+
+require 'rubygems'
+require 'highline'
+require 'mailfactory'
+require 'patir/command'
+
+module Rutema
+  VERSION_MAJOR=0
+  VERSION_MINOR=1
+  #Is raised when an error is found in a specification
+  class ParserError<RuntimeError
+  end
+
+  #Base class that bombs out when used....
+  class SpecificationParser
+    def parse_specification
+      raise ParserError,"not implemented. You should derive a parser implementation from SpecificationParser!"
+    end
+  end
+
+  class BaseXMLParser<SpecificationParser
+    ELEM_SPEC="specification"
+    ELEM_DESC="specification/description"
+    ELEM_TITLE="specification/title"
+    ELEM_SCENARIO="specification/scenario"
+    ELEM_REQ="requirement"
+    def initialize params
+      @logger=params[:logger]
+      @logger||=Patir.setup_logger
+    end
+    #Parses __param__ and returns the Rutema::TestSpecification instance
+    #
+    #param can be the filename of the specification or the contents of that file.
+    #
+    #Will throw ParserError if something goes wrong
+    def parse_specification param
+      @logger.debug("Loading #{param}")
+      begin
+        file=false
+        if File.exists?(param)
+          #read the file
+          txt=File.read(param)
+          file=true
+        else
+          #try to parse the parameter
+          txt=param
+        end
+        spec=parse_case(txt)
+        spec.filename=""
+        spec.filename=param if file
+        raise "Missing required attribute 'name' in specification element" unless spec.has_name? && !spec.name.empty?
+        return spec
+      rescue
+        @logger.debug($!)
+        raise ParserError,"Error loading #{param}: #{$!.message}"
+      end
+    end
+
+    private
+    #Parses the XML specification of a testcase and creates the corresponding TestSpecification instance
+    def parse_case xmltxt
+      #the testspec to return
+      spec=TestSpecification.new
+      #read the test spec
+      xmldoc=REXML::Document.new( xmltxt )
+      #validate it
+      validate_case(xmldoc)
+      #parse it
+      el=xmldoc.elements[ELEM_SPEC]
+      xmldoc.root.attributes.each do |attr,value|
+        add_attribute(spec,attr,value)
+      end
+      #get the title
+      spec.title=xmldoc.elements[ELEM_TITLE].text
+      spec.title||=""
+      spec.title.strip!
+      #get the description
+      #strip line feeds, cariage returns and remove all tabs
+      spec.description=xmldoc.elements[ELEM_DESC].text
+      spec.description||=""
+      begin
+        spec.description.strip!
+        spec.description.gsub!(/\t/,'')  
+      end unless spec.description.empty?
+      #get the requirements
+      reqs=el.elements.select{|e| e.name==ELEM_REQ}
+      reqs.collect!{|r| r.attributes["name"]}
+      spec.requirements=reqs
+      #Get the scenario
+      spec.scenario=parse_scenario(xmldoc.elements[ELEM_SCENARIO].to_s) if xmldoc.elements[ELEM_SCENARIO]
+      return spec
+    end
+    #Validates the XML file from our point of view.
+    #
+    #Checks for the existence of ELEM_SPEC, ELEM_DESC and ELEM_TITLE and raises ParserError if they're missing.
+    def validate_case xmldoc
+      raise ParserError,"missing #{ELEM_SPEC} element" unless xmldoc.elements[ELEM_SPEC]
+      raise ParserError,"missing #{ELEM_DESC} element" unless xmldoc.elements[ELEM_DESC]
+      raise ParserError,"missing #{ELEM_TITLE} element" unless xmldoc.elements[ELEM_TITLE]
+    end
+    #Parses the scenario XML element and returns the Rutema::TestScenario instance
+    def parse_scenario xmltxt
+      scenario=Rutema::TestScenario.new
+      xmldoc=REXML::Document.new( xmltxt )
+      xmldoc.root.attributes.each do |attr,value|
+        add_attribute(scenario,attr,value)
+      end
+      number=0
+      xmldoc.root.elements.each do |el| 
+        number+=1
+        step=parse_step(el.to_s)
+        step.number=number
+        scenario.add_step(step)
+      end
+      return scenario
+    end
+    #Parses xml and returns the Rutema::TestStep instance
+    def parse_step xmltxt
+      xmldoc=REXML::Document.new( xmltxt )
+      #any step element
+      step=Rutema::TestStep.new()
+      xmldoc.root.attributes.each do |attr,value|
+        add_attribute(step,attr,value)
+      end
+      step.text=xmldoc.root.text.strip if xmldoc.root.text
+      step.step_type=xmldoc.root.name 
+      return step
+    end
+
+    def add_attribute element,attr,value
+      if boolean?(value)
+        element.attribute(attr,eval(value))
+      else
+        element.attribute(attr,value)
+      end
+    end
+    def boolean? attribute_value
+      return true if attribute_value=="true" || attribute_value=="false"
+      return false
+    end
+  end
+
+  class MinimalXMLParser<BaseXMLParser
+    def parse_specification param
+      handle_specification(super(param))
+    end
+    private
+    def handle_specification spec
+      spec.scenario.steps.each do |step|
+        case step.step_type
+        when "echo"
+          step.cmd=Patir::RubyCommand.new("echo"){|cmd| cmd.output="#{step.text}";$stdout.puts(cmd.output) ;:success}
+        when "command"
+          raise ParserError,"missing required attribute cmd in #{step}"
+          wd=step.working_directory if step.has_working_directory?
+          step.cmd=Patir::ShellCommand.new(:cmd=>step.cmd,:working_directory=>wd)
+        when "prompt"
+          step.cmd=Patir::RubyCommand.new("prompt") do |cmd|  
+            cmd.output=""
+            cmd.error=""
+            if HighLine.agree("#{step.text}?")
+              :success
+            else
+              :error
+            end#if
+          end#do rubycommand
+        end#case
+      end#do spec.scenario.steps
+      return spec
+    end
+  end
+  
+  class Coordinator
+    attr_accessor :configuration,:parse_errors,:parsed_files
+    def initialize configuration,logger=nil
+      @logger=logger
+      @logger||=Patir.setup_logger
+      @parse_errors=Array.new
+      @configuration=configuration
+      @parser=instantiate_class(@configuration.parser)
+      raise "Could not instantiate parser" unless @parser
+      @reporters=@configuration.reporters.collect{ |reporter| instantiate_class(reporter) }
+      @reporters.compact!
+      @configuration.tests.collect!{|t| File.expand_path(t)}
+      @runner=create_runner
+      @parsed_files=Array.new
+    end
+    #Runs a set of tests
+    #
+    #mode can be :all, :attended, :unattended or a test filename
+    def run mode
+      @configuration.context.start_time=Time.now
+      @logger.info("Run started")
+      case mode
+      when :all
+        specs=parse_all_specifications
+        run_scenarios(specs)
+      when :attended
+        specs=parse_all_specifications
+        @logger.debug(specs)
+        run_scenarios(specs.select{|s| s.scenario && s.scenario.attended?})
+      when :unattended
+        specs=parse_all_specifications
+        @logger.debug(specs)
+        run_scenarios(specs.select{|s| s.scenario && !s.scenario.attended?})
+      when String
+        spec=parse_specification(mode)
+        run_test(spec) if spec
+      else
+        @logger.error("Don't know how to run '#{mode}'")
+      end
+      @configuration.context.end_time=Time.now
+      @logger.info("Run completed in #{@configuration.context.end_time-@configuration.context.start_time}s")
+    end
+
+    #Delegates reporting to all configured reporters spawning one thread per reporter
+    #
+    #It then joins the threads and returns when all of them are finished.
+    def report
+      threads=Array.new
+      runner_status=Patir::CommandSequenceStatus.new("",@runner.states.values)
+      #get the runner stati and the configuration and give it to the reporters
+      @reporters.each do |reporter|
+        threads<<Thread.new(reporter,runner_status,@parse_errors,@configuration) do |reporter,status,perrors,configuration|
+          @logger.debug(reporter.report(status,perrors,configuration))
+        end
+      end
+      threads.each do |t| 
+        @logger.debug("Joining #{t}")
+        t.join
+      end
+    end
+
+    def to_s
+      runner_status=Patir::CommandSequenceStatus.new("",@runner.states.values)
+      "Parsed #{@parsed_files.size} files\n#{Rutema.text_report(runner_status,@parse_errors)}"
+    end
+    private
+    def instantiate_class definition
+      if definition[:class]
+        #add the logger to the definition
+        definition[:logger]=@logger
+        klass=definition[:class]
+        return klass.new(definition)
+      end
+      return nil
+    end
+
+    def create_runner
+      setup=nil
+      teardown=nil
+      if @configuration.setup
+        @logger.info("Parsing setup specification from '#{@configuration.setup}'")
+        setup=@parser.parse_specification(@configuration.setup).scenario
+      end
+      if @configuration.teardown
+        @logger.info("Parsing teardown specification from '#{@configuration.teardown}'")
+        teardown=@parser.parse_specification(@configuration.teardown).scenario
+      end
+      if @configuration.step
+        @logger.info("Using StepRunner")
+        return StepRunner.new(setup,teardown,@logger)
+      else
+        return Runner.new(setup,teardown,@logger)
+      end
+    end
+
+    def parse_specification spec_file
+      filename=File.expand_path(spec_file)
+      if File.exists?(filename)
+        begin
+          @parsed_files<<filename
+          @parsed_files.uniq!
+          return @parser.parse_specification(spec_file)
+        rescue ParserError
+          @logger.error("Error parsing '#{spec_file}': #{$!.message}")
+          @parse_errors<<{:filename=>filename,:error=>$!.message}
+        end
+      else
+        msg="'#{filename}' not found."
+        @logger.error(msg)
+        @parse_errors<<{:filename=>filename,:error=>msg}
+      end
+      return nil
+    end
+    def parse_all_specifications
+      @configuration.tests.collect{|t| parse_specification(t)}.compact
+    end
+
+    def run_scenarios specs
+      specs.compact!
+      if specs.empty?
+        @logger.error("No tests to run")
+      else
+        specs.each{|s| run_test(s)}
+      end
+    end
+    def run_test specification
+      @logger.info("Running #{specification.name} -  #{specification.title}")
+      if specification.scenario
+        status=@runner.run(specification.name,specification.scenario)
+      else
+        @logger.warn("#{specification.name} has no scenario")
+        status=:not_executed
+      end
+      return status
+    end
+  end
+
+  #Runner executes TestScenario instances and maintains the state of all scenarios run.
+  class Runner
+    attr_reader :states,:number_of_runs
+    attr_accessor :setup,:teardown
+    attr_writer :attended
+
+    #setup and teardown are TestScenario instances that will run before and after each call
+    #to the scenario.
+    def initialize setup=nil, teardown=nil,logger=nil
+      @setup=setup
+      @teardown=teardown
+      @attended=false
+      @logger=logger
+      @logger||=Patir.setup_logger
+      @states=Hash.new
+      @number_of_runs=0
+    end
+
+    def attended?
+      return @attended
+    end
+    #Runs a scenario and stores the result internally
+    #
+    #Returns the result of the run as a Patir::CommandSequenceStatus
+    def run name,scenario
+      @logger.debug("Starting run for #{name} with #{scenario.inspect}")
+      @states[name]=Patir::CommandSequenceStatus.new(name,scenario.steps)
+      @states[name].sequence_id="s#{@number_of_runs}"
+      #if setup /teardown is defined we need to execute them before and after
+      if @setup
+        @logger.info("Setup for #{name}")
+        @states["#{name}_setup"]=run_scenario("#{name}_setup",@setup)
+        @states["#{name}_setup"].sequence_id="s#{@number_of_runs}"
+        if @states["#{name}_setup"].executed? 
+          #do not execute the scenario unless the setup was succesfull
+          if @states["#{name}_setup"].success?
+            @logger.info("Scenario for #{name}")
+            @states[name]=run_scenario(name,scenario)
+          end
+        end
+      else
+        @logger.info("Scenario for #{name}")
+        @states[name]=run_scenario(name,scenario)
+      end
+      if @teardown
+        #always execute teardown
+        @logger.warn("Teardown for #{name}")
+        @states["#{name}_teardown"]=run_scenario("#{name}_teardown",@teardown)
+        @states["#{name}_teardown"].sequence_id="t#{@number_of_runs}"
+      end
+      @number_of_runs+=1
+      return @states[name]
+    end
+
+    #Returns the state of the scenario with the given name.
+    #
+    #Will return nil if no scenario is found under that name.
+    def [](name)
+      return @states[name]
+    end
+
+    def reset
+      @states.clear
+      @number_of_runs=0
+    end
+    private
+    def run_scenario name,scenario
+      state=Patir::CommandSequenceStatus.new(name,scenario.steps)
+      if scenario.attended? && !self.attended?
+        @logger.warn("Attended scenario cannot be run in unattended mode")
+        state..status=:warning
+      else
+        stps=scenario.steps
+        if stps.empty?
+          @logger.warn("Scenario #{name} contains no steps")
+          state.status=:warning
+        else
+          stps.each do |s| 
+            state.step=run_step(s)
+            break if !state.success?
+          end
+        end
+      end
+      state.stop_time=Time.now
+      state.sequence_id=@number_of_runs
+      return state
+    end
+    def run_step step
+      @logger.info("#{step.to_s}")
+      if step.has_cmd? && step.cmd.respond_to?(:run)
+        step.cmd.run
+      else
+        @logger.warn("No command associated with step '#{step.step_type}'")
+      end
+      msg="#{step.number} - #{step.step_type} - #{step.status}"
+      # we might not have a command object
+      if step.has_cmd? && step.cmd.executed? && !step.cmd.success?
+        msg<<"\n#{step.cmd.output}" unless step.cmd.output.empty?
+      end
+      if step.status==:error
+        @logger.error(msg) 
+      else
+        @logger.info(msg)
+      end
+      return step
+    end
+  end
+
+  #StepRunner halts before every step and asks if it should be executed or not.
+  class StepRunner<Runner
+    def run_step step
+      if HighLine.agree("Execute #{step.to_s}?")
+        return super
+      else
+        state[:state]=:not_executed
+        msg="#{step.number} - #{step.step_type} - #{state[:state]}"
+        @logger.info(msg)
+        return state
+      end
+    end
+  end
+
+  #The application class
+  class RutemaX
+    require  'optparse'
+    def initialize command_line_args
+      parse_command_line(command_line_args)
+      @logger=Patir.setup_logger(@log_file)
+      begin
+        @configuration=RutemaConfigurator.new(@config_file,@logger).configuration
+        @coordinator=Coordinator.new(@configuration,@logger)
+        application_flow
+      rescue Patir::ConfigurationException
+        @logger.debug($!)
+        @logger.fatal("Configuration error '#{$!.message}'")
+        exit 1
+      rescue
+        @logger.debug($!)
+        @logger.fatal("#{$!.message}")
+        exit 1
+      end
+    end
+    private
+    def parse_command_line args
+      args.options do |opt|
+        opt.on("Options:")
+        opt.on("--debug", "-d","Turns on debug messages") { $DEBUG=true }
+        opt.on("--config FILE", "-c FILE",String,"Loads the configuration from FILE") { |@config_file|}
+        opt.on("--log FILE", "-l FILE",String,"Redirects the log output to FILE") { |@log_file|}
+        opt.on("--check","Runs just the check test"){@check=true}
+        opt.on("-V", "--version","Displays the version") { $stdout.puts("v#{VERSION_MAJOR}.#{VERSION_MINOR}");exit 0 }
+        opt.on("--help", "-h", "-?", "This text") { $stdout.puts opt; exit 0 }
+        opt.parse!
+        #and now the rest
+        if args.empty?
+          @mode=:unattended
+        else
+          command=args.shift
+          case command
+          when "attended"
+            @mode=:attended
+          when "all"
+            @mode=:all
+          when "unattended"
+            @mode=:unattended
+          else
+            if File.exists?(command)
+              @mode=command
+            else
+              $stderr.puts "Can't find '#{command}'. Don't know what to do with it."
+              exit 1
+            end
+          end
+        end
+      end
+    end
+    def application_flow
+      if @check
+        #run just the check test
+        if @configuration.check
+          @coordinator.run(@configuration.check)
+        else
+          @logger.error("There is no check test defined in the configuration.")
+        end
+      else
+        #run everything
+        @coordinator.run(@mode)
+      end
+      @logger.info("Report:\n#{@coordinator.to_s}")
+      @coordinator.report
+    end
+  end
+  #Reporter is meant as a base class for reporter classes.
+  class Reporter
+    #params should be a Hash containing the parameters used to initialize the class
+    def initialize params
+    end
+
+    #Coordinator will pass the Rutema __configuration__ giving you access to the context which can contain data like headings and version numbers to use in the report.
+    #
+    #runner_status is a Patir::CommandSequenceStatus containing the status of the last run (so it contains all the Scenario stati for the loaded tests)
+    #
+    #parse_errors is an Array of {:filename,:error} hashes containing the errors encounter by the parser when loading the specifications
+    def report runner_status,parse_errors,configuration
+
+    end
+  end
+
+  #The following configuration keys are used by EmailReporter:
+  #
+  #:server - the smtp server to use
+  #
+  #:port - the port to use (defaults to 25)
+  #
+  #:sender - the sender of the email (defaults to rutema@domain)
+  #
+  #:recipients - an array of strings with the recipients of the report emails
+  #
+  #The :logger key is set by the Coordinator
+  #
+  #Customization keys:
+  #
+  #:subject - the string of this key will be prefixed as a subject for the email
+  class EmailReporter
+    attr_reader :last_message
+    def initialize definition
+      #get the logger
+      @logger=definition[:logger]
+      @logger||=Patir.setup_logger
+      #extract the parameters from the definition
+      #address and port of the smtp server
+      @server=definition[:server]
+      @port=definition[:port]
+      @port||=25
+      #the domain we're coming from
+      @domain=definition[:domain]
+      #construct the mail factory object
+      @mail = MailFactory.new()
+      @mail.from = definition[:sender]
+      @mail.from||="rutema@#{@domain}"
+      @recipients=definition[:recipients]
+      @mail.to=@recipients
+      #customize
+      @subject=definition[:subject]
+      @subject||=""
+      #this is a way to test without sending
+      @dummy=true if definition[:dummy]
+      @logger.info("Reporter '#{self.to_s}' registered")
+    end
+
+    def to_s
+      list=@recipients.join(', ')
+      "EmailReporter - #{@server}:#{@port} from #{@mail.from} to #{list}"
+    end
+    
+    def report runner_status,parse_errors,configuration
+      @mail.subject = "#{@subject}"
+      @mail.text = Rutema.text_report(runner_status,parse_errors)
+      begin
+        if @mail.to.empty?
+          @logger.error("No recipients for the report mail")
+        else
+          #
+          #~ if @password
+          #~ #if a password is defined, use cram_md5 authentication
+          #~ else
+          Net::SMTP.start(@server, @port, @domain) {|smtp| smtp.sendmail(@mail.to_s(),@mail.from,mail_to)} unless @dummy
+          #~ end
+        end#recipients empty
+      rescue
+        @logger.error("Sending of email report failed: #{$!}")
+      end
+      @mail.to_s
+    end
+  end
+  private
+  def self.text_report runner_status,parse_errors
+    msg="Parse errors: #{parse_errors.size}"
+    parse_errors.each{|e| msg<<"\n\t#{e[:filename]}"}
+    msg<<"\nCurrent run:\nScenarios: #{runner_status.step_states.size}"
+    msg<<"\n#{runner_status.summary}"
+    return msg
+  end
+end

data/test/samples/check.spec

@@ -0,0 +1,5 @@
+<specification name="check">
+	<title></title>
+	<description></description>
+	<scenario></scenario>
+</specification>

data/test/samples/setup.spec

@@ -0,0 +1,7 @@
+<specification name="setup">
+	<title></title>
+	<description></description>
+	<scenario>
+		<echo>Hello Testing World</echo>
+	</scenario>
+</specification>

data/test/samples/teardown.spec

@@ -0,0 +1,7 @@
+<specification name="teardown">
+	<title></title>
+	<description></description>
+	<scenario>
+		<echo>Hello Testing World</echo>
+	</scenario>
+</specification>

data/test/samples/test.spec

@@ -0,0 +1,7 @@
+<specification name="sample">
+<title>Sample specification</title>
+<description>Something to play with</description>
+<scenario>
+	<echo>Hello Testing World</echo>
+</scenario>
+</specification>

data/test/samples/tests/no_title.spec

@@ -0,0 +1,4 @@
+<specification name="no_title">
+<description>Expect a parser error</description>
+<scenario></scenario>
+</specification>

data/test/samples/tests/sample.spec

@@ -0,0 +1,7 @@
+<specification name="sample">
+<title>Sample specification</title>
+<description>Something to play with</description>
+<scenario>
+	<echo text="Hello testing world"/>
+</scenario>
+</specification>

data/test/samples/valid_config.rb

@@ -0,0 +1,20 @@
+require 'rake'
+#
+configuration.parser={:class=>Rutema::MinimalXMLParser}
+configuration.reporter={:class=>Rutema::EmailReporter,
+  :server=>"localhost",
+  :port=>25,
+  :recipients=>["test"],
+  :sender=>"rutema",
+  :subject=>"test",
+  :dummy=>true
+}
+configuration.tool={:name=>"echo",:path=>"echo.exe"}
+configuration.tool={:name=>"tool",:path=>"tool.exe"}
+configuration.path={:name=>"SourcePath",:path=>"../../lib"}
+configuration.setup="setup.spec"
+configuration.teardown="teardown.spec"
+configuration.check="check.spec"
+configuration.tests=["test.spec"]
+configuration.tests=Rake::FileList["tests/*.spec"]
+configuration.context_data={:tester=>"riva"}

data/test/test_configuration.rb

@@ -0,0 +1,37 @@
+$:.unshift File.join(File.dirname(__FILE__),"..","lib")
+
+require 'test/unit'
+
+module TestRutema
+  require 'rutema/system'
+  
+  class TestRutemaConfigurator<Test::Unit::TestCase
+    def setup
+      @prev_dir=Dir.pwd
+      Dir.chdir(File.dirname(__FILE__))
+    end
+    def teardown
+      Dir.chdir(@prev_dir)
+    end
+    def test_configuration
+      cfg=nil
+      #load the valid configuration
+      assert_nothing_raised() { cfg=Rutema::RutemaConfigurator.new("samples/valid_config.rb").configuration}
+      assert_not_nil(cfg.parser)
+      assert_not_nil(cfg.reporters)
+      assert_equal(1, cfg.reporters.size)
+      assert_not_nil(cfg.tools)
+      assert_not_nil(cfg.paths)
+      assert_not_nil(cfg.setup)
+      assert_not_nil(cfg.teardown)
+      assert_not_nil(cfg.check)
+      assert_not_nil(cfg.tests)
+      assert_not_nil(cfg.context)
+    end
+    def test_specification_paths
+      cfg=Rutema::RutemaConfigurator.new("samples/valid_config.rb").configuration
+      assert_not_nil(cfg.tests)
+      p cfg.tests
+    end
+  end
+end