test4requirements 0.1.0.alpha.2

data/examples/example_test4requirements.rb

@@ -0,0 +1,62 @@
+=begin rdoc
+Some examples, how you can use test4requirements in your test.
+
+Expectes Testresults:
+  req1 successfull
+  req2 tested, but without success
+  req3 no test 
+  req4 successfull
+=end
+gem 'test-unit'#, '= 2.1.1'
+
+$:.unshift('../lib')
+require 'test4requirements.rb'
+
+$req = Test4requirements::RequirementList.new(:req1,:req2,:req3, :req4)
+#~ $req.log.outputters << Log4r::StdoutOutputter.new('stdout')
+#Define a user defined action after test execution.
+$req.do_after_tests{|reqlist|
+  puts reqlist.overview(nil)
+}
+
+=begin rdoc
+Example code
+=end
+module Examples
+=begin rdoc
+Test requirements 1 and 2.
+=end
+  class Test_requirement_1_2 < Test::Unit::TestCase
+    #Following requirements exist, and must be tested sucessfull
+    requirements $req
+    
+    #Test requirement 1.
+    def test_1()
+      assign_requirement(:req1)  #this test is testing requirement 1
+      assert_equal(2,1+1)
+    end
+    #Test requirement 2.
+    def test_2()
+      assign_requirement(:req2)
+      assert_equal(3,1+1)
+    end
+    #Test requirement 3, but without assignment to a requirement
+    def test_3()
+      #no assignment to requirement 3
+      pend 'pend'
+    end
+  end
+
+=begin rdoc
+Test requirement 4.
+=end
+  class Test_requirement_4 < Test::Unit::TestCase
+    #Following requirements exist, and must be tested sucessfull
+    requirements $req
+    #Test requirement 4.
+    def test_4()
+      assign_requirement(:req4)  #this test is testing requirement 4
+      assert_equal(2,1+1)
+    end
+  end
+end #module Examples

data/examples/example_test4requirements_shoulda.rb

@@ -0,0 +1,60 @@
+=begin rdoc
+Example code
+=end
+
+$:.unshift('../lib')
+gem 'test-unit'#, '= 2.1.1'
+
+require 'test4requirements'
+require 'test4requirements/shoulda'
+#~ require 'shoulda'
+
+$req = Test4requirements::RequirementList.new(:req1,:req2,:req3, :req4, :req5)
+#~ $req.log.outputters << Log4r::StdoutOutputter.new('stdout')
+
+=begin rdoc
+Example code
+=end
+module Examples
+=begin rdoc
+Some examples, how you can use test4requirements with shoulda.
+
+Expected result:
+
+  Requirement req1 was successfull tested (fullfill request 1 (req. of customer X/Examples::Test_with_shoulda))
+  Requirement req2 was unsuccessfull tested (fullfill request 2 (req. of customer X/Examples::Test_with_shoulda))
+  Requirement req3 was successfull tested (request_3 (Examples::_with_shoulda/Examples::Test_with_shoulda))
+  Requirement req4 was successfull tested (request_4 (Examples::_with_shoulda/Examples::Test_with_shoulda))
+  Requirement req5 was not tested
+=end
+  class Test_with_shoulda < Test::Unit::TestCase
+    #Following requirements exist, and must be tested sucessfull
+    requirements $req
+
+    context 'req. of customer X' do
+      #Add requirement as parameter of should
+      should 'fullfill request 1', requirement: :req1  do
+        assert_equal(2,1+1)
+      end
+      #add requirement via requirement command
+      should 'fullfill request 2' do
+        assign_requirement(:req2)  #this test is testing requirement 1
+        assert_equal(3,1+1)
+      end
+    end #context
+
+    #Examples outside a context
+    
+    #Add requirement as parameter of should
+    should 'request_3', requirement: :req3  do
+      assert_equal(2,1+1)
+    end
+    
+    #add requirement via requirement command
+    should 'request_4' do
+      assign_requirement(:req4)  #this test is testing requirement 1
+      assert_equal(2,1+1)
+    end
+
+  end    #MyTest_shoulda
+end #module Examples

data/lib/test4requirements.rb

@@ -0,0 +1,98 @@
+=begin rdoc
+This gem is based on a 
+{question at stackoverflow}[http://stackoverflow.com/questions/6958586/are-there-any-good-ruby-testing-traceability-solutions]:
+
+:: Are there any gems that'll allow me to implement traceability from my tests back to designs/requirements?
+
+:: i.e.: I want to tag my tests with the name of the requirements they test, and then generate reports of requirements that aren't tested or have failing tests, etc.
+
+:title:test4requirements Unit-Testing with assignment to requirements
+
+=Usage
+  require 'test4requirements.rb'
+
+==Define RequirementList and Requirements
+You must define your requirements and a RequirementList.
+
+You can make it with simple keys and without description:
+  $req = Test4requirements::RequirementList.new(:req1,:req2,:req3, :req4)
+
+You may set an outputter to a logger:
+  $req.log.outputters << Log4r::StdoutOutputter.new('stdout')
+
+
+Or you can define an empty list and assign requirements
+with description etc.
+  $req = Test4requirements::RequirementList.new()
+  $req << Test4requirements::Requirement.new(
+            description: 'What is required',
+            reference: 'Customer Requirement, Version 2011-08-02, page 12'
+        )
+
+==Define your test cases
+
+With Test::Unit::TestCase.requirments you can assign a RequirementList to your tests.
+  class Test_requirement < Test::Unit::TestCase
+    #Following requirements exist, and must be tested sucessfull
+    requirements $req
+    # ...
+  end
+
+A RequirementList can be assigned to multiply TestCase.
+
+==Assign tests to requirements
+Tests can by assigned to a requirement with 
+Test::Unit::TestCase#assign_requirement.
+
+    #Test requirement 1.
+    def test_1()
+      assign_requirement(:req1)  #this test is testing requirement 1
+      assert_equal(2,1+1)
+    end
+
+==Get the result
+
+Unit-Test are executed at_exit. Your results are not available before the tests are ready.
+
+There are three ways to get information.
+
+===Standard reporting
+
+Like the Unit-Test results the requirement-result are written at the end 
+with Test4requirements::RequirementList#overview 
+
+You can influence the output with Test4requirements::RequirementList#report_type= 
+
+===Logger
+There is a logger. You have access to teh logger with Test4requirements::RequirementList#log.
+You can define outputters to the logger, you may log in a file to get more informations.
+You can log to STDOUT, but the logging will be mixed with the test output.
+
+===User defined actions
+Each action must be done at the end of the script.
+You may use Test4requirements::RequirementList#do_after_tests to define an
+action at the end of the script.
+
+=end 
+
+gem 'test-unit'
+=begin
+unittest 2.3.1:
+Test::Unit::Assertions uses Encoding#ascii_compatible?
+Is not defined in ruby 1.9.1 (at least my installation ;) )
+=end
+gem 'test-unit', '<= 2.1.1' if RUBY_VERSION == '1.9.1'
+require 'test/unit'
+
+module Test4requirements
+  VERSION = '0.1.0.alpha.2'
+end
+require 'log4r'
+require_relative 'test4requirements/testcase'
+require_relative 'test4requirements/requirement'
+require_relative 'test4requirements/requirementlist'
+
+#Not loaded by default.
+#require_relative 'test4requirements/shoulda'
+
+

data/lib/test4requirements/requirement.rb

@@ -0,0 +1,132 @@
+=begin rdoc
+Define a requirement.
+
+=end
+module Test4requirements
+  class Requirement
+    #Valid options for Requirement#new
+    OPTIONS = [
+      :description,
+      :reference,
+    ]
+=begin rdoc
+Each requirement must include a key.
+
+Optional values:
+* description
+* reference
+=end
+    def initialize( key, options = {} )
+      @key = key
+      options.keys.each{|key|
+        raise ArgumentError, "Key #{key} undefined" unless OPTIONS.include?(key)
+      }
+      @description = options[:description]
+      @reference = options[:reference]
+      
+      #TestCases. Key is TestCase name.
+      @tests = {}
+      
+    end
+    #Key of the requirement
+    attr_reader :key
+    #Description of the requirement
+    attr_reader :description
+    #Reference, e.g. 'Page 47, Requirement document 2'
+    attr_reader :reference
+    #Logger. Defined by RequirementList#<<
+    attr_accessor :log
+
+
+=begin rdoc
+Returns the result of a TestCase.
+
+* nil: no test found
+* false: Not successfull
+* true: Succesfull tested
+=end
+    def [](key)
+      @tests[key]
+    end
+
+=begin rdoc  
+Assign a TestCase.
+=end
+    def test=(loc)
+      @log.info("Test #{loc} assigned to requirement #{@key}") if @log and @log.info?
+      @tests[loc] = false   #Will be tested
+    end
+
+=begin rdoc  
+Mark a test as successfull.
+=end
+    def successfull_test(loc)
+      #fixme: Check if already defined?
+      #~ raise ArgumentError, "Successfull test #{loc} was never assigned" unless @tests.has_key?(loc)
+      @log.info("Test #{loc} successfull for to requirement #{@key}") if @log and @log.info?
+      @tests[loc] = true #Was successfull tested
+    end
+=begin rdoc
+Return false, if no test is defined.
+Else you get the number of tests.
+=end
+    def tested?()
+      return @tests.empty? ? false : @tests.size
+    end
+=begin rdoc
+Test, if the requirement was successfull.
+
+If there is one test without success, the requirement is not successfull solved.
+* nil: no test found
+* false: At least one test not successfull
+* true: Succesfull tested
+=end
+    def successfull?()
+      return nil if @tests.empty?
+      success = true
+      @tests.each{|key,result|
+        success = (success and result)
+      }
+      return success
+    end
+=begin rdoc
+Return a list of tests with test result.
+=end
+    def testresults()
+      #single tests: Only key returned
+      #~ return @tests.keys if @tests.size == 1
+      res_ok = []
+      res_err = []
+      @tests.each{|key, result|
+        #Convert key (for shoulda)
+        case key
+          when /^test: (.*) should (.*)\. \((.*)\)/
+            #old: test: _Shoulda should request_2. (Test_ShouldaTest)
+            #new: request_2 (_Shoulda/Test_ShouldaTest)
+            key = "#{$2} (#{$1}/#{$3})"
+        end
+      
+        if result
+          res_ok << key
+        else
+          res_err << key
+        end
+      }
+      #return filled array, if other array is empty
+      return res_ok if res_err.empty?
+      return res_err if res_ok.empty?
+      
+      [
+        "OK: #{res_ok.join(', ')}", 
+        "Failure: #{res_err.join(', ')}",
+      ]
+    end
+    
+    def to_s()
+      "<Requirement #{key}>"
+    end
+    #~ def inspect()
+      #~ "<Requirement #{key} #{@tests}>"
+    #~ end
+  end
+end #module Test4requirements

data/lib/test4requirements/requirementlist.rb

@@ -0,0 +1,163 @@
+module Test4requirements
+=begin rdoc
+Define a list of requirements.
+
+This class can be used in Test::Unit::TestCase#assign_requirement.
+=end
+  class RequirementList
+    class << self
+      #alternatives: nil, :stdout, :txt
+      #fixme: check valid values. see #report_type=
+      attr_accessor :report_type_default
+    end
+    #Set default report type.
+    self.report_type_default = :stdout
+=begin rdoc
+Define a list of requirements.
+
+Parameters will define the key of new Requirement, unless it is no Requirement.
+=end
+    def initialize( *reqs )
+      
+      @log = Log4r::Logger.new('ReqL')
+      
+      @requirements = {}
+      reqs.each{|req|
+      
+        #Define a requirement.
+        if ! req.is_a?(Requirement)
+          req = Requirement.new(req)
+        end
+
+        self << req
+      }
+      
+      #Yes, we need two at_exit.
+      #tests are done also at_exit.  With double at_exit, we are after that.
+      #Maybe better to be added later.
+      at_exit {
+        at_exit do 
+          self.overview
+        end 
+      }
+      @report_type = self.class.report_type_default # alternatives: nil, :stdout, :txt
+    end #initialize
+    #Logger
+    attr_reader :log
+=begin rdoc
+Add a new requirement.
+=end
+    def <<(req)
+      raise ArgumentError, "Requirement is no Requiremnt but #{req.inspect}" unless req.is_a?(Requirement)
+      @log.info("Add requirement #{req.key}") if @log.info?
+      if @requirements[req.key]
+        raise ArgumentError, "Requirement #{req.key} defined twice"
+      end
+      req.log= Log4r::Logger.new("#{@log.name}::#{req.key}") unless req.log
+      @requirements[req.key] = req
+    end
+=begin rdoc
+Returns Requirement
+=end
+    def [](key)
+      @requirements[key]
+    end
+=begin rdoc
+Assign a testcase to an requirement.
+
+Requires:
+* Requirement key
+* testcase (Class#methodname)
+=end
+    def assign_test(req, testcase)
+      raise ArgumentError unless @requirements[req]
+      @requirements[req].test= testcase
+    end
+=begin rdoc
+Report successfull test to the requirement.
+
+This requires a previous assignment with #assign_test.
+=end
+    def test_successfull(loc)
+      #~ raise ArgumentError unless @requirements[req]
+      @requirements.each{|key,req|
+        req.successfull_test(loc) unless req[loc].nil?
+      }
+    end
+=begin rdoc
+Defines, how and if an overview of the requirements are given.
+
+Used in #overview. More details see there.
+=end
+    def report_type=(key)
+      @log.info("Set report type #{key.inspect}") if @log.info?
+      case key 
+        when :stdout, nil, :txt
+          @report_type = key
+        else
+          raise ArgumentError, "Unknown report type #{key} for #{self.class}"
+      end
+    end 
+=begin rdoc
+Give an overview.
+
+Returns a hash with test results for the requirements.
+* true: Successfull tested
+* false: Unsuccessfull tested
+* nil: Not tested
+
+The parameter defines alternative report types:
+* nil: No output. Please evaluate the return value
+* stdout: Result is written to stdout.
+* :txt: The text of stdout as an Array
+=end
+    def overview(report_type = @report_type )
+      
+      txt = []
+      hash = {}
+      
+      @requirements.each{|key, req|
+        if req.successfull?
+          txt << "Requirement #{key} was successfull tested (#{req.testresults.join(', ')})"
+          hash[key] = true
+        elsif req.tested?
+          txt << "Requirement #{key} was unsuccessfull tested (#{req.testresults.join(', ')})"
+          hash[key] = false
+        else
+          txt << "Requirement #{key} was not tested"
+          hash[key] = nil
+        end
+      }
+
+      case report_type
+        when :stdout
+          puts "Requirements overview:"
+          puts txt.join("\n")
+        when :txt
+          return txt
+        when nil 
+          return hash
+        else
+          raise ArgumentError, "Undefined report type #{report_type}"
+        end
+      
+    end #overview
+=begin rdoc
+Define an action at the end of the script (after the test).
+
+This method can be used for user defined actions after test execution.
+=end
+    def do_after_tests
+      raise ArgumentError, "do_after_tests: called without a block" unless block_given?
+      #Yes, we need two at_exit.
+      #The inner at_exit defines the action,
+      #the outer at_exit defines the action at the end. 
+      #So it will be after the at_exit used by unit-test runner.
+      at_exit{
+        at_exit{
+          yield self
+        }
+      }
+    end #at_exit
+  end #RequirementList
+end #module Test4requirements