plsql_unit_test 0.1.1 → 0.2.0

data/README.md

@@ -104,22 +104,30 @@ When testing database code, it can be useful to ensure a given table has zero, o
 To assert the users table has a single row for the username foouser:
 
     assert_table_has_one_row("users", 
-                             "where username = 'foouser',
+                             "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',
+                               "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",
+    assert_table_has_many_rows("users",
                                10 
-                               "where status = 'locked'
+                               "where status = 'locked'"
                                "Ensure 10 users are locked")
 
+It is also possible to pass an array as the where clause instead of a string. In this case, the first element of the array should be a string containing the where clause with bind variable placeholders. The remaining elements of the array are the bind variables. Ruby types are automatically converted to Oracle types by SimpleOracleJDBC behind the scenes. For example:
+
+    assert_table_has_many_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.

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/lib/plsql_unit_test/test_unit_patch.rb

@@ -1,55 +1,88 @@
 class Test::Unit::TestCase
 
-  # Sets the class instance variable @@db_interface to the 
+  # 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 
+  # 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', 
+  #     assert_table_has_one_row('users',
   #                              "where username = 'foouser'",
   #                              "Ensure the users table has a single row")
-  # 
+  #
+  # It is possible to pass an array for the where clause, where the first
+  # element is the where string with bind placeholders, and the remaining
+  # elements are the bind variables:
+  #
+  # @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 
+  # 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', 
+  #     assert_table_has_zero_rows('users',
   #                                "where username = 'foouser'",
   #                                "Ensure the users table has zero rows")
-  # 
+  #
+  # It is possible to pass an array for the where clause, where the first
+  # element is the where string with bind placeholders, and the remaining
+  # elements are the bind variables:
+  #
+  # @example Assert the users table has a single row for user foouser
+  #     assert_table_has_zero_row('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 
+  # 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', 
+  #     assert_table_has_many_rows('users',
   #                                 10
   #                                "where status = 'locked'",
   #                                "Ensure the users table has 10 locked rows")
-  # 
+  #
+  # It is possible to pass an array for the where clause, where the first
+  # element is the where string with bind placeholders, and the remaining
+  # elements are the bind variables:
+  #
+  # @example Assert the users table has a single row for user foouser
+  #     assert_table_has_many_rows('users',
+  #                              ["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
+    where = where_clause
+    binds = Array.new
+    if where_clause and where_clause.is_a? Array
+      where = where_clause.shift
+      binds = where_clause
+    end
+    results = @@db_interface.execute_sql("select count(*) from #{table} #{where}", *binds).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)
     assert_block(message) do
       row_count == results[0][0].to_i
@@ -68,4 +101,4 @@ class Test::Unit::TestCase
     "to_date('#{time.strftime('%Y%m%d')}', 'YYYYMMDD')"
   end
 
-end
+end

data/lib/plsql_unit_test/test_unit_patch.rb~

@@ -0,0 +1,71 @@
+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)
+    assert_block(message) do
+      row_count == results[0][0].to_i
+    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
+
+end

metadata

@@ -1,86 +1,94 @@
 --- !ruby/object:Gem::Specification
 name: plsql_unit_test
 version: !ruby/object:Gem::Version
-  version: 0.1.1
-  prerelease: 
+  version: 0.2.0
+  prerelease:
 platform: ruby
 authors:
 - Stephen O'Donnell
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-03-17 00:00:00.000000000 Z
+date: 2013-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: data_factory
-  requirement: !ruby/object:Gem::Requirement
-    none: false
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 0.1.2
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
     none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 0.1.2
+    none: false
+  prerelease: false
+  type: :runtime
 - !ruby/object:Gem::Dependency
   name: simpleOracleJDBC
-  requirement: !ruby/object:Gem::Requirement
-    none: false
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.1.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+        version: 0.3.0
     none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.1.1
-description: Monkey patches Test::Unit::TestCase to add some additional assert methods,
-  a global database_interface object (via a class variable) and a few helper functions
-  designed to enable plsql unit testing
+        version: 0.3.0
+    none: false
+  prerelease: false
+  type: :runtime
+description: Monkey patches Test::Unit::TestCase to add some additional assert methods, a global database_interface object (via a class variable) and a few helper functions designed to enable plsql unit testing
 email: stephen@betteratoracle.com
 executables: []
 extensions: []
 extra_rdoc_files:
 - README.md
 files:
-- lib/plsql_unit_test/setup.rb
-- lib/plsql_unit_test/test_unit_patch.rb
-- lib/plsql_unit_test.rb
-- Rakefile.rb
-- README.md
+- !binary |-
+  bGliL3Bsc3FsX3VuaXRfdGVzdC5yYg==
+- !binary |-
+  bGliL3Bsc3FsX3VuaXRfdGVzdC9zZXR1cC5yYg==
+- !binary |-
+  bGliL3Bsc3FsX3VuaXRfdGVzdC90ZXN0X3VuaXRfcGF0Y2gucmI=
+- !binary |-
+  bGliL3Bsc3FsX3VuaXRfdGVzdC90ZXN0X3VuaXRfcGF0Y2gucmJ+
+- !binary |-
+  UmFrZWZpbGUucmI=
+- !binary |-
+  UkVBRE1FLm1k
+- !binary |-
+  UkVBRE1FLm1kfg==
 homepage: http://betteratoracle.com
 licenses: []
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+      version: !binary |-
+        MA==
   none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
-      version: '0'
+      version: !binary |-
+        MA==
+  none: false
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.24
-signing_key: 
+rubyforge_project:
+rubygems_version: 1.8.25
+signing_key:
 specification_version: 3
-summary: A gem that monkey patches Test::Unit::TestCase to add some features to allow
-  unit testing of PLSQL code
+summary: A gem that monkey patches Test::Unit::TestCase to add some features to allow unit testing of PLSQL code
 test_files: []
 has_rdoc: true