plsql_unit_test 0.1.0 → 0.1.1

data/README.md

@@ -0,0 +1,153 @@
+# PLSQL Unit Test
+
+This gem is intended to be used to test PLSQL code. Most of the test framework is provided by Test::Unit, and this gem simply adds a few convenience methods that are useful when unit testing PLSQL code.
+
+# Dependencies
+
+This gem depends on:
+
+ * [SimpleOracleJDBC](http://rubygems.org/gems/simpleOracleJDBC) to provide a JDBC interface to Oracle
+ * [Data_Factory](http://rubygems.org/gems/data_factory) to provide an mechanism for generating test data
+ * The Oracle ojdbc6.jar drivers should be in the jruby lib directory
+
+The gem also requires JRuby, mostly because SimpleOracleJDBC requires JRuby. It would be possible to make it run in MRI Ruby, but a different database interface would be required, using perhaps OCI8.
+
+# How to Create a PLSQL Unit Test Suite
+
+## Test Helper
+
+First, create a new directory for the tests. Then create a file called test_helper.rb, it should contain something like the following:
+
+    require 'rubygems'
+    require 'plsql_unit_test'
+    
+    PLSQLUnitTest::Setup.connect('sodonnel',         # user
+                                 'sodonnell',        # password
+                                 'local11gr2.world', # service
+                                 'localhost',        # IP address
+                                 '1521')             # port
+
+This code does two things. It loads the plsql\_unit\_test gem (which also requires SimpleOracleJDBC and data_factory), and then establishes a database interface / connection. The database interface is provided by an instance of SimpleOracleJDBC::Interface - check out the documentation of SimpleOracleJDBC to understand how to use it.
+
+This single database interface is shared across all the test classes in the test suite. It is actually stored in a class instance variable called @@db_interface within the Test::Unit::TestCase class.
+
+## Creating a Test
+
+The test framework is all provided by Test::Unit, so tests can be coded in exactly the same way as usual - have a look at the Test::Unit documentation to learn about all the features of Test::Unit. An example of a very simple test is as follows:
+
+    require './test_helper'
+    
+    class FirstTest < Test::Unit::TestCase
+    
+      def setup
+      end
+    
+      def teardown
+      end
+    
+      def test_db_connection_works
+        query = @@db_interface.execute_sql("select 1 from dual")
+        results = query.all_array
+    
+        assert_equal(1, results.length, 'There should be one row in     the result set')
+        assert_equal(1, results[0][0], 'The first and only row in the     result set should contain the value 1') 
+      end
+    
+    end
+
+There are two important points:
+
+ * Notice that the test_helper file is required as the first line of code. This is important as it connects to the database and loads the other required modules.
+ * The variable @@db_interface is available for database interactions
+
+## Running a Test
+
+As with simple Test::Unit test suites, tests can be executed by simply passing the test filename to JRuby:
+
+    $ jruby first_test_test.rb
+    Run options:
+    
+    # Running tests:
+    
+    .
+    
+    Finished tests in 0.125000s, 8.0000 tests/s, 16.0000 assertions/s.
+    
+    1 tests, 2 assertions, 0 failures, 0 errors, 0 skips
+
+## Test Runner
+
+Ideally, there should be one Ruby test class for each PLSQL procedure, function or package under test. In a large application there could be many files, so there needs to be a way to run all the tests in the suite. Create a file called test_runner.rb in the same directory as the tests, and put the following code in it:
+
+    current_dir = File.expand_path(File.dirname(__FILE__))
+    
+    # Find all files that end in _test.rb and require them ...
+    files = Dir.entries(current_dir).grep(/^[^#].+_test\.rb$/).sort
+    files.each do |f|
+      require File.join(current_dir, f)
+    end
+
+Now all the test files in the directory can be executed with a single command:
+
+    $ jruby test_runner.rb
+
+For this code to work, all files that contain tests should have filenames that end in _test.rb.
+
+# Additional Methods in Test::Unit::TestCase
+
+PLSQL\_Unit\_Test adds a few extra methods to Test::Unit.
+
+## Assert Methods
+
+When testing database code, it can be useful to ensure a given table has zero, one or a number of rows for a given where clause.
+
+To assert the users table has a single row for the username foouser:
+
+    assert_table_has_one_row("users", 
+                             "where username = 'foouser',
+                             "Ensure the users table has a single row")
+
+Similarly, to ensure the users table does not have a row:
+
+    assert_table_has_zero_rows("users", 
+                               "where username = 'foouser',
+                               "Ensure the users table zero rows")
+
+Finally, to check a table has a given number of rows:
+
+    assert_table_has_zero_rows("users",
+                               10 
+                               "where status = 'locked'
+                               "Ensure 10 users are locked")
+
+## Set The Database Interface
+
+An additional class method is available on Test::Unit::TestCase called set_db_interface. This stores the passed in object in @@db_interface. As this is a class variable, it is shared by all classes that sub-class Test::Unit::TestCase.
+
+    Test::Unit::TestCase.set_db_interface(my_db_interface)
+
+## Oracle Dates and Times
+
+Two further helper methods are available to format a Ruby Time object as an Oracle to_date string:
+
+    # Return a string representing the passed in Time object
+    # as an Oracle to_date string, down to the second
+    def time_as_oracle_dtm(time)
+      "to_date('#{time.strftime('%Y%m%d %H:%M:%S')}', 'YYYYMMDD HH24:MI:SS')"
+    end
+
+    # Return a string representing the passed in Time object
+    # as an Oracle to_date string, down to the day
+    def time_as_oracle_dt(time)
+      "to_date('#{time.strftime('%Y%m%d')}', 'YYYYMMDD')"
+    end
+
+# The Setup Class
+
+The only other class in PLSQL\_Unit\_Test is the setup class, and it contains a single class method:
+
+    def self.connect(user, password, service, host, port)
+      # ...
+    end
+
+It takes the given parameters, creates an instance of SimpleOracleJDBC and passes it to both Test::Unit::TestCase and DataFactory::Base via their set_database_interface methods.

data/Rakefile.rb

@@ -0,0 +1,30 @@
+desc "Generate RDoc"
+task :doc => ['doc:generate']
+
+namespace :doc do
+  project_root = File.expand_path(File.dirname(__FILE__))
+  doc_destination = File.join(project_root, 'doc')
+
+  begin
+    require 'yard'
+    require 'yard/rake/yardoc_task'
+
+    YARD::Rake::YardocTask.new(:generate) do |yt|
+      yt.files   = Dir.glob(File.join(project_root, 'lib/**/*.rb')) + #, '**', '*.rb')) +
+                   [ File.join(project_root, 'README.md') ]
+      puts yt.files
+      yt.options = ['--output-dir', doc_destination, '--readme', 'README.md']
+    end
+  rescue LoadError
+    desc "Generate YARD Documentation"
+    task :generate do
+      abort "Please install the YARD gem to generate rdoc."
+    end
+  end
+
+  desc "Remove generated documenation"
+  task :clean do
+    rm_r doc_dir if File.exists?(doc_destination)
+  end
+
+end

data/lib/plsql_unit_test/setup.rb

@@ -1,5 +1,13 @@
 module PLSQLUnitTest
   class Setup
+
+    # Establishes a database connection using the SimpleOracleJDBC::Interface 
+    # class. This interface is then passed to both Test::Unit::TestCase
+    # and DataFactory::Base using their set_database_interface methods.
+    #
+    # After calling this method, the class instance variable @@db_interface
+    # will be available in all sub-classes of Test::Unit::TestCase and can 
+    # be used for database interactions.
     def self.connect(user, password, service, host, port)
       interface = SimpleOracleJDBC::Interface.create(user,
                                                      password,

data/lib/plsql_unit_test/test_unit_patch.rb

@@ -1,18 +1,53 @@
 class Test::Unit::TestCase
 
-
+  # Sets the class instance variable @@db_interface to the 
+  # object that is passed in
   def self.set_database_interface(interface)
     @@db_interface = interface
   end
 
+  # Used to assert / test a given table has only a single row.
+  # If a where clause is passed, it should start with 'where'. The table 
+  # name and where clause are used to form a select statement in the form:
+  #
+  #    "select count(*) from #{table} #{where_clause}"
+  #
+  # @example Assert the users table has a single row for user foouser
+  #     assert_table_has_one_row('users', 
+  #                              "where username = 'foouser'",
+  #                              "Ensure the users table has a single row")
+  # 
   def assert_table_has_one_row(table, where_clause=nil, message=nil)
     assert_table_has_many_rows(table, 1, where_clause, message)
   end
 
+  # Used to assert / test a given table has zero rows.
+  # If a where clause is passed, it should start with 'where'. The table 
+  # name and where clause are used to form a select statement in the form:
+  #
+  #    "select count(*) from #{table} #{where_clause}"
+  #
+  # @example Assert the users table has zero rows for user foouser
+  #     assert_table_has_zero_rows('users', 
+  #                                "where username = 'foouser'",
+  #                                "Ensure the users table has zero rows")
+  # 
   def assert_table_has_zero_rows(table, where_clause=nil, message=nil)
     assert_table_has_many_rows(table, 0, where_clause, message)
   end
 
+  # Used to assert / test a given table has a given number of rows.
+  # If a where clause is passed, it should start with 'where'. The table 
+  # name and where clause are used to form a select statement in the form:
+  #
+  #    "select count(*) from #{table} #{where_clause}"
+  #
+  # @example Assert the users table has zero rows for user foouser
+  #     assert_table_has_many_rows('users', 
+  #                                 10
+  #                                "where status = 'locked'",
+  #                                "Ensure the users table has 10 locked rows")
+  # 
   def assert_table_has_many_rows(table, row_count, where_clause=nil, message=nil)
     results = @@db_interface.execute_sql("select count(*) from #{table} #{where_clause}").all_array
     message = build_message(message, "A count of <?> was expected but was <?> for <?> <?>", row_count.to_s, results[0][0].to_i, table, where_clause)
@@ -21,10 +56,14 @@ class Test::Unit::TestCase
     end
   end
 
+  # Returns a string representing an Ruby Time object in Oracle to_date
+  # format, accurate to a second.
   def time_as_oracle_dtm(time)
     "to_date('#{time.strftime('%Y%m%d %H:%M:%S')}', 'YYYYMMDD HH24:MI:SS')"
   end
 
+  # Returns a string representing an Ruby Time object in Oracle to_date
+  # format, accurate to a day.
   def time_as_oracle_dt(time)
     "to_date('#{time.strftime('%Y%m%d')}', 'YYYYMMDD')"
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plsql_unit_test
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,14 +9,14 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-04 00:00:00.000000000 Z
+date: 2013-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: data_factory
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - '='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 0.1.2
   type: :runtime
@@ -24,7 +24,7 @@ dependencies:
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - '='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 0.1.2
 - !ruby/object:Gem::Dependency
@@ -32,7 +32,7 @@ dependencies:
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - '='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 0.1.1
   type: :runtime
@@ -40,7 +40,7 @@ dependencies:
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - '='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 0.1.1
 description: Monkey patches Test::Unit::TestCase to add some additional assert methods,
@@ -55,6 +55,7 @@ files:
 - lib/plsql_unit_test/setup.rb
 - lib/plsql_unit_test/test_unit_patch.rb
 - lib/plsql_unit_test.rb
+- Rakefile.rb
 - README.md
 homepage: http://betteratoracle.com
 licenses: []