piggly 1.2.1 → 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6bc3e3b06dfb2ce02fc63e702216f7144165c2a0
+  data.tar.gz: 15a2d1da931923920ffce34f726096c3f31e8492
+SHA512:
+  metadata.gz: 8409f7c8adde74c01dfaeb3dcf0e1a6df10b5e8d7552701d38586f938d47e9727457c34a3b2a539f1ad54ceb4e5450909bddfc3f4b43485a2094fd9dc045f97c
+  data.tar.gz: b4d409e5ab4f45112f27444720fa56ce6e034e8c9244c466a2f249fcf0cb3032269287ca8eb48927c01245e7e1e62bf42a0b15a32f3df408ed3278a962eeb1dc

data/README.md

@@ -0,0 +1,163 @@
+# Piggly
+
+PostgreSQL PL/pgSQL stored procedure code coverage [![Build Status](https://secure.travis-ci.org/kputnam/piggly.png)](http://travis-ci.org/kputnam/piggly)
+
+![Screenshot](http://kputnam.github.com/piggly/images/example.png)
+
+## Purpose
+
+PL/pgSQL doesn't have much in the way of developer tools, and writing automated tests for
+stored procedures can be much easier when you know what you haven't tested. Code coverage
+allows you to see which parts of your code haven't been executed.
+
+Piggly is a tool (written in Ruby, but you can write your tests in any language) to track
+code coverage of PostgreSQL PL/pgSQL stored procedures. It reports on code coverage to help
+you identify untested parts of your code.
+
+## How Does It Work?
+
+Piggly tracks the execution of PostgreSQL's PL/pgSQL stored procedures by recompiling
+the stored procedure with instrumentation code. Basically, RAISE WARNING statements notify the
+client of an execution event (e.g., a branch condition evaluating to true or false). It records
+these events and generates prettified source code that is annotated with coverage details.
+
+## Features
+
+* Readable and easily-navigable reports (see [example] [5])
+* Language agnostic - write your tests in Ruby, Python, Java, SQL scripts etc
+* Branch, block, and loop coverage analysis
+* Instrumenting source-to-source compiler
+* Low test execution overhead
+* Reduced compilation times by use of disk caching
+* Possible to aggregate coverage across multiple runs
+
+## Limitations
+
+* Not all PL/pgSQL grammar is currently supported, but the grammar is easy to modify
+* Cannot parse nested dollar-quoted strings, eg $A$ ... $B$ ... $B$ ... $A$
+* SQL statements are not instrumented, so their branches (COALESCE, WHERE-clauses, etc) aren't tracked
+
+## Requirements
+
+* [Treetop] [2]: `gem install treetop`
+* The [ruby-pg driver] [3]: `gem install pg`
+* The examples require ActiveRecord: `gem install activerecord`
+
+## How to Install
+
+To install the latest from github:
+
+    $ git clone git://github.com/kputnam/piggly.git
+    $ cd piggly
+    $ bundle install
+    $ bundle exec rake spec
+
+    $ rake gem
+    $ gem install pkg/*.gem --no-rdoc --no-ri
+
+To install the latest release:
+
+    $ gem install piggly
+
+## Usage
+
+Your stored procedures must already be loaded in the database. Configure your database connection in
+a file named `config/database.yml` relative to where you want to run piggly. You can also specify the
+`-d PATH` to an existing configuration file. The contents of the file follow ActiveRecord conventions:
+
+    piggly:
+      adapter: postgresql
+      database: cookbook
+      username: kputnam
+      password: secret
+      host: localhost
+
+Here we'll add some stored procedures to the database we described above:
+
+    $ cat example/proc/*.sql | psql -U kputnam -h localhost cookbook
+
+Note the connection is expected to be named `piggly` but you may specify the `-k DATABASE` option to
+use a different connection name (eg `-k development` in Rails).  See also `example/config/database.yml`.
+
+Now you are ready to recompile and install your stored procedures. This reads the configuration from 
+`./config/database.yml` relative to the current working directory.
+
+    $ piggly trace
+    compiling 5 procedures
+    Compiling scramble
+    Compiling scramble
+    Compiling numberedargs
+    Compiling snippets
+    Compiling iterate
+    tracing 5 procedures
+
+This caches the original version (without instrumentation) in `piggly/cache` so you can restore them
+later. Piggly will only recompile procedures that have changed in the database since it last
+made a copy in `piggly/cache`.
+
+*WARNING*: piggly fetches your code from the database and replaces it (in the database) with the
+instrumented code. If you run `piggly trace` twice consecutively, the second time will cause an error
+because you are trying to re-instrument code that has already been instrumented. You need to run
+`piggly untrace` or restore your original stored procedures manually before you can trace them again.
+
+Now you're ready to execute your tests. Make sure your connection is configured to log `RAISE WARNING`
+messages to a file -- or you can log them to `STDERR` and redirect that to a file. For instance you
+might run:
+
+    $ ant test 2> messages.txt
+    $ make test 2> messages.txt
+    etc.
+
+To build the coverage report, have piggly read that file in by executing `piggly report < messages.txt`,
+ or `piggly report -f messages.txt`. You don't actually need the intermediate file, you can pipe your
+test suite directly in like `ant test 2>&1 | piggly report`.
+
+Once the report is built you can open it in `piggly/reports/index.html`.
+
+## Running the Examples
+
+    $ cd piggly
+    $ bundle install
+    $ cat example/README
+    ...
+
+    $ ./example/run-tests
+    compiling 5 procedures
+    Compiling scramble
+    Compiling scramble
+    Compiling numberedargs
+    Compiling snippets
+    Compiling iterate
+    tracing 5 procedures
+    Loaded suite /home/kputnam/wd/piggly/example/test/iterate_test
+    Started
+    ......
+    Finished in 0.199236 seconds.
+
+    6 tests, 6 assertions, 0 failures, 0 errors, 0 skips
+
+    Test run options: --seed 25290
+    clearing previous coverage
+    storing coverage profile
+    creating index
+    creating reports
+    reporting coverage for scramble
+    reporting coverage for scramble
+    reporting coverage for numberedargs
+    reporting coverage for snippets
+    reporting coverage for iterate: +0.0% block, +0.0% branch, +0.0% loop
+    restoring 5 procedures
+    OK, view /home/kputnam/wd/piggly/example/piggly/reports/index.html
+
+    $ ls -alh example/reports/index.html
+    -rw-r--r-- 1 kputnam kputnam 1.4K 2010-04-28 11:21 example/reports/index.html
+
+## Bugs & Issues
+
+Please report any issues or feature requests on the [github tracker] [4].
+
+  [1]: http://github.com/relevance/rcov/
+  [2]: http://github.com/nathansobo/treetop
+  [3]: http://bitbucket.org/ged/ruby-pg/
+  [4]: http://github.com/kputnam/piggly/issues
+  [5]: http://kputnam.github.com/piggly/reports/index.html

data/Rakefile

@@ -1,19 +1,33 @@
-dir = File.dirname(__FILE__)
-require 'rubygems'
-require 'rake'
-
 begin
-  require 'spec/rake/spectask'
-  Spec::Rake::SpecTask.new do |t|
-    t.pattern = 'spec/**/*_spec.rb'
-  end
-  task :default => :spec
-rescue Exception
+  require "rubygems"
+  require "bundler/setup"
+rescue LoadError
+  warn "couldn't load bundler:"
+  warn "  #{$!}"
 end
 
-require 'rake/gempackagetask'
-load './piggly.gemspec'
-Rake::GemPackageTask.new(Piggly.gemspec) do |pkg|
-  pkg.need_tar = false
-  pkg.need_zip = false
+begin # rspec-2
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new do |t|
+    t.verbose    = false
+    t.pattern    = "spec/**/*_spec.rb"
+    t.rspec_opts = "--color --format=p"
+  end
+rescue LoadError => first
+  begin # rspec-1
+    require "spec/rake/spectask"
+    Spec::Rake::SpecTask.new do |t|
+      t.pattern = "spec/**/*_spec.rb"
+      t.spec_opts << "--color"
+      t.spec_opts << "--format=p"
+    end
+  rescue LoadError => second
+    task :spec do
+      warn "couldn't load rspec version 1 or 2:"
+      warn "  #{first}"
+      warn "  #{second}"
+    end
+  end
 end
+
+task :default => :spec

data/bin/piggly

@@ -1,248 +1,8 @@
 #!/usr/bin/env ruby
-require 'optparse'
-require 'rubygems'
-$:.push File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
-require 'piggly'
+$:.unshift File.expand_path(File.join(File.dirname(__FILE__), *%w(.. lib)))
+require "piggly"
 
 # Number of children to fork for parallel tasks
-Piggly::Queue.children = 2
+Piggly::Util::ProcessQueue.concurrent = 2
 
-STDOUT.sync = true
-
-module Piggly
-  module Command
-    class << self
-
-      def main
-        benchmark do
-          sources, tests = parse_options
-          load_tests(tests)
-          connect_to_database
-          compile_procs(sources)
-          install_procs(sources)
-          clear_coverage
-          execute_tests
-          store_coverage
-          uninstall_procs(sources)
-          create_index(sources)
-          create_reports(sources)
-          exit! 0 # avoid running tests again
-        end
-      end
-
-    private
-
-      def benchmark
-        start = Time.now
-        yield
-        puts " > Completed in #{'%0.2f' % (Time.now - start)} seconds"
-      end
-
-      def parse_options
-        proc_paths = []
-
-        opts = OptionParser.new do |opts|
-          opts.on("-I", "--include PATHS", "Prepend paths to $: (colon separated list)") do |paths|
-            $:.concat paths.split(':')
-          end
-
-          opts.on("-o", "--output PATH", "Report output directory") do |dir|
-            Piggly::Config.report_root = dir
-          end
-
-          opts.on("-c", "--cache-root PATH", "Compiler cache directory") do |dir|
-            Piggly::Config.cache_root = dir
-          end
-
-          opts.on("-s", "--proc-files PATH", "Stored procedures file list (may be specified many times)") do |dir|
-            proc_paths << dir
-          end
-
-        # opts.on("-T", "--trace-prefix PATH", "Trace prefix") do |str|
-        #   Piggly::Config.trace_prefix = str
-        # end
-          
-          opts.on("-a", "--aggregate", "Aggregate data from the previous run") do
-            Piggly::Config.aggregate = true
-          end
-
-          opts.on("--version", "Show version") do
-            puts "piggly #{Piggly::VERSION::STRING} #{Piggly::VERSION::RELEASE_DATE}"
-            exit
-          end
-
-          opts.on("-h", "--help", "Show this message") do
-            puts opts
-            exit 0
-          end
-        end
-
-        if index = ARGV.index('--')
-          extra = ARGV.slice!(index..-1).slice(1..-1)
-        else
-          extra = []
-        end
-
-        begin
-          opts.parse! ARGV
-          raise OptionParser::MissingArgument, "no tests specified" if ARGV.empty?
-        rescue OptionParser::InvalidOption, OptionParser::InvalidArgument, OptionParser::MissingArgument
-          puts opts
-          puts
-          puts $!.message
-          exit -1
-        end
-
-        proc_paths = proc_paths.map{|p| Dir[p] }.flatten.sort
-        test_paths = ARGV.map{|p| Dir[p] }.flatten.sort
-
-        ARGV.clear
-
-        return proc_paths, test_paths
-      end
-
-      def load_tests(tests)
-        puts "Loading #{tests.size} test files"
-
-        benchmark { tests.each{|file| load file } }
-
-      # # TODO: this doesn't seem right, but workaround RSpec executing each spec twice
-      # if defined? Spec::Runner::ExampleGroupRunner
-      #   Spec::Runner::ExampleGroupRunner.send(:define_method, :load_files) do |*args|
-      #     # don't do anything, we already loaded the files
-      #   end
-      # end
-      end
-
-      def connect_to_database
-        ActiveRecord::Base.connection.active?
-      rescue
-        ActiveRecord::Base.establish_connection
-      end
-
-      def compile_procs(sources)
-        stale = sources.select{|f| Piggly::TraceCompiler.stale?(f) }
-
-        # build the parser if needed
-        Piggly::Parser.parser
-
-        puts "Compiling #{stale.size} files"
-        benchmark do
-          stale.each do |file|
-            Piggly::Queue.child do
-              begin
-                Piggly::TraceCompiler.cache(file)
-            # rescue Errno::ENOENT, Piggly::Parser::Failure
-            #   puts "! #{File.basename file}"
-              rescue
-                puts
-                puts "#{$!.class}: #{$!.message}"
-                puts $!.backtrace.join("\n")
-              end
-            end
-          end
-          Piggly::Queue.start
-        end
-      end
-
-      def install_procs(sources)
-        puts "Installing #{sources.size} proc files"
-
-        benchmark do
-          sources.each do |file|
-            begin
-              Piggly::Installer.trace_proc(file)
-            rescue Errno::ENOENT, Piggly::Parser::Failure
-            # puts "! #{File.basename file}"
-            rescue
-              puts
-              puts "#{$!.class}: #{$!.message}"
-              puts $!.backtrace.join("\n")
-            end
-          end
-
-          Piggly::Installer.install_trace
-        end
-      end
-
-      def clear_coverage
-        unless Piggly::Config.aggregate
-          puts "Clearing previous run's profile"
-          benchmark { Piggly::Profile.clear }
-        end
-      end
-
-      def execute_tests
-        if defined?  Test::Unit::AutoRunner
-          Test::Unit::AutoRunner.run
-        elsif defined? Spec::Runner
-          Spec::Runner.run
-        else
-          raise "Neither RSpec nor Test::Unit were detected"
-        end
-      end
-
-      def store_coverage
-        puts "Storing coverage profile"
-        benchmark { Piggly::Profile.store }
-      end
-
-      def uninstall_procs(sources)
-        puts "Removing trace code"
-        benchmark do
-          sources.each do |file|
-            begin
-              Piggly::Installer.untrace_proc(file)
-            rescue Errno::ENOENT, Piggly::Parser::Failure
-            # puts "! #{File.basename file}"
-            rescue
-              puts
-              puts "#{$!.class}: #{$!.message}"
-              puts $!.backtrace.join("\n")
-            end
-          end
-
-          Piggly::Installer.uninstall_trace
-        end
-      end
-
-      def create_index(sources)
-        puts "Creating index"
-        benchmark do
-          Piggly::Reporter.install('piggly.css', 'sortable.js')
-          Piggly::HtmlReporter::Index.output(sources)
-        end
-      end
-
-      def create_reports(sources)
-        puts "Creating reports"
-        summary = Hash.new{|h,k| h[k] = Hash.new[:count => 0, :percent => 0]}
-
-        benchmark do
-          sources.each do |file|
-            Piggly::Queue.child do
-              begin
-                summary = Piggly::Profile.summary(file)
-                pretty  = Piggly::PrettyCompiler.compile(file, Piggly::Profile)
-
-                Piggly::HtmlReporter.output(file, pretty, summary)
-              rescue Errno::ENOENT, Piggly::Parser::Failure
-              # puts "! #{File.basename file}"
-              rescue
-                puts "#{$!.class}: #{$!.message}"
-                puts $!.backtrace.join("\n")
-              end
-            end
-          end
-
-          Piggly::Queue.start
-        end
-      end
-
-    end
-  end
-end
-
-if __FILE__ == $0
-  Piggly::Command.main
-end
+Piggly::Command::Base.main(ARGV)