rutema 2.0.0.pre15 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 00d7a4f19073abcdc37a290d8515fbecb4220c1d
-  data.tar.gz: 6a4e2926eeca77c79578fca7113a84c6e9810885
+  metadata.gz: a5e0e4c18d2eab07c25f48a69bcdc1b107be341d
+  data.tar.gz: 2c7b678e57ff73713a0aa1dda240144650203351
 SHA512:
-  metadata.gz: 0a69bcdb242e8feb2fef37f8fff62c1680c127a2d240f1cb034fe1306e605162c1fc97262795c3aa6d85cf925541bab1ee6bb8eed54f4eb55e2c300d6171395c
-  data.tar.gz: 51f7a2cdb69bd39498bfefbe31820ff9a8b8d136bb2302b8be047e8af8aaaa62eea107daa8e11b357d57367b4f799a2e3f30380374ec863a74f88c2ea060158b
+  metadata.gz: 60f93501c1a3c659effff6f8c3eed6bd2f9e0b1384df14629c92b599d6c2ce57dede0491de2679ca7231a42a77e61269ed822e9531d69815a2ccdc4a6e02f87a
+  data.tar.gz: ec9a4ab8dd76ef4dcd606008d02cd9e00bd7786948b44a860ae45f4676c9128c2802418b3ea0566a7ea24c63d3d17cca33e8c18cdc874ad0ab06f5c5fb2f3624

data/History.txt

@@ -1,3 +1,5 @@
+== 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
  * Update gem dependencies
 == 2.0.0.pre14 /2017-01-11
@@ -27,7 +29,7 @@
 == 2.0.0.pre5 /2015-09-14
  * Add JUnit format reporter
  * The NUnit format is v3, which means it won't work for most CI plugins
-== 2.0.0 /2015-09-10
+== 2.0.0.pre2 /2015-09-10
  * Completely rewritten execution engine
    * dropped Ruby 1.8.x, 1.9.x support, added 2.x
  * Rewritten configuration engine and new format for configuration files

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)
+## 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)
 
 rutema [http://github.com/damphyr/rutema](http://github.com/damphyr/rutema)
 
@@ -9,7 +9,8 @@ It enables the combination of different test tools while it takes care of loggin
 
 It's purpose is to make testing in heterogeneous environments easier. 
 
-###Why?
+### Why?
+
 Require consistency, repeatability and reliability from your test infrastructure while gathering data on every run.
 
 Whether running through a checklist of manual steps, or executing a sequence of fully automated commands we always want to know if a test has failed, where it failed and what was the state of the system at that time.
@@ -18,23 +19,33 @@ rutema will gather all logs, timestamp them, store them and report on them.
 
 Rutema core provides a reference implementation of a parser for a simple but extensible XML test specification format which works well out of the box but the framework provides clearly defined interfaces so you can write the parser for your own format and add reporters that log wherever is needed.
 
-###The dry stuff
+### The dry stuff
+
 * Unified test execution environment for automated and manual tests
 * Extensible reports and notifications in various formats (email, rss, pdf, html etc.)
 * A well defined way to create a project specific test specification format
 
+### Further Reading
+
+* [Configuring rutema](doc/CONFIGURATION.md)
+* An [example](doc/EXAMPLE.md) of a (very simple) testing DSL with rutema 
+* High level [description](README.md) of the concepts behind rutema
+
 ## Installation:
+
 * gem install rutema
 
 ## Dependencies
+
 The core functionality of rutema depends on the following gems:
  * [patir](http://github.com/damphyr/patir)
  * [highline](http://highline.rubyforge.org/)
 
 ## License:
+
 (The MIT License)
 
-Copyright (c) 2007-2015 Vassilis Rizopoulos
+Copyright (c) 2007-2017 Vassilis Rizopoulos
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -53,4 +64,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/bin/rutema

@@ -1,4 +1,5 @@
-#  Copyright (c) 2007-2015 Vassilis Rizopoulos. All rights reserved.
+#!/usr/bin/env ruby
+#  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
 require 'rutema/application'
 begin
 	Rutema::App.new(ARGV)

data/lib/rutema/core/configuration.rb

@@ -1,4 +1,4 @@
-  #  Copyright (c) 2007-2015 Vassilis Rizopoulos. All rights reserved.
+  #  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
   require 'ostruct'
   require_relative 'parser'
   require_relative 'reporter'
@@ -47,21 +47,18 @@
         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.
       def setup= path
         @setup=check_path(path)
       end
-      
       #Path to the teardown specification. (optional)
       #
       #The teardown test runs after every test.    
       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.
@@ -75,14 +72,12 @@
 
       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.
       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.
       def context= definition
@@ -90,7 +85,6 @@
         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.
@@ -98,7 +92,6 @@
       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.
@@ -111,7 +104,6 @@
         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.
@@ -124,7 +116,6 @@
         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.
@@ -134,7 +125,7 @@
         raise ConfigurationException,"required key :class is missing from #{definition}" unless definition[:class]
         @reporters[definition[:class]]=definition
       end
-
+      #:stopdoc
       def init
         @reporters={}
         @context={}
@@ -142,6 +133,7 @@
         @tools=OpenStruct.new
         @paths=OpenStruct.new
       end
+      #:startdoc
       private 
       #Checks if a path exists and raises a ConfigurationException if not
       def check_path path
@@ -164,7 +156,9 @@
 
     class ConfigurationException<RuntimeError
     end
-
+    #The object we pass around after we load the configuration from file
+    #
+    #All relevant methods are in Rutema::ConfigurationDirectives
     class Configuration
       include ConfigurationDirectives
       attr_reader :filename
@@ -179,7 +173,6 @@
           yield self
         end
       end
-    
       #Loads the configuration from a file
       #
       #Use this to chain configuration files together

data/lib/rutema/core/engine.rb

@@ -1,4 +1,4 @@
-#  Copyright (c) 2007-2015 Vassilis Rizopoulos. All rights reserved.
+#  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
 require 'thread'
 require_relative 'parser'
 require_relative 'reporter'
@@ -6,6 +6,11 @@ require_relative 'runner'
 require_relative '../version'
 
 module Rutema
+  #Rutema::Engine implements the rutema workflow.
+  #
+  #It instantiates the configured parser, runner and reporter instances and wires them together via Rutema::Dispatcher
+  #
+  #The full workflow is Parse->Run->Report and corresponds to one call of the Engine#run method
   class Engine
     include Messaging
     def initialize configuration
@@ -24,18 +29,15 @@ module Rutema
       @dispatcher=Dispatcher.new(@queue,configuration)
       @configuration=configuration
     end
+    #Parse, run, report
     def run test_identifier=nil
       @dispatcher.run!
       #start
       message("start")
       suite_setup,suite_teardown,setup,teardown,tests=*parse(test_identifier)
-      if tests.empty?
-        if test_identifier && is_special?(test_identifier)
-          run_scenarios([suite_setup],nil)
-        else
-          @dispatcher.exit
-          raise RutemaError,"Did not parse any tests succesfully"
-        end
+      if tests.empty?  
+        @dispatcher.exit
+        raise RutemaError,"No tests to run!"
       else
         @runner.setup=setup
         @runner.teardown=teardown
@@ -47,14 +49,15 @@ module Rutema
       @dispatcher.exit
       @dispatcher.report(tests)
     end
+    #Parse a single test spec or all the specs listed in the configuration
     def parse test_identifier=nil
       specs=[]
       #so, while we are parsing, we have a list of tests
       #we're either parsing all of the tests, or just one
       #make sure the one test is on the list
       if test_identifier
-        if  is_spec_included?(test_identifier)
-          specs<<parse_specification(File.expand_path(test_identifier)) unless is_special?(test_identifier)
+        if is_spec_included?(test_identifier)
+          specs<<parse_specification(File.expand_path(test_identifier))
         else
           error(File.expand_path(test_identifier),"does not exist in the configuration")  
         end
@@ -67,15 +70,16 @@ module Rutema
     end
     private
     def parse_specifications tests
-      tests.map{|t| parse_specification(t)}.compact
+      tests.map do |t| 
+        parse_specification(t)
+      end.compact
     end
     def parse_specification spec_identifier
       begin
         @parser.parse_specification(spec_identifier)
       rescue Rutema::ParserError
         error(spec_identifier,$!.message)
-        raise Rutema::ParserError, "In #{spec_identifier}: #{$!.message}" if is_special?(spec_identifier)
-        nil
+        raise Rutema::ParserError, "In #{spec_identifier}: #{$!.message}" 
       end
     end
     def parse_specials configuration
@@ -143,7 +147,13 @@ module Rutema
       full_path==@configuration.teardown 
     end
   end
+  #The Rutema::Dispatcher functions as a demultiplexer between Rutema::Engine and the various reporters.
+  #
+  #In stream mode the incoming queue is popped periodically and the messages are destributed to the queues of any subscribed event reporters.
+  #
+  #By default this includes Rutema::Reporters::Collector which is then used at the end of a run to provide the collected data to all registered block mode reporters 
   class Dispatcher
+    #The interval between queue operations
     INTERVAL=0.01
     def initialize queue,configuration
       @queue = queue
@@ -159,6 +169,7 @@ module Rutema
       @streaming_reporters<<@collector
       @configuration=configuration
     end
+    #Call this to establish a queue with the given identifier
     def subscribe identifier
       @queues[identifier]=Queue.new
       return @queues[identifier]

data/lib/rutema/core/framework.rb

@@ -22,7 +22,7 @@ module Rutema
       return msg
     end
   end
-
+  #What it says on the tin.
   class ErrorMessage<Message
     def to_s
       msg="ERROR - "
@@ -31,7 +31,6 @@ module Rutema
       return msg
     end
   end
-
   #The Runner continuously sends these when executing tests
   #
   #If there is an engine error (e.g. when parsing) you will get an ErrorMessage, if it is a test error
@@ -62,7 +61,6 @@ module Rutema
       return msg.chomp
     end
   end
-
   #While executing tests the state of each test is collected in an 
   #instance of ReportState and the collection is at the end passed to the available block reporters
   #
@@ -88,9 +86,11 @@ module Rutema
   end
 
   module Messaging
+    #Signal an error - use the test name/id as the identifier
     def error identifier,message
       @queue.push(ErrorMessage.new(:test=>identifier,:text=>message,:timestamp=>Time.now))
     end
+    #Informational message during test runs
     def message message
       case message
       when String

data/lib/rutema/core/objectmodel.rb

@@ -1,4 +1,4 @@
-#  Copyright (c) 2007-2015 Vassilis Rizopoulos. All rights reserved.
+#  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
 require 'patir/command'
 
 module Rutema
@@ -197,7 +197,6 @@ module Rutema
       return "#{@attributes[:step_type]}#{param}"
     end
     def to_s#:nodoc:
-      param=""
       if self.has_cmd?
         msg="#{self.number} - #{self.cmd.to_s}"
       else

data/lib/rutema/core/parser.rb

@@ -1,4 +1,4 @@
-#  Copyright (c) 2007-2015 Vassilis Rizopoulos. All rights reserved.
+#  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
 require_relative 'framework'
 
 module Rutema

data/lib/rutema/core/reporter.rb

@@ -1,4 +1,4 @@
-#  Copyright (c) 2007-2015 Vassilis Rizopoulos. All rights reserved.
+#  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
 module Rutema
   #Rutema supports two kinds of reporters.
   #

data/lib/rutema/core/runner.rb

@@ -1,4 +1,4 @@
-#  Copyright (c) 2007-2015 Vassilis Rizopoulos. All rights reserved.
+#  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
 
 require_relative "framework"
 

data/lib/rutema/elements/minimal.rb

@@ -1,4 +1,4 @@
-#  Copyright (c) 2007-2015 Vassilis Rizopoulos. All rights reserved.
+#  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
 require 'highline'
 module Rutema
   #The Elements module provides the namespace for the various modules adding parser functionality

data/lib/rutema/parsers/xml.rb

@@ -1,4 +1,4 @@
-#  Copyright (c) 2007-2015 Vassilis Rizopoulos. All rights reserved.
+#  Copyright (c) 2007-2017 Vassilis Rizopoulos. All rights reserved.
 require 'rexml/document'
 require 'patir/command'
 require_relative '../core/parser'

data/lib/rutema/version.rb

@@ -3,7 +3,7 @@ module Rutema
   module Version
     MAJOR=2
     MINOR=0
-    TINY="0.pre15"
+    TINY=0
     STRING=[ MAJOR, MINOR, TINY ].join( "." )
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rutema
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre15
+  version: 2.0.0
 platform: ruby
 authors:
 - Vassilis Rizopoulos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-09 00:00:00.000000000 Z
+date: 2017-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: patir
@@ -71,8 +71,7 @@ description: "rutema [http://github.com/damphyr/rutema](http://github.com/damphy
   across different tools.\n\nIt enables the combination of different test tools while
   it takes care of logging, reporting, archiving of results and formalizes execution
   of automated and manual tests.\n\nIt's purpose is to make testing in heterogeneous
-  environments easier. \n\n###Why?\nRequire consistency, repeatability and reliability
-  from your test infrastructure while gathering data on every run."
+  environments easier. \n\n### Why?"
 email:
 - vassilisrizopoulos@gmail.com
 executables:
@@ -117,9 +116,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.5.2