rdx 0.9.0.pre

data/lib/rdx/options.rb

@@ -0,0 +1,359 @@
+
+require 'optparse'
+require 'pathname'
+
+module RDX
+	
+	#
+	# Handles running options for RDX.
+	#
+	class Options
+		
+		# Current Options instance active.
+		def self.current
+			RDX.runner && RDX.runner.options
+		end
+		
+	# :stopdoc:
+	
+		DirArray = Object.new
+		
+		attr_reader :parser
+		
+		@contents = []
+		
+		class << self
+		
+		private
+
+			def define_option name=nil, &definition
+				attr_reader name if name
+				@contents << [name, definition]
+			end
+			alias define_options define_option
+
+			def section name
+				@contents << name.to_str
+			end
+
+		public
+			
+			def apply_defaults_to options
+				@contents.each do |name,definition|
+					if definition
+						options.instance_eval(&definition)
+					else
+						options.parser.separator nil
+						options.parser.separator name
+					end
+				end
+			end
+			
+		end
+		
+		def initialize argv=[]
+			@parser = OptionParser.new
+			@parser.banner = "Usage: rdx [options] [--] [files...] "
+			setup_parser
+			@files = []
+			parse(argv)
+			@parser = nil
+		end
+		
+		def setup_parser
+			@parser.accept DirArray do |names|
+				names.split(File::PATH_SEPARATOR).map do |name|
+					dir = File.expand_path(name)
+					raise OptionParser::InvalidArgument unless File.directory? dir
+					dir
+				end
+			end
+			Options.apply_defaults_to self
+		end
+		
+	# :startdoc:
+		
+		# The list of files to be processed.
+		attr_reader :files
+		
+	section "Running modes:"
+		
+		##
+		# :method:
+		# 
+		# Verbose running mode. When active locations of tests are showed while they run.
+		# In this way you can know where the problem is if the application blocks in the testing.
+		# 
+		# Default to +false+.
+		#
+		define_option :verbose do
+			@verbose = false
+			@parser.on '-v', '--verbose', "Run in verbose mode" do
+				@verbose = true
+			end
+		end
+		
+		##
+		# :method:
+		# 
+		# Debug running mode. When active the backtrace of raised exceptions is not filtered:
+		# they include also the frames generated in the RDX::ROOT.
+		# 
+		# Default to +false+.
+		#
+		define_option :debug do
+			@debug = false
+			@parser.on '-d', '--debug', "Run in debug mode" do
+				@debug = true
+			end
+		end
+		
+		##
+		# :method:
+		# 
+		# Dry run mode. When active conventions are detected, but nothing actually runs.
+		# Use this when you don't want to scan the whole sources to find the examples:
+		# RDX will recognize them for you.
+		# 
+		# Default to +false+.
+		#
+		define_option :dry_run do
+			@dry_run = false
+			@parser.on '-y', '--dry-run', "Run in dry run mode" do
+				@dry_run = true
+			end
+		end
+		
+		##
+		# :method:
+		# 
+		# Fast run mode. When active the documentation output is not produced, increasing
+		# the testing speed.
+		# 
+		# Default to +false+.
+		#
+		define_option :fast do
+			@fast = false
+			@parser.on '-f', '--fast', '--no-doc-output',
+				"Run in fast mode (don't produce documentation output)" do
+				@fast = true
+			end
+		end
+		
+		# Will the documentation output be produced?
+		def doc_output
+			not fast
+		end
+		
+	section "Running options:"
+		
+		##
+		# :method:
+		# 
+		# Directories to search in for libraries, that will be prepended to <tt>$LOAD_PATH</tt>.
+		# 
+		# If this option is not given nothing will be required.
+		#
+		define_option :lib_dirs do
+			@lib_dirs = nil
+			@parser.on '-I', '--libdir DIRECTORIES', DirArray,
+				"Prepend DIRECTORIES to $LOAD_PATH" do |dirs|
+				@lib_dirs ||= []
+				@lib_dirs.concat dirs
+			end
+		end
+		
+		##
+		# :method:
+		# 
+		# The list of libraries that will be required for the tests.
+		# 
+		# If this option is not given but #lib_dirs was all their content will be loaded.
+		#
+		define_option :libs do
+			@libs = nil
+			@parser.on '-r', '--require FILE', String,
+				"Require FILE as a scipt during the testing phase" do |file|
+				@libs ||= []
+				@libs << file
+			end
+		end
+		
+		##
+		# :method:
+		# 
+		# The random seed, that determines the test order.
+		#
+		define_option :seed do
+			@seed = nil
+			@parser.on '-s', '--seed SEED', Integer,
+				"Sets random seed to SEED. Also via env. Eg: SEED=n rake" do |seed|
+        @seed = seed
+      end
+		end
+		
+		##
+		# :method:
+		# 
+		# The documentation generator tool on which RDX relies.
+		# 
+		# Currently only RDoc is supported, so there isn't such option.
+		#
+		define_option :generator do
+			@generator = 'rdoc'
+		#	@parser.on '-g', '--generator GENERATOR', String,
+		#		"Use GENERATOR as the documentation generator" do |generator|
+		#		@generator = generator
+		#	end
+		end
+		
+		##
+		# :method:
+		# 
+		# The list of options that will be sent to the #generator.
+		#
+		define_option :generator_options do
+			@generator_options = []
+			@parser.on '-G', '--generator-option OPTION',
+				"Pass OPTION to the documentation generator" do |option|
+				@generator_options << option
+			end
+		end
+		
+		define_option do
+			@parser.on '--bash BASH', String,
+				"Sets the BASH system command to use in bash examples" do |bash|
+        Example::Bash.bash = bash
+      end
+		end
+		
+	section "Reporting options:"
+	
+		##
+		# :method:
+		# 
+		# The kind of reporter to use. +REPORTER+ may be one of the following:
+		# * +common+: no output redirection: the generator and RDX use the same streams;
+		# * +docquiet+: nothing is produced by the documentation generator;
+		# * +rdxfocused+ (default): writes to <tt>$stderr</tt> the output of the generator tool;
+		# * +essential+: writes to <tt>$stderr</tt> even the RDX messages: only the report will be sent to <tt>$stdout</tt>;
+		# * +summary+: <tt>$stdout</tt> contains only the headers of the report without messages, one per line.
+		#
+		define_option :reporter do
+			@reporter = 'rdxfocused'
+			@parser.on '-R', '--reporter REPORTER', String,
+			"Use REPORTER as the reporter" do |reporter|
+				@reporter = reporter
+			end
+		end
+		
+		attr_reader :report_filter # :nodoc:
+		
+		define_options do
+			@report_filter = { :show=>[], :hide=>[:Success, :Skip] }
+			@parser.on '--hide TYPE', String,
+				"Hide TYPE reportables in the report" do |name|
+				hide_reportable name
+			end
+			@parser.on '--show TYPE', String,
+				"Show only TYPE reportables in the report" do |name|
+				show_reportable name
+			end
+			@parser.on '-t', '--full-trace',
+				"Trace all the reportables (including Success)" do
+				@report_filter[:hide].clear
+				@report_filter[:show].clear
+			end
+			@parser.on '--no-warnings',
+				"Hide all warings in the report" do
+				hide_reportable :Warning
+			end
+		end
+		
+		define_options do
+			Assertions.use_default_diff
+			@parser.on '--diff DIFF', String,
+				"Sets the DIFF system command to use in assert_equal" do |diff|
+        Assertions.diff = diff
+      end
+			@parser.on '--no-diff',
+				"Doesn't use the DIFF system command in assert_equal" do
+        Assertions.diff = nil
+      end
+		end
+		
+	section "Other options:"
+	
+		define_option do
+			@parser.on '--version', "Show version header and exit" do
+				puts RDX::VERSION_HEADER
+				exit
+			end
+		end
+		
+		define_option do
+			@parser.on '-h', '--help', "Show this help message" do
+				puts @parser
+				exit
+			end
+		end
+		
+	private
+	
+	# :stopdoc:
+		
+		def show_reportable name
+			name = name.capitalize.to_sym
+			@report_filter[:hide].delete(name) or
+				@report_filter[:show] << name
+		end
+		
+		def hide_reportable name
+			name = name.capitalize.to_sym
+			@report_filter[:show].delete(name) or
+				@report_filter[:hide] << name
+		end
+		
+		def parse(argv)
+			@parser.parse!(argv)
+			adjust_report_filter
+			adjust_require_list
+			adjust_seed
+			finalize_argv argv
+		end
+		
+		def adjust_report_filter
+			@report_filter[:hide].uniq!
+			@report_filter[:show].uniq!
+		end
+		
+		def adjust_require_list
+			if @libs
+				@lib_dirs ||= []
+			elsif @lib_dirs
+				@libs = []
+				@lib_dirs.each do |lib_dir|
+					Dir.glob "#{lib_dir}/*.rb" do |file|
+						@libs << File.basename(file,'.rb')
+					end
+				end
+			else
+				@lib_dirs = []
+				@libs = []
+			end
+		end
+		
+		def adjust_seed
+			return if @seed
+			srand
+			@seed = (ENV["SEED"] || srand).to_i % 0xFFFF
+		end
+		
+		def finalize_argv argv
+			@files.concat argv
+			argv.clear
+		end
+		
+	end
+	
+end

data/lib/rdx/plain_text.rb

@@ -0,0 +1,65 @@
+
+module RDX
+	
+	#
+	# Represents a text section (like this one) in a comment.
+	# :rdx: off
+	#   Whereas this section is an example
+	# Its content is not intended to be executed.
+	#
+	class PlainText < CodeObject
+		
+		# The SourceFile this text section belongs to.
+		def source_file
+			comment.source_file
+		end
+		
+		# The Comment this text section belongs to.
+		attr_reader :comment
+		alias parent comment
+		
+		def initialize(comment,text,relative_line_no=1) # :nodoc:
+			@comment = comment
+			super(text,relative_line_no)
+		end
+		
+	#
+	# :section: API
+	#
+		
+		# Returns +true+. This method should be used instead of _section_<tt>.is_a?(PlainText)</tt>.
+		def text?
+			true
+		end
+		
+		# Returns +false+. This method should be used instead of _section_<tt>.is_a?(Example)</tt>.
+		def example?
+			false
+		end
+		
+	#
+	# :section: Internal
+	#
+		
+		#
+		# Generates a warning if a convention is detected in the text,
+		# because we probably forget to turn this plain text into an example
+		# (with +RDoc+ this happens if we don't add indentation).
+		# 
+		# If it's not the case - you intentionally want to include a convention pattern
+		# in a text section - use Directive.disable_warnings with +conventions+ as parameter.
+		#
+		def check_missing_conventions
+			RubyLex.extract_potential_comments(text) do |comment,l_no|
+				comment = Text.normalize_comment comment
+				store.find_convention_in comment do |conv|
+					warn "Found pattern for convention `#{conv.name}' in plain text section",
+						:conventions, location(l_no)
+				end
+			end
+			return self
+		end
+		
+	end
+	
+end

data/lib/rdx/reporter.rb

@@ -0,0 +1,421 @@
+
+module RDX
+	
+# :stopdoc:
+	
+	class Reportable
+		attr_accessor :in_building
+		attr_accessor :before_require
+		attr_accessor :rdx_caller
+		attr_reader :file_name
+		attr_reader :line_no
+		attr_reader :type
+		def initialize location, type=nil
+			@file_name,@line_no = split_location(location)
+			@type = type && type.to_sym
+		end
+		def split_location location
+			m = location.to_str.match /:(\d++)(?!\w)/
+			return ['',0] unless m
+			return [m.pre_match, m[1].to_i]
+		end
+		private :split_location
+		def content
+		end
+		def location_ary
+			[file_name,line_no]
+		end
+		def location
+			location_ary.join ':'
+		end
+		def <=> other
+			return nil unless other.is_a?(:location_ary)
+			return self.location_ary <=> other.location_ary
+		end
+		def label
+		end
+		def result_code
+			label.to_str[0,1]
+		end
+		def code_priority
+			0
+		end
+		def when
+			return "[in building]" if in_building
+			"[before require]" if before_require
+		end
+		def report_header
+			whr = location.to_str
+			whn = self.when && ' '+self.when
+			lbl = label.to_str
+			result = "#{whr}#{whn}: #{lbl}\n"
+			result << "\tCalled by: #{rdx_caller}\n" if rdx_caller
+			return result
+		end
+		def report_body
+			result = ''
+			if content && !content.empty?
+				result << content.gsub(/^/,"\t")
+			end
+			return result
+		end
+		def report
+			report_header.to_str + report_body.to_str
+		end
+		def failure?
+			false
+		end
+	end
+	
+	class Success < Reportable
+		def label
+			"Success [#{type}]"
+		end
+		def result_code
+			'.'
+		end
+		def self.result_code
+			'.'
+		end
+		def code_priority
+			1
+		end
+		def initialize type, location
+			super(location,type)
+		end
+		def type_of? arg
+			arg == :Success
+		end
+	end
+	
+	class Detection < Success
+		def label
+			"Detected #{type}"
+		end
+		def result_code
+			''
+		end
+	end
+	
+	class Warning < Reportable
+		def label
+			"Warning [#{type}]"
+		end
+		def code_priority
+			2
+		end
+		attr_reader :content
+		def initialize content, type, location
+			@content = content
+			super(location,type)
+		end
+		def type_of? arg
+			arg == :Warning
+		end
+	end
+	
+	class Skip < Reportable
+		def label
+			"Skip [#{type}]"
+		end
+		def code_priority
+			2
+		end
+		attr_reader :content
+		def initialize content, type, location
+			@content = content
+			super(location,type)
+		end
+		def type_of? arg
+			arg == :Skip
+		end
+	end
+	
+	class Failure < Reportable
+		def label
+			"Failure [#{type}]"
+		end
+		def code_priority
+			3
+		end
+		attr_reader :content
+		def initialize fail, type, location
+			@content = fail.message
+			unless location
+				location = fail.backtrace.find{ |line| !line.start_with?(RDX::ROOT) }
+				# TODO: search for first in the target folder
+				location ||= fail.backtrace.first
+			end
+			super(location,type)
+		end
+		def failure?
+			true
+		end
+		def type_of? arg
+			arg == :Failure
+		end
+	end
+
+	class UnexpectedError < Reportable
+		def label
+			'Error'
+		end
+		def code_priority
+			4
+		end
+		attr_reader :content
+		def initialize raised_exception
+			@content = [
+				"Class: #{raised_exception.class.name}",
+				"Message: #{raised_exception.message}",
+				"---Backtrace---",
+				*RDX.filter_backtrace(raised_exception.backtrace),
+				"---------------",
+				""
+			].join "\n"
+			idx = raised_exception.backtrace.find_index{ |line| line.start_with?(RDX::ROOT) }
+			idx -= 1 if idx > 0
+			super(raised_exception.backtrace[idx])
+		end
+		def failure?
+			true
+		end
+		def type_of? arg
+			arg == :Error
+		end
+	end
+	
+# :startdoc:
+	
+	#
+	# Shows the report of the tests.
+	#
+	class Reporter
+		
+	# :stopdoc:
+		
+		@reporters = {}
+		class << self
+			attr_reader :reporters
+		end
+		def self.reporter_name
+			name.split('::').last.downcase
+		end
+		def self.inherited child_class
+			Reporter.reporters[child_class.reporter_name] = child_class
+		end
+		def self.[] name
+			Reporter.reporters[name.downcase] or
+				raise "Undefined reporter: #{name}"
+		end
+		
+		attr_reader :runner
+		def options
+			runner.options
+		end
+		def verbose
+			options.verbose
+		end
+		def store
+			runner.store
+		end
+		
+		attr_reader :stdout
+		
+		attr_reader :stderr
+		
+		def initialize runner, stdout=$stdout, stderr=$stderr
+			@runner = runner
+			@stdout = stdout || StringIO.new
+			@stderr = stderr || StringIO.new
+		end
+		
+		def print *args
+			stdout.print *args
+		end
+		def puts *args
+			stdout.puts *args
+		end
+		alias report puts
+		
+		def on_documenting &blk
+			RDX::Util.change_ostreams stdout, stderr, &blk
+		end
+		
+		def on_testing &blk
+			RDX::Util.change_ostreams nil, nil, &blk
+		end
+		
+		def start_run_test test
+			print "\n\tRunning #{test.location} : " if verbose
+		end
+		def finish_run_test test
+			print test.result_code
+		end
+		
+		def run_tests tests
+			puts unless verbose # newline for dots
+			count = 0
+			total_time = RDX::Util.measure_time do
+				tests.each do |test|
+					start_run_test test
+					test.full_run
+					finish_run_test test
+					count += 1
+					if count == 40
+						count = 0
+						puts
+					end
+				end
+			end
+			if tests.empty?
+				puts 'No tests!'
+			else
+				puts # finishes the dots
+				tests_count = tests.size
+				# For statistics is fine to assume skip and warnings negligible...
+				assertions_count = tests.reduce(0){ |sum,test| sum+test.reportables.size }
+				show_statistics(total_time,tests_count,assertions_count)
+			end
+			puts
+		end
+		
+		def run_pre_tests tests
+			print '# Running pre-require tests:'
+			run_tests tests
+		end
+		
+		def require_libs
+			puts '# Requiring libs:'
+			before_req_size = $LOADED_FEATURES.size
+			result = yield
+			no_libs = before_req_size == $LOADED_FEATURES.size
+			puts 'No libraries to require!' if no_libs
+			puts
+			result
+		end
+		
+		def require_lib lib
+			print lib, '... '
+			before_req_size = $LOADED_FEATURES.size
+			result = yield
+			required_now = $LOADED_FEATURES.drop(before_req_size)
+			if required_now.empty?
+				puts 'ALREDY LOADED'
+			else
+				unless verbose
+					puts 'OK!'
+				else
+					puts 'OK:'
+					required_now.each do |new_req|
+						puts "\t#{new_req} required"
+					end
+				end
+			end
+			result
+		end
+		
+		def run_post_tests tests
+			print '# Running post-require tests:'
+			run_tests tests
+		end
+		
+		def show_report
+			show_report_header
+			show_aggregated_results
+			show_summary
+		end
+		
+	private
+		
+		def show_report_header
+			puts
+			puts "========== Test report =========="
+			puts
+		end
+		
+		def show_statistics total_time, tests_count, assertions_count
+      puts "Finished in %.6fs, %.4f runs/s, %.4f assertions/s." %
+        [total_time, tests_count/total_time, assertions_count/total_time]
+    end
+		
+		def show_aggregated_results
+			result = ''
+			digits = reportables.size.to_s.size
+			format = "%#{digits}d) %s\n"
+			reportables.each_with_index do |reportable,i|
+				result << format % [i+1, reportable_content(reportable)]
+			end
+			report result
+		end
+		
+    def show_summary
+			tests_no      = store.tests_no
+			counts = Hash.new(0)
+			all_reportables.each{ |r| counts[r.class] += 1 }
+			result = "Total: %d runs, %d successes, %d failures, %d errors, %d skips, %d warnings" %
+        [tests_no, counts[Success], counts[Failure], counts[UnexpectedError], counts[Skip], counts[Warning]]
+			puts result
+    end
+		
+		def all_reportables
+			store.collect_reportables
+		end
+		
+		def reportables
+			return @reportables if @reportables
+			@reportables = all_reportables.dup
+			options.report_filter[:hide].each do |type|
+				@reportables.delete_if{ |r| r.type_of?(type) }
+			end
+			show = options.report_filter[:show]
+			unless show.empty?
+				@reportables.keep_if do |reportable|
+					show.any?{ |type| reportable.type_of? type }
+				end
+			end
+			@reportables
+		end
+		
+		def reportable_content reportable
+			reportable.report
+		end
+		
+		class Common < self
+		end
+		
+		class DocQuiet < self
+			def on_documenting &blk
+				RDX::Util.change_ostreams(nil,nil,&blk)
+			end
+		end
+		
+		class RDXFocused < self
+			def on_documenting &blk
+				RDX::Util.change_ostreams(stderr,stderr,&blk)
+			end
+		end
+		
+		class Essential < RDXFocused
+			def print *args
+				stderr.print *args
+			end
+			def puts *args
+				stderr.puts *args
+			end
+			def show_report_header
+			end
+			def reportable_content reportable
+				super.chomp("\n")
+			end
+		end
+		
+		class Summary < Essential
+			def reportable_content reportable
+				reportable.report_header[/.+/]
+			end
+		end
+		
+	end
+	
+end