rutema 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a5e0e4c18d2eab07c25f48a69bcdc1b107be341d
-  data.tar.gz: 2c7b678e57ff73713a0aa1dda240144650203351
+SHA256:
+  metadata.gz: b7b895aa680e7df981e4915c65427164a6c0f3e423d7381adcb286c8c625ee11
+  data.tar.gz: eb6409e8c312f835dedd4f5f35588113a870b166eef9d73a8f7a84f4ae4c5101
 SHA512:
-  metadata.gz: 60f93501c1a3c659effff6f8c3eed6bd2f9e0b1384df14629c92b599d6c2ce57dede0491de2679ca7231a42a77e61269ed822e9531d69815a2ccdc4a6e02f87a
-  data.tar.gz: ec9a4ab8dd76ef4dcd606008d02cd9e00bd7786948b44a860ae45f4676c9128c2802418b3ea0566a7ea24c63d3d17cca33e8c18cdc874ad0ab06f5c5fb2f3624
+  metadata.gz: 3f7af65c99c671f3622287ed11ea0cd6fdd95539e339a0cf52561a974cd08f60fd9d57ae9f92328c45d3eb5ba26e37b99ff2d2a6309cee7c14c323cff16567e6
+  data.tar.gz: 0f5a684b9fca67d3b9cb6fed542996e27dc43229f77b87154da5d41bb27d88085f5d3335c747cdab6671e2a69eca929d768cf2a4f4730235db1127d05f94069f

data/History.txt

@@ -1,3 +1,5 @@
+== 2.0.1 2026-03-02
+ * Release the 10 year old changes that fix handling of execution context within steps
 == 2.0.0/ 2017-09-23
  * Parsing behaviour has changed, parsing errors are not accepted and the run fails immediately
 == 2.0.0.pre15 /2017-02-08

data/README.md

@@ -1,5 +1,5 @@
 ## rutema
-[![Build Status](https://secure.travis-ci.org/damphyr/rutema.png)](http://travis-ci.org/damphyr/rutema) [![Coverage Status](https://coveralls.io/repos/damphyr/rutema/badge.svg)](https://coveralls.io/r/damphyr/rutema) [![Code Climate](https://codeclimate.com/github/damphyr/rutema.png)](https://codeclimate.com/github/damphyr/rutema) ![doc status](http://inch-ci.org/github/damphyr/rutema.svg?branch=master)
+[![Build Status](https://secure.travis-ci.org/damphyr/rutema.png)](http://travis-ci.org/damphyr/rutema) [![Coverage Status](https://coveralls.io/repos/damphyr/rutema/badge.svg)](https://coveralls.io/r/damphyr/rutema) [![Code Climate](https://codeclimate.com/github/damphyr/rutema.png)](https://codeclimate.com/github/damphyr/rutema) ![doc status](http://inch-ci.org/github/damphyr/rutema.svg?branch=master) [![Gem Version](https://badge.fury.io/rb/rutema.svg)](https://badge.fury.io/rb/rutema)
 
 rutema [http://github.com/damphyr/rutema](http://github.com/damphyr/rutema)
 
@@ -31,7 +31,7 @@ Rutema core provides a reference implementation of a parser for a simple but ext
 * An [example](doc/EXAMPLE.md) of a (very simple) testing DSL with rutema 
 * High level [description](README.md) of the concepts behind rutema
 
-## Installation:
+## Installation
 
 * gem install rutema
 
@@ -41,7 +41,7 @@ The core functionality of rutema depends on the following gems:
  * [patir](http://github.com/damphyr/patir)
  * [highline](http://highline.rubyforge.org/)
 
-## License:
+## License
 
 (The MIT License)
 

data/bin/rutema

@@ -1,9 +1,11 @@
 #!/usr/bin/env ruby
-#  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
+
+#  Copyright (c) 2007-2021 Vassilis Rizopoulos. All rights reserved.
+
 require 'rutema/application'
 begin
 	Rutema::App.new(ARGV)
 rescue Rutema::RutemaError
  puts $!.message
  exit 1
-end
+end

data/lib/rutema/application.rb

@@ -1,10 +1,20 @@
+#  Copyright (c) 2021 Vassilis Rizopoulos. All rights reserved.
+
 require  'optparse'
+
 require_relative "core/configuration"
 require_relative "core/engine"
 
 module Rutema
-  #Parses the commandline, sets up the configuration and launches Rutema::Engine
+  ##
+  # Entry-point class for rutema
+  #
+  # This class parses the commandline, sets up the internal configuration of
+  # rutema accordingly and starts the application flow.
   class App
+    ##
+    # Configure and start the application flow according to the passed
+    # commandline options
     def initialize command_line_args
       parse_command_line(command_line_args)
       @configuration=Rutema::Configuration.new(@config_file)
@@ -18,7 +28,12 @@ module Rutema
       @engine=Rutema::Engine.new(@configuration)
       application_flow
     end
+
     private
+
+    ##
+    # Define the available commandline options and parse the given commandline
+    # accordingly
     def parse_command_line args
       args.options do |opt|
         opt.on("rutema v#{Version::STRING}")
@@ -45,18 +60,21 @@ module Rutema
         end
       end
     end
+
+    ##
+    # Start the application flow
     def application_flow
       if @check
-        #run just the suite setup test
+        # run just the suite setup test if requested
         if @configuration.suite_setup
           exit @engine.run(@configuration.suite_setup)
         else
           raise Rutema::RutemaError,"There is no suite setup test defined in the configuration."
         end
       else
-        #run everything
+        # run everything
         exit @engine.run(@test_identifier)
       end
     end
   end
-end
+end

data/lib/rutema/core/configuration.rb

@@ -1,131 +1,260 @@
-  #  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
+#  Copyright (c) 2007-2021 Vassilis Rizopoulos. All rights reserved.
+
   require 'ostruct'
   require_relative 'parser'
   require_relative 'reporter'
   module Rutema
-    #This module defines the "configuration directives" used in the configuration of Rutema
+  ##
+  # Mix-in module defining all configuration directives available for rutema
+  #
+  # === Example
+  #
+  # A configuration file needs at least definitions of which parser to utilize
+  # and which tests to run.
+  #
+  # rutema configuration files are valid Ruby code and can use the full power of
+  # the language including _require_ directives.
+  #
+  #     require "rake/file_list"
+  #     
+  #     configure do |cfg|
+  #       cfg.parser = { :class => Rutema::Parsers::XML }
+  #       cfg.tests = FileList['all/of/the/tests/**/*.*']
+  #     end
+    module ConfigurationDirectives
+    ##
+    # Hash of context data which may be utilized throughout test runs
     #
-    #Example
-    #A configuration file needs as a minimum to define which parser to use and which tests to run.
+    # This could be used for e.g. tester names, version numbers, etc.
+    attr_reader :context
+
+    ##
+    # Parser class which shall be used to parse test specifications
+    attr_reader :parser
+
+    ##
+    # A hash of supplementary paths identified by representative names
+    attr_reader :paths
+
+    ##
+    # A hash mapping reporter classes to supplementary definitions
+    attr_accessor :reporters
+
+    ##
+    # Runner class which shall be used to execute the tests
+    attr_reader :runner
+
+    ##
+    # Path to a setup specification which will be run before every test
+    # specification (optional)
+    attr_reader :setup
+
+    ##
+    # Path to a suite setup specification (optional)
     #
-    #Since rutema configuration files are valid Ruby code, you can use the full power of the Ruby language including require directives
+    # This will be run before all other test specifications. If it fails no
+    # other specifications will be executed.
+    attr_reader :suite_setup
+
+    ##
+    # Path to a suite teardown specification (optional)
     #
-    # require 'rake'
-    # configuration.parser={:class=>Rutema::MinimalXMLParser}
-    # configuration.tests=FileList['all/of/the/tests/**/*.*']
-    module ConfigurationDirectives
-      attr_reader :parser,:runner,:tools,:paths,:tests,:context,:setup,:teardown,:suite_setup,:suite_teardown
-      attr_accessor :reporters
-      #Adds a hash of values to the tools hash of the configuration
-      #
-      #This hash is then accessible in the parser and reporters as a property of the configuration instance
-      #
-      #Required keys:
-      # :name - the name to use for accessing the path in code
-      #Example:
-      # configure do |cfg|
-      #  cfg.tool={:name=>"nunit",:path=>"/bin/nunit",:configuration=>{:important=>"info"}}
-      # end
-      #
-      #The path to nunit can then be accessed in the parser as
-      # @configuration.tools.nunit[:path]
-      #
-      #This way you can pass configuration information for the tools you use
+    # This will be run after all other test specifications
+    attr_reader :suite_teardown
+
+    ##
+    # Path to a teardown specification which will be run after every test
+    # specification (optional)
+    attr_reader :teardown
+
+    ##
+    # Array of (most probably the paths to) the specifications of the tests to
+    # be executed
+    #
+    # In nearly all cases this would contain only paths but generally this can
+    # contain any data intelligible by the test specification parser.
+    attr_reader :tests
+
+    ##
+    # Hash containing data for tools indexed by their names
+    attr_reader :tools
+
+    ##
+    # Add a hash with arbitrary data concerning one particular tool which can be
+    # utilized throughout testing by accessing the +tools+ attribute of classes
+    # including this module
+    #
+    # The hash must include a +:name+ key which will define the key under which
+    # the entire passed hash will be stored.
+    #
+    # New calls only add to the hash. Later calls containing the same +:name+
+    # key as earlier ones replace the data these set.
+    #
+    # === Example
+    #
+    #     configure do |cfg|
+    #       cfg.tool = { :name => "nunit", :path => "/bin/nunit", :configuration => { :important=>"info" } }
+    #     end
+    #
+    # The path to NUnit can be accessed the following way:
+    #
+    #     @configuration.tools["nunit"][:path]
       def tool= definition
         raise ConfigurationException,"required key :name is missing from #{definition}" unless definition[:name]
         @tools[definition[:name]]=definition
       end
-      #Adds a path to the paths hash of the configuration
-      #
-      #Required keys:
-      # :name - the name to use for accessing the path in code
-      # :path - the path
-      #Example:
-      # cfg.path={:name=>"sources",:path=>"/src"}
+
+    ##
+    # Add a path indexed by a representative name to the paths attribute
+    #
+    # A hash is expected which contains a representative name under the +:name+
+    # key and the path itself under the +:path+ key.
+    #
+    # New calls only add to the hash. Later calls containing the same +:name+
+    # key as earlier ones replace the data these set.
+    #
+    # === Example
+    #
+    #     configure do |cfg|
+    #       cfg.path = { :name => "doc", :path => "/usr/local/share/doc" }
+    #     end
       def path= definition
         raise ConfigurationException,"required key :name is missing from #{definition}" unless definition[:name]
         raise ConfigurationException,"required key :path is missing from #{definition}" unless definition[:path]
         @paths[definition[:name]]=definition[:path]
       end
-      #Path to the setup specification. (optional)
-      #
-      #The setup test runs before every test.
+
+    ##
+    # Path to a setup specification (optional)
+    #
+    # This setup specification will be run before every test specification.
+    #
+    # Later calls override earlier ones.
       def setup= path
         @setup=check_path(path)
       end
-      #Path to the teardown specification. (optional)
-      #
-      #The teardown test runs after every test.    
+
+    ##
+    # Path to a teardown specification (optional)
+    #
+    # This teardown specification will be run after every test specification.
+    #
+    # Later calls override earlier ones.
       def teardown= path
         @teardown=check_path(path)
       end
-      #Path to the suite setup specification. (optional)
-      #
-      #The suite setup test runs once in the beginning of a test run before all the tests.
-      #
-      #If it fails no tests are run.
-      #
-      #This is also aliased as check= for backwards compatibility
+
+    ##
+    # Path to a suite setup specification (optional)
+    #
+    # This suite setup specification is executed once in the beginning of a test
+    # run before any other specifications. If it fails no other test
+    # specifications are executed.
+    #
+    # This is aliased as #check= for backwards compatibility.
+    #
+    # Later calls override earlier ones.
       def suite_setup= path
         @suite_setup=check_path(path)
       end
 
       alias_method :check,:suite_setup
       alias_method :check=,:suite_setup=
-      #Path to the suite teardown specification. (optional)
-      #
-      #The suite teardown test runs after all the tests.
+
+    ##
+    # Path to a suite teardown specification (optional)
+    #
+    # This suite teardown specification is executed once after all other test
+    # specifications have been executed.
+    #
+    # Later calls override earlier ones.
       def suite_teardown= path
         @suite_teardown=check_path(path)
       end
-      #Hash values for passing data to the system. It's supposed to be used in the reporters and contain 
-      #values such as version numbers, tester names etc.
+
+    ##
+    # Context information which shall be accessible during test execution
+    #
+    # Data must be passed in form of a hash. In case of key collisions later
+    # calls override existing data of colliding keys.
+    #
+    # This could be used e.g. to pass data as tester names, version numbers,
+    # etc. to the reporters.
       def context= definition
         @context||=Hash.new
         raise ConfigurationException,"Only accepting hash values as context_data" unless definition.kind_of?(Hash)
         @context.merge!(definition)
       end
-      #Adds the specification identifiers available to this instance of Rutema
-      #
-      #These will usually be files, but they can be anything.
-      #Essentially this is an Array of strings that mean something to your parser
+
+    ##
+    # Add an array of (paths of) test specifications to be executed
+    #
+    # Usually an array of file paths would be given. Generally the passed array
+    # can contain anything intelligible for the parser.
       def tests= array_of_identifiers
         @tests+=array_of_identifiers.map{|f| full_path(f)}
       end
-      #A hash defining the parser to use.
-      #
-      #The hash is passed as is to the parser constructor and each parser should define the necessary configuration keys.
-      #
-      #The only required key from the configurator's point fo view is :class which should be set to the fully qualified name of the class to use.
-      #
-      #Example:
-      # cfg.parser={:class=>Rutema::MinimalXMLParser}
+
+    ##
+    # Set the parser class which shall be used to parse test specifications
+    #
+    # The only required key is +:class+ which should be set to the fully
+    # qualified name of the class to be used for parsing.
+    #
+    # Later calls overwrite earlier ones.
+    #
+    # === Example
+    #
+    #     configure do |cfg|
+    #      cfg.parser = { :class => Rutema::Parsers::XML }
+    #     end
       def parser= definition
         raise ConfigurationException,"required key :class is missing from #{definition}" unless definition[:class]
         @parser=definition
       end
-      #A hash defining the runner to use.
-      #
-      #The hash is passed as is to the runner constructor and each runner should define the necessary configuration keys.
-      #
-      #The only required key from the configurator's point fo view is :class which should be set to the fully qualified name of the class to use.
-      #
-      #Example:
-      # cfg.runner={:class=>Rutema::Runners::NoOp}
+
+    ##
+    # Set the runner which shall be used to execute the tests
+    #
+    # Upon construction of the runner the context set through the configuration
+    # is being passed to the initializer.
+    #
+    # The only required key is +:class+ which should be set to the fully
+    # qualified name of the class as runner.
+    #
+    # Later calls overwrite earlier ones.
+    #
+    # === Example
+    #
+    #     configure do |cfg|
+    #      cfg.runner = { :class => Rutema::Runners::Default }
+    #     end
       def runner= definition
         raise ConfigurationException,"required key :class is missing from #{definition}" unless definition[:class]
         @runner=definition
       end
-      #Adds a reporter to the configuration.
-      #
-      #As with the parser, the only required configuration key is :class and the definition hash is passed to the class' constructor.
-      # 
-      #Unlike the parser, you can define multiple reporters.
+
+    ##
+    # Add a reporter for the test execution
+    #
+    # The only required key is +:class+ which should be set to the fully
+    # qualified name of the class to be used for reporting.
+    #
+    # Multiple reporter classes can be set simultaneously.
+    #
+    # === Example
+    #
+    #     configure do |cfg|
+    #      cfg.reporters = { :class => Rutema::Reporters::Console }
+    #      cfg.reporters = { :class => Rutema::Reporters::JUnit }
+    #     end
       def reporter= definition
         raise ConfigurationException,"required key :class is missing from #{definition}" unless definition[:class]
         @reporters[definition[:class]]=definition
       end
-      #:stopdoc
+
+    ##
+    # Initialize member variables which are needed to process a configuration
       def init
         @reporters={}
         @context={}
@@ -133,54 +262,97 @@
         @tools=OpenStruct.new
         @paths=OpenStruct.new
       end
-      #:startdoc
-      private 
-      #Checks if a path exists and raises a ConfigurationException if not
+
+      private
+
+    ##
+    # Check if the given path exists and raise a ConfigurationException if not
       def check_path path
         path=File.expand_path(path)
         raise ConfigurationException,"#{path} does not exist" unless File.exist?(path)
         return path
       end
-      #Gives back a string of key=value,key=value for a hash
+
+    ##
+    # Return a string in the form of "key=value,key=value" for a given hash
       def definition_string definition
         msg=Array.new
         definition.each{|k,v| msg<<"#{k}=#{v}"}
         return msg.join(",")
       end
 
+    ##
+    # Convert the given filename to an absolute path if the file exists or
+    # otherwise return the passed filename as is
       def full_path filename
         return File.expand_path(filename) if File.exist?(filename)
         return filename
       end
     end
 
+  ##
+  # Exception which is being raised upon errors concerning configurations passed
+  # to rutema
+  #
+  # This may be caused by e.g.:
+  #
+  # * a file or path could not be found/does not exist
+  # * passed hash arguments being of an unexpected/unhandled type
+  # * passed hash arguments missing required keys
     class ConfigurationException<RuntimeError
     end
-    #The object we pass around after we load the configuration from file
-    #
-    #All relevant methods are in Rutema::ConfigurationDirectives
+
+  ##
+  # Class for reading, parsing and representing the configuration for a rutema
+  # test run
+  #
+  # The instance will be passed around during testing and instruct each
+  # component which tests to execute how.
+  #
+  # Rutema::ConfigurationDirectives defines all relevant methods and attributes.
     class Configuration
       include ConfigurationDirectives
+
+    ##
+    # The filename of the root configuration file from which the Configuration
+    # instance was built
       attr_reader :filename
+
+    ##
+    # Create a new instance by parsing the given configuration file
+    #
+    # * +config_file+ - the configuration file which shall be parsed on
+    #   initializing the new instance
       def initialize config_file
         @filename=config_file
         init
         load_configuration(@filename)
       end
 
+    ##
+    # Yield the instance itself if a block is given
+    #
+    # This can be used e.g. in configuration files to execute a block on the
+    # Configuration instance itself (e.g. to modify it through the setter
+    # methods of the ConfigurationDirectives module).
       def configure
         if block_given?
           yield self
         end
       end
-      #Loads the configuration from a file
-      #
-      #Use this to chain configuration files together
-      #==Example
-      #Say you have on configuration file "first.rutema" that contains all the generic directives and several others that change only one or two things. 
-      #
-      #You can import the first.rutema file in the other configurations with
-      # import("first.rutema")
+
+    ##
+    # Load and import the configuration from a file
+    #
+    # This method can be used to chain configuration files together.
+    #
+    # === Example
+    #
+    # If there is a configuration file "main.rutema" which contains all the
+    # generic directives and several others which modify specific aspects, then
+    # the specialized configurations can import the "main.rutema" as follows:
+    #
+    #     import("main.rutema")
       def import filename
         fnm = File.expand_path(filename)
         if File.exist?(fnm)          
@@ -189,27 +361,34 @@
           raise ConfigurationException, "Import error: Can't find #{fnm}"
         end
       end
+
       private
+
+    ##
+    # Load the configuration from the file given by +filename+
+    #
+    # On many common parsing errors a ConfigurationException is being raised.
       def load_configuration filename
         begin 
           cfg_txt=File.read(filename)
           cwd=File.expand_path(File.dirname(filename))
-          #WORKAROUND for ruby 2.3.1
+          # WORKAROUND for ruby 2.3.1
           fname=File.basename(filename)
-          #evaluate in the working directory to enable relative paths in configuration
+          # evaluate in the working directory to enable relative paths in
+          # configuration
           Dir.chdir(cwd){eval(cfg_txt,binding(),fname,__LINE__)}
         rescue ConfigurationException
-          #pass it on, do not wrap again
+          # pass it on, do not wrap again
           raise
         rescue SyntaxError
-          #Just wrap the exception so we can differentiate
+          # just wrap the exception so we can differentiate
           raise ConfigurationException.new,"Syntax error in the configuration file '#{filename}':\n#{$!.message}"
         rescue NoMethodError
           raise ConfigurationException.new,"Encountered an unknown directive in configuration file '#{filename}':\n#{$!.message}"
         rescue 
-          #Just wrap the exception so we can differentiate
+          # just wrap the exception so we can differentiate
           raise ConfigurationException.new,"#{$!.message}"
         end
       end
     end
-  end
+  end