ruby-plsql-spec 0.1.0

data/.gitignore

@@ -0,0 +1,13 @@
+.bundle
+.rvmrc
+.svn
+.DS_Store
+/coverage
+/examples/coverage
+/doc
+/pkg
+/log
+/tmp
+sqlnet.log
+Gemfile.lock
+/spec/sandbox

data/Gemfile

@@ -0,0 +1,11 @@
+source 'http://rubygems.org'
+
+gem 'jeweler'
+gem 'rspec', '~> 1.3.0'
+gem 'thor', '~> 0.14.2'
+gem 'ruby-plsql', '~> 0.4.3'
+gem 'nokogiri', '>= 1.4.3'
+
+platforms :ruby do
+  gem 'ruby-oci8', '~> 2.0.4'
+end

data/History.txt

@@ -0,0 +1,5 @@
+== 0.1.0 2010-10-01
+
+* Initial release
+  * Created command line utility plsql-spec for initialization and tests run
+  * Created PL/SQL code coverage reporting

data/INSTALL-Windows.markdown

@@ -0,0 +1,55 @@
+Installing on Windows
+=====================
+
+Ruby installation on Windows is a little bit different than installation on Mac OS X or Linux therefore here is description of steps for preparing Windows computer for ruby-plsql-spec.
+
+Install Ruby
+------------
+
+Download and install Ruby 1.8.7 from [Ruby Installer for Windows](http://www.rubyinstaller.org/).
+(If you prefer you can try to install also Ruby 1.9.2 but it might be more difficult to install ruby-oci8 on this latest Ruby version on Windows).
+
+When installing then select checkbox to add Ruby to your PATH.
+
+Verify from command line that you have Ruby installed:
+
+    ruby -v
+
+Install Oracle client
+---------------------
+
+You should have Oracle client installed on your computer and its dll directory should be in PATH.
+
+If you do not have Oracle client installed then the easiest way is to install [Oracle Instant Client](http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html) - install Basic and SQL*Plus packages. After installation include Oracle Instant Client directory in PATH.
+
+If needed you can create tnsnames.ora file and enter TNS connections there so that later TNS aliases can be used for connection. Set TNS_ADMIN environment variable to point to directory where tnsnames.ora file is located.
+
+Verify installation and try to connect to database using sqlplus.
+
+Install ruby-oci8
+-----------------
+
+[ruby-oci8](http://ruby-oci8.rubyforge.org/en/) Ruby library is providing access to Oracle database from Ruby using OCI interface (provided by Oracle client). Install it with
+
+    gem install ruby-oci8
+
+If you are behind firewall with proxy server then specify proxy server use -p option, e.g.: 
+
+    gem install ruby-oci8 -p http://proxy.example.com:8080
+
+Install ruby-plsql-spec
+-----------------------
+
+Install ruby-plsql-spec with
+
+    gem install ruby-plsql-spec
+
+Validate installation
+---------------------
+
+From command line run `irb` and try to connect to some Oracle database (use appropriate username/password/database instead of "hr","hr","orcl"):
+
+    require "rubygems"
+    require "ruby-plsql"
+    plsql.connect! "hr","hr","orcl"
+    plsql.dual.all

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2009-2010 Raimonds Simanovskis
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+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.

data/README.markdown

@@ -0,0 +1,91 @@
+ruby-plsql-spec
+===============
+PL/SQL unit testing with Ruby
+-----------------------------
+
+Unit testing of PL/SQL procedures with Ruby libraries:
+
+* [ruby-plsql](http://github.com/rsim/ruby-plsql) - Ruby API for calling PL/SQL procedures
+* [RSpec](http://rspec.info) - Ruby testing (or behavior driven development) framework
+
+Examples
+--------
+
+PL/SQL procedure examples are in `examples/source` subdirectory, test examples are in `examples/spec` subdirectory.
+
+* `BETWNSTR` - example from [utPLSQL project](http://utplsql.sourceforge.net/)
+* `AWARD_BONUS` - example from [SQL Developer 2.1 tutorial](http://www.oracle.com/technology/obe/11gr2_db_prod/appdev/sqldev/sqldev_unit_test/sqldev_unit_test.htm)
+* `REMOVE_ROOMS_BY_NAME` - example from [Quest Code Tester for Oracle tutorial](http://www.quest.com/code-tester-for-oracle/product-demo/chap02.htm)
+
+Installing
+----------
+
+See [Installing on Windows](INSTALL-Windows.markdown) in separate file.
+
+* Install [Ruby 1.8.7 or Ruby 1.9.2](http://www.ruby-lang.org/en/downloads/)
+* Install Oracle client, e.g. [Oracle Instant Client](http://www.oracle.com/technology/tech/oci/instantclient/index.html)
+* Install ruby-oci8 and ruby-plsql-spec (prefix with sudo if necessary)
+
+        gem install ruby-oci8
+        gem install ruby-plsql-spec
+
+Another alternative is to use [JRuby](http://jruby.org) if for example it is necessary also to test Java classes / methods using Ruby.
+
+* Install [JRuby](http://jruby.org/download)
+* Copy Oracle JDBC driver (e.g. ojdbc14.jar) to JRUBY_HOME/lib directory
+* Install ruby-plsql-spec (prefix with sudo if necessary)
+
+        jruby -S gem install ruby-plsql-spec
+
+Initializing project directory
+------------------------------
+
+In your project directory execute
+
+        plsql-spec init
+
+which will create `spec` directory where test files will be located.
+
+Modify `spec/database.yml` file and specify database connection which should be used when running tests. In `database:` parameter specify either TNS connection name or use "servername/databasename" or "servername:port/databasename" to specify host, port and database name.
+
+Start creating tests in files with `_spec.rb` at the end of file name. If there will be not so many files then you can place them directly in `spec` directory. If there will be many tests files then create separate directories per module / functionality group and place tests files in subdirectories. You can also create `factories` and `helpers` subdirectories per each module / functionality group.
+
+Executing tests
+---------------
+
+All tests can be run from command line using
+
+        plsql-spec run
+
+or if you want to run tests just from one file then use, e.g.
+
+        plsql-spec run spec/example_spec.rb
+
+You can get additional help about `plsql-spec` command line utility with
+
+        plsql-spec help
+
+Code coverage reporting
+-----------------------
+
+If you would like to see PL/SQL code coverage report (which lines of code were executed during tests run) then run tests with --coverage option:
+
+        plsql-spec run --coverage
+
+Coverage reports will be created as HTML files in coverage/ directory. Open with your browser coverage/index.html file.
+
+Code coverage is gathered using DBMS_PROFILER package. Please take into account that only those packages will be analyzed to which current database session user has CREATE privilege.
+
+How to start?
+-------------
+
+Read blog post about [Oracle PL/SQL unit testing with Ruby](http://blog.rayapps.com/2009/11/27/oracle-plsql-unit-testing-with-ruby).
+
+If you are not familiar with Ruby I recommend to start with [Ruby in Twenty Minutes](http://www.ruby-lang.org/en/documentation/quickstart/) tutorial. Then you can take a look on some [RSpec examples](http://rspec.info/documentation/) how to write and structure tests. And then you can take a look at [ruby-plsql own tests](http://github.com/rsim/ruby-plsql/blob/master/spec/plsql/procedure_spec.rb) to see how to pass parameters and verify results for different PL/SQL data types.
+
+How to customize ruby-plsql-spec for my project?
+--------------------------------------------
+
+* Review spec/spec_helper.rb file and modify if needed directories where you will store additional required files (helper files, factory files, source files).
+* Review and or create new helper files in `spec\helpers` directory.
+* Create new factory methods for test data creation in `factories` directory (see example in `examples/spec/factories`).

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "ruby-plsql-spec"
+    gem.summary = "Oracle PL/SQL unit testing framework using Ruby and RSpec"
+    gem.description = <<-EOS
+ruby-plsql-spec is Oracle PL/SQL unit testing framework which is built using Ruby programming language, ruby-plsql library and RSpec testing framework.
+EOS
+    gem.email = "raimonds.simanovskis@gmail.com"
+    gem.homepage = "http://github.com/rsim/ruby-plsql-spec"
+    gem.authors = ["Raimonds Simanovskis"]
+    gem.add_dependency "ruby-plsql", ">= 0.4.3"
+    gem.add_dependency "thor", ">= 0.14.2"
+    gem.add_dependency "rspec", "~> 1.3.0"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/plsql/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/plsql/**/*_spec.rb'
+  spec.rcov = true
+  spec.rcov_opts = ['--exclude', '/Library,spec/']
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = "ruby-plsql-spec #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/plsql-spec

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'ruby-plsql-spec'
+
+PLSQL::Spec::CLI.start

data/examples/source/award_bonus.rb

@@ -0,0 +1,29 @@
+# example from SQL Developer 2.1 tutorial
+# http://www.oracle.com/technology/obe/11gr2_db_prod/appdev/sqldev/sqldev_unit_test/sqldev_unit_test.htm
+
+# Uncomment to create table employees2 which is used by award_bonus procedure
+# plsql.execute "DROP TABLE employees2" rescue nil
+# plsql.execute "CREATE TABLE employees2 AS SELECT * FROM employees WHERE ROWNUM < 0"
+# plsql.execute "DROP SEQUENCE employees2_seq" rescue nil
+# plsql.execute "CREATE SEQUENCE employees2_seq"
+
+plsql.execute <<-SQL
+CREATE OR REPLACE
+ PROCEDURE award_bonus (
+  emp_id NUMBER, sales_amt NUMBER) AS
+  commission    REAL;
+  comm_missing  EXCEPTION;
+BEGIN
+  SELECT commission_pct INTO commission
+    FROM employees2
+      WHERE employee_id = emp_id;
+
+  IF commission IS NULL THEN
+    RAISE comm_missing;
+  ELSE
+    UPDATE employees2
+      SET salary = NVL(salary,0) + sales_amt*commission
+        WHERE employee_id = emp_id;
+  END IF;
+END;
+SQL

data/examples/source/betwnstr.rb

@@ -0,0 +1,19 @@
+# example from utPLSQL project (http://utplsql.sourceforge.net/)
+plsql.execute <<-SQL
+CREATE OR REPLACE FUNCTION betwnstr (
+   string_in   IN   VARCHAR2,
+   start_in    IN   INTEGER,
+   end_in      IN   INTEGER
+)
+   RETURN VARCHAR2
+IS
+   l_start PLS_INTEGER := start_in;
+BEGIN
+   IF l_start = 0
+   THEN
+      l_start := 1;
+   END IF;
+
+   RETURN (SUBSTR (string_in, l_start, end_in - l_start + 1));
+END;
+SQL

data/examples/source/remove_rooms_by_name.rb

@@ -0,0 +1,45 @@
+# example from Code Tester for Oracle tutorial
+# http://www.quest.com/code-tester-for-oracle/product-demo/chap02.htm
+
+# Setup test tables
+plsql.execute "DROP TABLE room_contents" rescue nil
+plsql.execute "DROP TABLE rooms" rescue nil
+
+plsql.execute <<-SQL
+CREATE TABLE rooms (
+  room_key NUMBER PRIMARY KEY,
+  name VARCHAR2(100)
+)
+SQL
+plsql.execute <<-SQL
+CREATE TABLE room_contents (
+  contents_key NUMBER PRIMARY KEY,
+  room_key NUMBER,
+  name VARCHAR2(100)
+)
+SQL
+
+# Foreign key to rooms. Note: this is not a CASCADE DELETE
+# key. Child data is NOT removed when the parent is
+# removed.
+
+plsql.execute <<-SQL
+ALTER TABLE room_contents ADD CONSTRAINT
+  fk_rooms FOREIGN KEY (room_key)
+  REFERENCES rooms (room_key)
+SQL
+
+plsql.execute <<-SQL
+CREATE OR REPLACE PROCEDURE remove_rooms_by_name (
+  name_in IN rooms.name%TYPE)
+IS
+BEGIN
+  IF NAME_IN IS NULL
+  THEN
+    RAISE PROGRAM_ERROR;
+  END IF;
+
+  DELETE FROM rooms WHERE name LIKE name_in;
+
+END;
+SQL

data/examples/source/what_is_profiled.rb

@@ -0,0 +1,207 @@
+plsql.execute <<-SQL
+CREATE OR REPLACE PACKAGE what_is_profiled
+IS
+   TYPE aa1 IS TABLE OF VARCHAR2 (100)
+      INDEX BY PLS_INTEGER;
+   TYPE aa2 IS TABLE OF VARCHAR2 (100)
+      INDEX BY PLS_INTEGER;
+   PROCEDURE proc1 (arg IN NUMBER, arg2 OUT VARCHAR2);
+   FUNCTION func1
+      RETURN VARCHAR2;
+      
+      procedure driver ;
+END what_is_profiled;
+SQL
+
+plsql.execute <<-SQL
+CREATE OR REPLACE PACKAGE BODY what_is_profiled
+IS
+   TYPE p_aa1 IS TABLE OF VARCHAR2 (100)
+      INDEX BY PLS_INTEGER;
+
+   TYPE p_aa2 IS TABLE OF VARCHAR2 (100)
+      INDEX BY PLS_INTEGER;
+
+   PROCEDURE loops (arg IN NUMBER, arg2 OUT VARCHAR2)
+   IS
+      val
+      INTEGER;
+      condition1 boolean := true;
+      condition2 boolean 
+      := 
+      true;
+
+   BEGIN
+      FOR indx IN 1 .. 100
+      LOOP
+         NULL;
+      END LOOP;
+
+      FOR
+      indx
+      IN
+      1
+      ..
+      100
+      LOOP
+         val := 1;
+      END
+      LOOP;
+
+      FOR indx IN 1 .. 100 LOOP NULL; END LOOP;
+
+      FOR rec IN (SELECT *
+                    FROM all_source
+                   WHERE ROWNUM < 101)
+      LOOP
+         val := 1;
+      END LOOP;
+
+      FOR 
+      rec 
+      IN 
+      (
+      SELECT *
+                    FROM all_source
+                   WHERE ROWNUM < 101
+      )
+      LOOP
+         val := 1;
+      END 
+      LOOP;
+
+      WHILE (condition1 AND condition2)
+      LOOP
+         condition1 := FALSE;
+      END LOOP;
+
+      WHILE
+      (
+      condition1
+      AND
+      condition2
+      )
+      LOOP
+         condition1
+         := 
+         FALSE
+         ;
+      END LOOP;
+
+      DECLARE
+         indx   INTEGER := 1;
+      BEGIN
+         LOOP
+            EXIT WHEN indx > 100;
+            indx := indx + 1;
+         END LOOP;
+      END;
+
+      DECLARE
+         indx   INTEGER := 1;
+      BEGIN
+         LOOP
+            EXIT
+            WHEN
+            indx
+            >
+            100;
+            indx := indx +
+            1
+            ;
+         END LOOP;
+      END;
+   END;
+
+   PROCEDURE conditionals
+   IS
+   a
+   boolean;
+   b boolean;
+   c boolean
+   ;
+   BEGIN
+      IF (a AND b OR c)
+      THEN
+         NULL;
+         elsif
+         a
+         then
+         null;
+         else
+         dbms_output.put_line ('a');
+      END IF;
+
+      a := case
+      true
+      when true
+      then
+      false
+      when
+      false then
+      true
+      else
+      false
+      end
+      ;
+      a := case true
+      when true
+      then
+      false
+      when
+      false then
+      true
+      else
+      false
+      end
+      ;
+
+      case when
+      sysdate > sysdate + 1
+      then
+      a := false;
+      when 1 > 2 then
+      b := false;
+      when 1
+      > 2
+      then
+      c := false;
+      else null; end case;
+   END;
+
+   FUNCTION p_func1
+      RETURN VARCHAR2
+   IS
+   BEGIN
+      RETURN NULL;
+   END;
+
+   PROCEDURE proc1 (arg IN NUMBER, arg2 OUT VARCHAR2)
+   IS
+   BEGIN
+      NULL;
+   END;
+
+   FUNCTION func1
+      RETURN VARCHAR2
+   IS
+   BEGIN
+      RETURN p_func1;
+   END;
+   
+   procedure driver is
+   l varchar2(100);
+   begin
+   loops(1, l);
+   conditionals;
+   proc1
+   (
+   1
+   ,
+   l);
+   GOTO checkloop;
+   <<checkloop>>
+   dbms_output.put_line ('a');
+   end;
+END what_is_profiled;
+SQL