rubyunit 0.0.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 28a9809b472a236515ef571df2e8547159e86069
-  data.tar.gz: 0ea9d91b0c0ca5cc31d1a499d55ac511780117ac
+  metadata.gz: 59aa4f7b242f3ddc81d73520e4325a2b025004fb
+  data.tar.gz: f6cb7b9b0a8445b43e2e669be8e8904eeb763473
 SHA512:
-  metadata.gz: a9ade60f35da0753441b01ac931cda5bf8d224815b7dc2465f00322e7eb8d4ca28b4528b47c481d80efb421cb57874010c3954caa307a742722629a45000d06d
-  data.tar.gz: 75897620958a179618807275c86c57e2813eecc712196b407ae125cc7cb37fee90d504f05c7e3c1ba1be93900696a8cdde204a8c41876e0b54a4d38821500b42
+  metadata.gz: 875ebe75d487403a20c131f079d2b8c94aa84da7bda10a2dc7a98d33209d170906be19a975bc0133060978a7e13aaeadfbae5960f56d29673f3cc073bb5c71c0
+  data.tar.gz: 6dd66e51da74b120b158a90c1fe8364a1539a0af33a29f0eaa30712869af383b4a6475aa2361656bdb3989e6d1b14715d0f7fd43db3ca7e361c7331d0688a13e

data/README.md

@@ -1,27 +1,34 @@
 RubyUnit
 ========
 
-[![Gem Version](https://badge.fury.io/rb/rubyunit.png)](http://badge.fury.io/rb/rubyunit)
+[![Gem Version](https://badge.fury.io/rb/rubyunit.svg)](http://badge.fury.io/rb/rubyunit)
 [![Code Climate](https://codeclimate.com/github/RubyUnit/RubyUnit/badges/gpa.svg)](https://codeclimate.com/github/RubyUnit/RubyUnit)
 [![Test Coverage](https://codeclimate.com/github/RubyUnit/RubyUnit/badges/coverage.svg)](https://codeclimate.com/github/RubyUnit/RubyUnit)
 
+### Practical Examples
+* https://github.com/matthewclower/PlayingCards
+
 
+### Links
 * http://rubyunit.github.io/
 * https://github.com/RubyUnit/RubyUnit
 
 
-# Practical Examples
-* https://github.com/matthewclower/PlayingCards
-
-## Description
+### Description
 
-A simple Unit Test framework for Ruby.
-- Currently tested with Ruby 2.1.1
+Unit testing and test-driven development is a crucial part of the software
+development life cycle. This tool is intended to make development and
+testing in Ruby easier on everyone.
 
-## Install
+### Install
 
 ```bash
 $ gem install rubyunit
 ```
 
-## License LGPL
+### Contact
+Please submit issues and feature requests to the github issue tracking page
+https://github.com/RubyUnit/RubyUnit/issues
+
+
+* Copyright (c) 2014, Matthew Clower

data/example/TestSet.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 # require RubyUnit framework
-require 'RubyUnit'
+require_relative '../lib/RubyUnit'
 
 # Example test for RealNumber mixin
 require_relative 'RealNumberTest'

data/lib/RubyUnit/AssertionFailure.rb

@@ -1,4 +1,11 @@
 module RubyUnit
+  #
+  # = RubyUnit::AssertionFailure
+  # Exception that is raised when a test assertion fails.
+  #
+  # TODO add some things to this object:
+  # * Excpetion info so that better reporting can be generated
+  # 
   class AssertionFailure < StandardError
   end
 end

data/lib/RubyUnit/Runner.rb

@@ -2,18 +2,44 @@ require_relative 'TestCase'
 require_relative 'AssertionFailure'
 
 module RubyUnit
+  #
+  # This is the test runner.
+  # Done, and done.
+  #
   class Runner
     class << self
       protected
+      #--
+      # Most of these variables need to be refactored.  This is made so it can
+      # be used, but it's not very far along.
+      #++
+      # The list of Test Cases that have been run are are currently running
       @@test_cases = []
+      # The list of RubyUnit::AssertionFailure exceptions that were caught by the
+      # test runner during testing
       @@failures   = []
+      # The list of non RubyUnit::AssertionFailure exceptions that were caught by
+      # the test runner during testing
       @@errors     = []
+      # The total number of tests that have been run
       @@tests      = 0
+      # The time the tests were started
       @@start      = nil
+      # The time the tests completed
       @@finish     = nil
+      # Whether or not the test suite still needs to be run. This is used by the
+      # automatic runner to determine if it must be run before the program exits.
       @@autorun    = true
 
       public
+      #
+      # The static test runner
+      # * raises ArgumentError if any data method doesn't return an array
+      # * raises ArgumentError if any data method doesn't return an array of arrays
+      # * Returns the sum of the failure and error counts
+      #
+      #  RubyUnit::Runner.run
+      #
       def run
         @@autorun = false
         @@start   = Time.new
@@ -30,9 +56,9 @@ module RubyUnit
               test_case = object.new
               data      = test_case.send data_method
 
-              raise "Data method #{data_method} must return an array" unless data.is_a? Array
+              raise ArgumentError, "Data method #{data_method} must return an array" unless data.is_a? Array
               data.each do |params|
-                raise "Data method #{data_method} must return an array of arrays" unless data.is_a? Array
+                raise ArgumentError, "Data method #{data_method} must return an array of arrays" unless data.is_a? Array
                 runner.run object, test, params
               end
             else
@@ -45,14 +71,26 @@ module RubyUnit
         @@failures.count + @@errors.count
       end
 
+      #
+      # Whether or not the test suite still needs to be run. This is used by the
+      # automatic runner to determine if it must be run before the program exits.
+      #
+      #  RubyUnit::Runner.autorun?
+      # 
       def autorun?
         @@autorun
       end
 
       protected
+      #
+      # Prints the report after testing has been completed.  This mehtod is protected and
+      # is called by the global runner unless no tests have been run.
+      #
+      #  report # => nice and simple
+      #
       def report
         # haven't figured out what I want to do for reporting yet but I need some results
-        puts "RubyUnit #{RubyUnit::version}"
+        puts "RubyUnit #{RubyUnit::VERSION}"
         puts "Started Tests #{@@start.strftime("%Y-%m-%d %H:%M:%S")}"
 
         puts "#{@@errors.count} Errors:\n" if @@errors.count > 0
@@ -76,11 +114,27 @@ module RubyUnit
         puts "%.3f tests/s, %.3f assertions/s" % [(@@tests * inverse).to_f, (TestCase.assertions * inverse).to_f]
         puts "%d Tests, %d Assertions, %d Errors, %d Failures" % [@@tests, TestCase.assertions, @@errors.count, @@failures.count]
         puts
-        
       end
     end
 
     public
+    #
+    # Run a test and record the results. The test object is instantiated and
+    # RubyUnit::TestCase.setup is called. RubyUnit::TestCase.teardown is called
+    # after the test has finished. This is called by the static runner.
+    # * raises ArgumentError unless _params_ is an Array
+    #
+    # object::
+    #   The test case that has the test
+    #
+    # test::
+    #   The test that is going to be run
+    #
+    # params::
+    #   The parameters that are passed to test execution
+    #
+    #  run TestCaseClass, :myTest, [param1, param2]
+    #
     def run object, test, params = []
       raise ArgumentError, "Parameter list for #{object.class}::#{test} must be an array" unless params.is_a? Array
 

data/lib/RubyUnit/TestCase.rb

@@ -1,60 +1,224 @@
 require_relative 'AssertionFailure'
 
 module RubyUnit
+  #
+  # = RubyUnit::TestCase
+  #
+  # All classes derrived from the RubyUnit::TestCase will automatically be run by
+  # the test runner.
+  # * Test methods must currently be named ending in 'Test'
+  # * Data methods must currently be named ending in 'Data'
+  #   All data methods must return an array of arrays as param lists to passed to
+  #   the corresponding test method.
+  # * Exceptions raised in this class are generally caught by the RubyUnit::Runner
+  #
+  #  MyTest < RubyUnit::TestCase
+  #    def simpleData
+  #      [
+  #        [       1,   3],
+  #        ['string', nil],
+  #      ],
+  #    end
+  #
+  #    def simpleTest param1, param2
+  #      # run assertions
+  #    end
+  #  end
+  #
   class TestCase
     public
+
+    #
+    # The setup helper that is run before each test in the test case.
+    #
+    #  def setup
+    #    # create objects, set up the scenario
+    #  end
+    #
     def setup
     end
 
+    #
+    # The teardown helper that is run after each test in the test case.
+    #
+    #  def teardown
+    #    # destroy objects, clean up after yourself
+    #  end
+    #
     def teardown
     end
 
     private
-    def __assertion &block
+    #
+    # The assertion wrapper is responsible for doing everything that must be done
+    # on each assertion.
+    # * keep track of the total number of assertions
+    #
+    # &block::
+    #   The assertion which is being wrapped
+    #
+    def __assertion &block # :nodoc:
       @@assertions += 1
       yield
     end
 
     protected
+    
+    #
+    # Fail the test. This is used when some conditioned outside the test warrants
+    # a test failure.
+    # * This is likely an indication of something unexpected or missing functionality
+    # * raises RubyUnit::AssertionFailure
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  fail "I wasn't expecting the moon to fall into Lake Michigan"  # => fail
+    #
     def fail message = nil
       __assertion do
         raise AssertionFailure, message
       end
     end
 
+    #
+    # Assert that a test condition is true.
+    # * raises RubyUnit::AssertionFailure unless _expected_ is true
+    #
+    # expected::
+    #   The value that is being checked for the assertion
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  assert false "This will fail"  # => fail
+    #
     def assert expected, message = nil
       __assertion do
         raise AssertionFailure, message unless expected
       end
     end
 
+    #
+    # Assert that a test condition is false.
+    # * raises RubyUnit::AssertionFailure if _expected_ is true
+    #
+    # expected::
+    #   The value that is being checked for the assertion
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  assertNot true "This will fail"  # => fail
+    #
     def assertNot expected, message = nil
       __assertion do
         raise AssertionFailure, message if expected
       end
     end
 
+    #
+    # Assert that two values are equal.
+    # * raises RubyUnit::AssertionFailure unless _expected_ equals _actual_
+    #
+    #--
+    # TODO It probably makes sense to rename _expected_ here
+    #++
+    # expected::
+    #   The value that is expected by the assertion
+    #
+    # actual::
+    #   The value that is being checked for the assertion
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  assertEqual 42, 24 "This will fail"  # => fail
+    #
     def assertEqual expected, actual, message = nil
       __assertion do
         raise AssertionFailure, message unless expected == actual
       end
     end
 
+    #
+    # Assert that two values are NOT equal.
+    # * raises RubyUnit::AssertionFailure if _expected_ equals _actual_
+    #
+    # expected::
+    #   The value that is not allowed by the assertion
+    #
+    # actual::
+    #   The value that is being checked for the assertion
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  assertNotEqual 3.14, 3.14 "This will fail"  # => fail
+    #
     def assertNotEqual expected, actual, message = nil
       __assertion do
         raise AssertionFailure, message if expected == actual
       end
     end
 
+    #
+    # Assert that a value matches a Regexp pattern.
+    # * raises RubyUnit::AssertionFailure unless _actual_ matches _pattern_
+    #
+    # pattern::
+    #   A Regexp pattern expected by the assertion
+    #
+    # actual::
+    #   The value that is being checked for the assertion
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  assertMatch /^Hello/, 'Goodbye!', "This will fail"  # => fail
+    #
     def assertMatch pattern, actual, message = nil
       __assertion do
         raise AssertionFailure, message unless actual =~ pattern
       end
     end
 
+    #
+    # Assert that a specified exception is raised.
+    # * raises RubyUnit::AssertionFailure unless the correct Exception is raised
+    # * raises ArgumentError unless the parameter count is positive
+    # * raises ArgumentError unless the first parameter is a descendent of the
+    #   Exception class
+    # * raises ArgumentError if the second parameter is provided and is not a
+    #   String, Regexp or nil
+    # * raises ArgumentError if the third parameter is provided and is not a
+    #   String or nil
+    #
+    # *args::
+    #   List of arguments passed in as [expected, pattern, message]. Additional
+    #   parameters are ignored.
+    #
+    # expected::
+    #   *required*: The Exception class that is expected.  The Exception must be a
+    #   descendent of the Exception class.
+    #
+    # pattern::
+    #   _optional_: The String or Regexp that will be used to validate the Exception
+    #   message
+    #
+    # message::
+    #   _optional_: The message provided to be reported for a failure
+    #
+    # &block::
+    #   The code block that is expected to throw the Exception
+    #
+    #  assertRaiseExpected Exception, /^Invalid/, 'Expecting an exception!' do
+    #    raise 'Invalid Retroincabulator'
+    #  end
+    #
     def assertRaiseExpected *args, &block
       __assertion do
-        raise ArgumentError, "wrong number of arguments (#{args.count} for 2..3)" unless args.count >= 1 
+        raise ArgumentError, "wrong number of arguments (#{args.count} for 2..3)" unless args.count > 0 
         expected, pattern, message = args
         raise ArgumentError, "expected exception must be a subclass of Exception" unless expected < Exception
         raise ArgumentError, "exception message must be a Regexp or String" unless pattern.is_a? Regexp or pattern.is_a? String or pattern.nil?
@@ -73,6 +237,20 @@ module RubyUnit
       end
     end
 
+    #
+    # Assert that no exception is raised.
+    # * raises RubyUnit::AssertionFailure if any exception is raised
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    # &block::
+    #   The code block that is executed
+    #
+    #  assertNothingRaised 'Not expecting an exception!' do
+    #    # do something
+    #  end
+    #
     def assertNothingRaised message = nil, &block
       __assertion do
         begin
@@ -83,34 +261,121 @@ module RubyUnit
       end
     end
 
+    #
+    # Assert that an object is an instance of the specified class or one of
+    # its descendents.
+    # * raises RubyUnit::AssertionFailure unless _object_ is an instance of
+    #   _klass_ or one of its descendents. 
+    #
+    # klass::
+    #   The class that is expected
+    #
+    # object::
+    #   The object that will be checked against _klass_
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  assertIsA String, 25, 'Nope, try again.'  # => fail
+    #
     def assertIsA klass, object, message = nil
       __assertion do
-        raise AssertionFailure, message unless klass.is_a? Class
+        raise AssertionFailure, message unless object.is_a? klass
       end
     end
 
+    #
+    # Assert that an object is an instance of a specified class
+    # * raises RubyUnit::AssertionFailure unless _object_ is an instance of
+    #   _klass_.
+    #
+    # klass::
+    #   The class that is expected
+    #
+    # object::
+    #   The object that will be checked against _klass_
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  assertInstanceOf Integer, '25', 'So close, but... No.'  # => fail
+    #
     def assertInstanceOf klass, object, message = nil
       __assertion do
-        assertIsA Class, klass, message
         raise AssertionFailure, message unless object.instance_of? klass
       end
     end
 
+    #
+    # Assert that two objects are the same object
+    # * raises RubyUnit::AssertionFailure unless _expected_ and _actual_ are
+    #   the same object.
+    #
+    # expected::
+    #   The expected object
+    #
+    # actual::
+    #   The object that is being checked against _expected_
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  assertSame '42', 42, 'Not even close.'  # => fail
+    #
     def assertSame expected, actual, message = nil
       __assertion do
         raise AssertionFailure, message unless expected.equal? actual
       end
     end
 
+    #
+    # Assert that two objects are not the same object
+    # * raises RubyUnit::AssertionFailure if _expected_ and _actual_ are the
+    #   same object.
+    #
+    #--
+    # TODO It probably makes sense to rename this one too
+    #++
+    # expected::
+    #   The expected that it shouldn't be
+    #
+    # actual::
+    #   The object that is being checked against _expected_
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  value = 42
+    #  assertSame value, value, 'Imagine that!'  # => fail
+    #
     def assertNotSame expected, actual, message = nil
       __assertion do
         raise AssertionFailure, message if expected.equal? actual
       end
     end
 
+    #
+    # Assert that a constant is defined correctly in the correct class
+    # * raises RubyUnit::AssertionFailure unless the constant is defined in
+    #   the specified class and it is the correct type and value
+    #
+    # expected::
+    #   The value that is expected for the constant
+    #
+    # klass::
+    #   The class where the constant should be defined
+    #
+    # konstant::
+    #   The name of the constant expressed as a String so that it can be
+    #   validated in the class
+    #
+    # message::
+    #   The message provided to be reported for a failure
+    #
+    #  assertConst 42, Numbers, 'TWENTYFOUR', 'So dyslexic.'  # => fail
+    #
     def assertConst expected, klass, konstant, message = nil
       __assertion do
-        assertIsA Class, klass, message
         value = klass.const_get konstant
         assertIsA expected.class, value, message
         assertEqual expected, value, message
@@ -118,14 +383,24 @@ module RubyUnit
     end
 
     class << self
+      private
+      # Tracks the total number of assertions made during the tests
       @@assertions = 0
 
+      public
+      #
+      # Gets a list of all the descendents of the RubyUnit::TestCase class.
+      # This is important when determining the tests that have been defined.
+      #
       def descendents
         ObjectSpace.each_object(Class).select do |object|
           object < self
         end
       end
-      
+
+      #
+      # Gets the current number of assertions that have been run while testing
+      #
       def assertions
         @@assertions
       end

data/lib/RubyUnit.rb

@@ -1,30 +1,44 @@
+#
+# = RubyUnit
+# A Simple Unit Test Framework for Ruby
+#
+# The RubyModule is the root object for all RubyUnit modules and classes.
+#
 module RubyUnit
-  @@build = 5
-  VERSION = '0.0'
+  # Current RubyUnit version
+  VERSION = '0.1.6'
 
-  protected
-  public
-  def self.debug?
-    @@debug
-  end
-  
-  def self.build
-    @@build
-  end
+  #
+  # RubyUnit::GemInfo contains data and functionality needed by the gem builder
+  # when building and distributing the RubyUnit gem.
+  #
+  module GemInfo
 
-  def self.version
-    "#{VERSION}.#{build}"
-  end
+    #
+    # Provides a list of all the files required by this gem
+    #
+    #  spec.files = RubyUnit::GemInfo.files
+    #
+    def self.files
+      # local one-off directory
+      static   = ['README.md', 'LICENSE']
+      # libraries
+      libs     = Dir['lib/**/*.rb']
+      # examples
+      examples = Dir['example/*.rb']
 
-  class GemInfo
-    class << self
-      def files
-        static   = ['README.md', 'LICENSE']
-        libs     = Dir['lib/**/*.rb']
-        examples = Dir['example/*.rb']
+      static + libs + examples
+    end
 
-        static + libs + examples
-      end
+    #
+    # Provides a longer description of the RubyUnit gem
+    #
+    #  spec.description = RubyUnit::GemInfo.description
+    #
+    def self.description
+      'Unit testing and test-driven development is a crucial part of the software ' +
+      'development life cycle. This tool is intended to make development and ' +
+      'testing in Ruby easier on everyone.'
     end
   end
 end
@@ -32,9 +46,18 @@ end
 require_relative 'RubyUnit/TestCase'
 require_relative 'RubyUnit/Runner'
 
-# Automatically run test cases
+# Automatically Run Test Cases if they haven't been run already
 Module.new do
+  #
+  # Automatically run defined Test Cases
+  #
+  #--
+  # TODO: add alias and call the alias so that the function doesn't break any
+  # functionality that may have also extended this event.  Before/After?
+  #++
+  #
   at_exit do
+    # Don't run if it there is an exception or it has already been run
     if $ERROR_INFO.nil? and RubyUnit::Runner.autorun?
       RubyUnit::Runner.run
     end

metadata

@@ -1,16 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: rubyunit
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Matthew Clower
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-12 00:00:00.000000000 Z
+date: 2014-10-13 00:00:00.000000000 Z
 dependencies: []
-description: 'Framework for Unit Testing in Ruby, examples: https://github.com/matthewclower/PlayingCards'
+description: Unit testing and test-driven development is a crucial part of the software
+  development life cycle. This tool is intended to make development and testing in
+  Ruby easier on everyone.
 email:
 - matthewclower@gmail.com
 executables: []
@@ -30,8 +32,10 @@ files:
 - lib/RubyUnit/TestCase.rb
 homepage: http://github.com/RubyUnit/RubyUnit
 licenses:
+- Ruby
 - LGPL
-metadata: {}
+metadata:
+  Issue Tracker: https://github.com/RubyUnit/RubyUnit/issues
 post_install_message: Happy Testing!
 rdoc_options: []
 require_paths:
@@ -51,5 +55,5 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Unit Test Framework
+summary: A Simple Unit Test Framework
 test_files: []