rdx 0.9.0.pre

data/lib/rdx.rb

@@ -0,0 +1,331 @@
+#
+# = RDX: Ruby Documentation example eXecutor
+# 
+# The aim of RDX is to join the worlds of documentation and testing, whose overlap in examples.
+# Relying on the RDoc documentation generator tool and Minitest RDX parses source files,
+# generates documentation, extracts examples from comments and executes them as tests.
+# 
+# == Why RDX?
+# 
+# The whole application is built on these four cornerstones:
+# * Document Well and Right!
+# 
+#   The library should be well documented. The examples can be the most direct way
+#   to explain and show the use of the library - if these have been unit tested and work fine.
+# * DRY (Don't Repeat Yourself)!
+# 
+#   We want to avoid - honestly, we should hate - writing the same things more than once.
+#   It's too tedious to translate back and forth all the examples between documentation and testing.
+# * Join coupled parts!
+# 
+#   Source, documentation and tests are different sides of the same thing - the programmer's idea -.
+#   When some parts are tightly coupled, the more these are close the more straightforward the eventual
+#   fix is. Documentation tools unify documentation with the source, RDX tries to take the next step.
+# * Be Consistent!
+# 
+#   Most scripts of the Ruby Core and many of the Standard Library already have the examples
+#   written in a conformed and accepted way. It was this coherency that allowed (and induced)
+#   me to write RDX: a tool can easily automate tasks if they fit well into a general scheme.
+#   
+# == How RDX works
+# 
+# In order to achieve its goal it first deals with the documentation tool
+# (RDoc is the most commonly used, so currently only its support is built-in) asking to keep
+# track of examples. These are parsed and subdivided into statements: the comment at
+# their end can eventually become an expectation. The tests are build according to
+# conventions and directives.
+# 
+# The *conventions*, heart of RDX, define the rules to accept the ending comments and process the code
+# (for example the historical hash-rocket notation, <tt>#=></tt>, is implemented in Convention::result_eval:
+# it evaluates both the statement and the expectation, then compares those results through +assert_equal+).
+# See more details in the RDX::Convention class.
+# 
+# While conventions affect single statements, the *directives* operate on a larger scale.
+# Perhaps we may want to not execute an example, to interpret one as the output of the
+# previous, to locally change some of the assertions methods, to run it in a temporary directory,
+# to simulate a bash environment, and so on...
+# See the RDX::Directive class for more information about them.
+# 
+# Both the conventions and directives can be either built-in because of their popularity in the
+# Ruby Community or defined for convenience by the user.
+# 
+# Once these tests are built, the only thing left to do is to simply run them.
+# As a bonus, if everything is correct, RDX's signature is added to those made by the generator
+# tool: the user of our library now can know that the examples showed enjoy a high level of trust.
+# All this with a single run, either from the command line or through rake.
+# 
+# == Conclusions
+# 
+# When RDX has finished we can see the report of our tests, as if we had manually written all of
+# them refactoring the comments. In fact, it's even better: if an example has something wrong - if it
+# doesn't work as declared - the error points us to its location in the comment, which is just above
+# the source code. This makes the tracking and fixing steps inceadibly easy.
+# 
+# Through execution, <b>RDX gives formalism to the documentation examples</b>,
+# greatly increasing their strength. It gives all the section of a source file the deserved emphasis,
+# transforming fictitious examples into living ones!
+# 
+# A great point in its favour is that a developer familiar with the Ruby documentation
+# (of course most of them) doesn't have to learn a new DSL or syntax, but just
+# to code and document in the "standard" way, with very few alteration.
+#
+# == Security
+# 
+# The point that +RDX+ evaluates the comments leads to the topic of security.
+# Never run blindly RDX on libraries that haven't been written for that, since it's never
+# a good idea to evaluate unknown code.
+# If you want, fisrt you have to scan the files and find the examples
+# (the <tt>--dry-run</tt> option may help you, though it isn't fully secure).
+# Once you have found that the code is safe you can give RDX a try.
+# 
+# However, if a library has been built RDX-compatible, you can run it
+# from your machine - if you _trust_ the producer. If you don't
+# you must be very careful: even a plain +require+ can be dangerous,
+# with RDX you have to pay an extra attention to the comments.
+#
+# == Roadmap
+#
+# We have already talked about conventions, directives and their relative classes.
+# These are probably the most intresting topics.
+# 
+# If you want to define your own conventions and directives, see the Specification.
+# 
+# If you want to know the available command line options, see Options.
+# 
+# If you want to run RDX through +rake+, see Task.
+# 
+# The role of other classes is explained in these sections.
+#
+# == Credits
+#
+# I have ideated RDX and I am developing it. <br>
+# I think this is the best way I have to thank Yukihiro "Matz" Matsumoto
+# for the beatiful language he has designed.
+# 
+# Maurizio Destefanis
+#
+module RDX
+	
+# :stopdoc:
+	
+	require 'stringio'
+	require 'tempfile'
+	require 'pathname'
+	
+	ROOT = File.dirname(__FILE__).freeze
+	
+	require 'rdx/version'
+	
+	VERSION_HEADER = "RDX version: #{VERSION}".freeze
+	
+	HOMEPAGE = 'https://rubygems.org/gems/rdx'.freeze
+	
+	SIGNATURE = "Examples tested with <a href='#{HOMEPAGE}'>RDX</a> #{VERSION}".freeze
+	
+	
+	Error = Class.new RuntimeError
+	
+	# Raised when invalid code is processed.
+	class ParseError < RuntimeError
+		attr_accessor :line_no
+		def initialize msg=nil, line_no=nil
+			super msg
+			@line_no = line_no
+		end
+	end
+	
+	class Assertion < Exception
+	end
+	
+	class << self
+		attr_accessor :backtrace_filter
+	end
+	class BacktraceFilter # :nodoc:
+		def filter bt
+			return ['No backtrace'] if bt.empty?
+			return bt.take_while{ |line| !line.start_with?(RDX::ROOT) } unless RDX.options.debug
+			# We are not debugging launching tools (eg: rake)
+			last_index = bt.rindex{ |line| line.start_with?(RDX::ROOT) } || bt.size-1
+			bt.take last_index+1
+		end
+	end
+	self.backtrace_filter = BacktraceFilter.new
+	def self.filter_backtrace bt
+		backtrace_filter.filter bt
+	end
+	
+	def self.runner
+		Runner.current
+	end
+	
+	def self.options
+		Options.current
+	end
+	
+	def self.generator
+		Generator.current
+	end
+	
+	def self.active?
+		Runner.active?
+	end
+	
+	def self.passed?
+		Runner.passed?
+	end
+	
+	def self.run(argv)
+		Runner.run(argv)
+	end
+	
+# :startdoc:
+	
+	#
+	# Contains various useful stuff.
+	#
+	module Util
+		
+	module_function
+	
+	# :stopdoc:
+		
+		def runner
+			RDX.runner
+		end
+		
+		def options
+			RDX.options
+		end
+		
+		def generator
+			RDX.generator
+		end
+		
+	# :startdoc:
+		
+		#
+		# Returns the number of seconds elapsed during the execution of the given block.
+		#
+		def measure_time
+			t0 = Time.now
+			yield
+			return Time.now - t0
+		end
+		
+		#
+		# Run the given block with the current directory set to a temporary one.
+		#
+		def in_tmpdir *args
+			tmpdir = Dir.mktmpdir *args
+			begin
+				result = nil
+				Dir.chdir tmpdir do
+					result = yield(tmpdir)
+				end
+				result
+			ensure
+				FileUtils.remove_entry tmpdir, true
+			end
+		end
+		
+		#
+		# Changes <tt>$stdout</tt> and <tt>$stderr</tt> to the given +IO+ streams _new_out_ and _new_err_
+		# during the execution of the block.
+		# If +nil+ is provided that stream will be discarded;
+		# if +false+ is given that stream will not be changed.
+		#
+		def change_ostreams new_out, new_err
+			new_out = StringIO.new if new_out.nil?
+			new_err = StringIO.new if new_err.nil?
+			begin
+				orig_stdout,$stdout = $stdout,new_out if new_out
+				orig_stderr,$stderr = $stderr,new_err if new_err
+				yield
+			ensure
+				$stdout = orig_stdout if new_out
+				$stderr = orig_stderr if new_err
+			end
+		end
+		
+		#
+		# Captures <tt>$stdout</tt> and <tt>$stderr</tt> produced by the block into strings and returns them.
+		# If _stdout_ or _stderr_ is +nil+ or +false+ that stream will not be captured.
+		#
+		def capture_ostreams stdout=true, stderr=true, &blk
+			stdout = stdout ? StringIO.new : false
+			stderr = stderr ? StringIO.new : false
+			change_ostreams(stdout,stderr,&blk)
+			return [stdout && stdout.string, stderr && stderr.string]
+		end
+		
+		#
+		# Changes <tt>$stdin</tt> to the given +String+ _in_str_
+		# during the execution of the block.
+		#
+		def change_stdin in_str
+			stdin = StringIO.new(in_str.to_str)
+			begin
+				orig_stdin,$stdin = $stdin,stdin
+				yield
+			ensure
+				$stdin = orig_stdin
+			end
+		end
+		
+		def restore_instance_method klass, meth # :nodoc:
+			name = meth.name
+			owner = meth.owner
+			unless owner == klass
+				klass.__send__ :remove_method, name
+			else
+				klass.__send__ :define_method, name, meth
+			end
+		end
+		
+		def restore_singleton_method receiver, orig_singleton_method # :nodoc:
+			receiver_singleton_class = class<<receiver; self; end
+			restore_instance_method receiver_singleton_class, orig_singleton_method.unbind
+		end
+		
+		def patch_singleton_method receiver, name, new_method # :nodoc:
+			name = name.to_sym
+			new_method = new_method.to_proc
+			orig_method = receiver.method(name)
+			receiver.define_singleton_method name do |*args,&blk|
+				new_method.call(orig_method,*args,&blk)
+			end
+			begin
+				yield
+			ensure
+				restore_singleton_method receiver, orig_method
+			end
+		end
+		
+	end
+	
+	gem 'minitest'
+	gem 'rdoc', '= 4.0.0'
+
+	require 'rdx/runner'
+	
+	autoload :Options,     'rdx/options'
+	autoload :Store,       'rdx/store'
+	autoload :Generator,   'rdx/generator'
+	autoload :Task,        'rdx/task'
+	
+	autoload :Convention,    'rdx/convention'
+	autoload :Directive,     'rdx/directive'
+	autoload :Specification, 'rdx/specification'
+	
+	autoload :Assertions,  'rdx/assertions'
+	autoload :Binding,     'rdx/binding'
+	autoload :SourceFile,  'rdx/source_file'
+	autoload :Comment,     'rdx/comment'
+	autoload :PlainText,   'rdx/plain_text'
+	autoload :Example,     'rdx/example'
+	autoload :Statement,   'rdx/statement'
+	
+	autoload :Text,        'rdx/text'
+	autoload :RubyLex,     'rdx/ruby_lex'
+	
+end

data/lib/rdx/assertions.rb

@@ -0,0 +1,484 @@
+
+module RDX
+	
+	#
+	# RDX uses the assertions of the standard testing framework of ruby, +Minitest+.
+	# This module adapt its functionality to RDX's needs.
+	# The most important new features are:
+	# * #assert_equal_numeric: more powerful than +assert_equal+ if +Numeric+ are involved;
+	# * #assert_string_match: perfect when comparing an actual +String+ with an expected +String+ or +Regexp+;
+	# * #assert_msg_raised: checks the exception message in alternative of or along to the exception class;
+	# * #assert_same_type: expected and actual should be "similar";
+	# * #assert_*_but family: it's possible to do some normalization before the assertion.
+	#   
+	#-- rdx
+	#   :rdx: setup
+	#     include RDX::Assertions
+	#
+	module Assertions
+		
+		begin
+			gem 'minitest', '>= 5.0'
+			require 'minitest/assertions'
+		rescue Gem::LoadError
+			gem 'minitest'
+			require 'minitest/unit'
+			::Minitest = ::MiniTest unless Object.const_defined?(:Minitest) # For minitest < 2.12
+		end
+		
+		include Minitest::Assertions
+		
+		extend self
+		
+		PASSTHROUGH_EXCEPTIONS = [NoMemoryError, SignalException, SystemExit] # :nodoc:
+		
+		# Doesn't count assertions (done in CodeObject::Runnable#trace_assertion).
+		def assert test, msg = nil
+			return true if test
+			msg ||= "Failed assertion, no message given."
+			msg = msg.call if Proc === msg
+			raise Assertion, msg
+		end
+		
+		#
+		# Same as +assert_equal+, but uses #normalize_values (passing _normalize_.+to_proc+) before the comparison.
+		# 
+		#   act = "a string"
+		#   exp = "A string"
+		#   assert_equal                  exp, act   # fails!
+		#   assert_equal_but :capitalize, exp, act   # passes
+		#
+		def assert_equal_but normalize, exp, act, msg=nil
+			exp,act = normalize_values(exp,act,&normalize)
+			msg = message(msg,''){ diff exp, act }
+      assert exp==act, msg
+		end
+		
+		# Overrided to implicitly call #normalize_values.
+		def assert_equal *args, &blk
+			assert_equal_but nil, *args, &blk
+		end
+		
+		# This should be used in libraries, because +assert_equal+ can get patched.
+		alias rdx_assert_equal assert_equal # :nodoc:
+		private :rdx_assert_equal
+		
+		#
+		# Fails unless _comparison_ <tt>===</tt> _target_.
+		# 
+		#   assert_relation 'a string', String   # passes
+		#   assert_relation 'a string', /str/    # passes
+		#   assert_relation 3, 1..4              # passes
+		#
+		def assert_relation target, comparison, msg=nil
+			msg = message msg do
+				"Expected #{mu_pp(comparison)} === #{mu_pp(target)} to be true"
+			end
+			assert comparison===target, msg
+		end
+		
+		#
+		# Fails unless _exp_ and _act_ aren't instances of the same class.
+		# 
+		#   assert_same_class "A string", "Another string"   # passes
+		#   assert_same_class 1, 2**64                       # fails! # Fixnum and Bignum
+		#   assert_same_class Complex(1,1), Complex(1.0,1)   # passes
+		#   assert_same_class [1], ['A']                     # passes
+		#
+		def assert_same_class exp, act, msg=nil
+			msg = message msg do
+				"Expected #{mu_pp(exp)} and #{mu_pp(act)} to be instances of the same class, not #{exp.class} and #{act.class}"
+			end
+			assert exp.class==act.class, msg
+		end
+		
+		#
+		# Resembles #assert_same_class but with a few differences:
+		# * It's more permissive with similar objects:
+		#     assert_same_type Object.new, nil       # passes # nil is the wildcard, because it's quite common
+		#     assert_same_type 1, 2**64              # passes # Fixnum and Bignum are Integer
+		#     assert_same_type true, false           # passes # both are booleans
+		# * It's more strict with +Enumerable+ objects, where +assert_same_type+
+		#   is called again with some of their elements:
+		#     assert_same_type [1], ['A']            # fails! # the first element for non-empty arrays
+		#     assert_same_type( {:a=>1}, {:b=>:c} )  # fails! # the first pair for non-empty hashes
+		#     assert_same_type 1..2, 1..2.0          # fails! # begin and end for ranges
+		#     assert_same_type [1].each, [:a].each   # fails! # the first element for other enumerables
+		#
+		def assert_same_type exp, act, msg=nil
+			return pass if nil==exp || nil==act
+			if ([true,false] & [exp,act]).size==2
+				return pass
+			end
+			exp_class = exp.class
+			act_class = act.class
+			if ([Fixnum,Bignum] & [exp_class,act_class]).size==2
+				return pass
+			end
+			assert_same_class exp, act, msg
+			return unless Enumerable > exp_class
+			if Array==exp_class && !exp.empty? && !act.empty?
+				assert_same_type exp.first, act.first, message(msg,''){ 'First element of Array' }
+			elsif Hash==exp_class && !exp.empty? && !act.empty?
+				assert_same_type exp.first[0], act.first[0], message(msg,''){ 'First key of Hash' }
+				assert_same_type exp.first[1], act.first[1], message(msg,''){ 'First value of Hash' }
+			elsif Range==exp_class
+				assert_same_type exp.begin, act.begin, message(msg,''){ 'Begin of Range' }
+				assert_same_type exp.end,   act.end,   message(msg,''){ 'End of Range' }
+			else
+				assert_same_type exp.first, act.first, message(msg,''){ 'First element of Enumerable' }
+			end
+		end
+		
+		#
+		# More suitable for +Numeric+ in contrast to +assert_equal+ because:
+		# * type checking is enforced according to #assert_same_type
+		#     assert_equal         1, 1.0                         # passes
+		#     assert_equal_numeric 1, 1.0                         # fails!
+		#     assert_equal         Complex(1,1), Complex(1,1.0)   # passes
+		#     assert_equal_numeric Complex(1,1), Complex(1,1.0)   # fails!
+		# * accuracy is reduced in float comparison: #assert_in_epsilon is used
+		#     assert_equal         1.0, 1.0+1e-10                 # fails!
+		#     assert_equal_numeric 1.0, 1.0+1e-10                 # passes
+		#     assert_equal_numeric 1.0, 1.0+1e-10, 0              # fails!
+		#
+		def assert_equal_numeric exp, act, epsilon=1e-6, msg=nil
+			assert_same_type exp, act, msg
+			case exp
+			when Float
+				assert_in_epsilon exp, act, epsilon, msg
+			when Complex
+				assert_same_type exp.real, act.real, message(msg,''){ 'Real part of Complex' }
+				assert_same_type exp.imag, act.imag, message(msg,''){ 'Imag part of Complex' }
+				assert_equal_numeric exp.real, act.real, epsilon, msg
+				assert_equal_numeric exp.imag, act.imag, epsilon, msg
+			else
+				rdx_assert_equal exp, act, msg
+			end
+		end
+		
+		#
+		# Same as +assert_match+, but uses #normalize_values (passing _normalize_.+to_proc+)
+		# before the comparison.
+		# 
+		#   normalize = lambda do |arg|
+		#     arg.respond_to?(:to_str) ? arg.to_str.strip : arg
+		#   end
+		#   re  = /\A\w+\z/
+		#   str = " a_word "
+		#   assert_match                re, str   # fails!
+		#   assert_match_but normalize, re, str   # passes
+		#
+		def assert_match_but normalize, matcher, obj, msg=nil
+			matcher,obj = normalize_values matcher, obj, &normalize
+			msg = message msg do
+				"Expected #{mu_pp matcher} to match #{mu_pp obj}"
+			end
+			assert matcher =~ obj, msg
+		end
+		
+		# Overrided to implicitly call #normalize_values.
+		def assert_match *args, &blk
+			assert_match_but nil, *args, &blk
+		end
+		
+		#
+		# Same as #assert_string_match, but uses #normalize_values (passing _normalize_.+to_proc+)
+		# before the comparison.
+		# 
+		#   act = "a string"
+		#   exp = /str$/
+		#   normalize = lambda do |arg|
+		#     arg.is_a?(String) ? arg.chomp('ing') : arg
+		#   end
+		#   assert_string_match                exp, act   # fails!
+		#   assert_string_match_but normalize, exp, act   # passes
+		#
+		def assert_string_match_but normalize, matcher, str, msg=nil
+			if matcher.respond_to?(:to_str)
+				assert_equal_but normalize, matcher.to_str, str.to_str, msg
+			else
+				assert_match_but normalize, matcher, str.to_str, msg
+			end
+		end
+		
+		#
+		# Usable when _act_ is a +String+.
+		# If _exp_ is a +Regexp+ uses #assert_match, otherwise (including a +String+) uses #assert_equal.
+		# 
+		#   assert_string_match 'string', 'string'   # passes
+		#   assert_string_match 'ing',    'string'   # fails!
+		#   assert_string_match /ing/,    'string'   # passes
+		#   assert_string_match 'string', /rgxp/     # raises!
+		#
+		def assert_string_match exp, act, msg=nil
+			assert_string_match_but nil, exp, act, msg
+		end
+		
+		#
+		# Same as +assert_output+, but uses #normalize_values (passing _normalize_.+to_proc+)
+		# before the comparison.
+		#
+		#   assert_output             'Hey!' do puts "Hey!" end   # fails! # Does the trailing newline really matter?
+		#   assert_output_but :chomp, 'Hey!' do puts "Hey!" end   # passes
+		#   strip_and_capitalize = lambda{ |str| str.strip.capitalize }
+		#   assert_output_but strip_and_capitalize, "A word" do puts " a word " end   # passes
+		#
+		def assert_output_but normalize, exp_out=nil, exp_err=nil, out_msg='In stdout', err_msg='In stderr', &blk
+			act_out,act_err = capture_io(exp_out,exp_err,&blk)
+			assert_string_match_but normalize, exp_out, act_out, out_msg if exp_out
+			assert_string_match_but normalize, exp_err, act_err, err_msg if exp_err
+		end
+		
+		# Overrided to implicitly call #normalize_values.
+		def assert_output *args, &blk
+			assert_output_but nil, *args, &blk
+		end
+		
+		#
+		# Same as +assert_silent+, but uses #normalize_values (passing _normalize_.+to_proc+)
+		# before the comparison.
+		# 
+		#   assert_silent            do print " " end   # fails!
+		#   assert_silent_but :strip do print " " end   # passes
+		#
+		def assert_silent_but normalize, out_msg=nil, err_msg=nil, &blk
+			assert_output_but normalize, '', '', out_msg, err_msg, &blk
+		end
+		
+		# Overrided to implicitly call #normalize_values.
+		def assert_silent *args, &blk
+			assert_silent_but nil, *args, &blk
+		end
+		
+		#
+		# The block should raise an exception listed in _excs_, or a generic +StandardError+ if no
+		# exceptions are given. The last argument given can be a message containing additional failure details.
+		# If the raised exception isn't expected two things may happen:
+		# * if it's a +StandardError+ a failure will be reported:
+		#     assert_raises(ArgumentError){ raise NameError }   # fails!
+		# * otherwise it's re-raised, eventually reporting an error:
+		#     assert_raises(NameError){ raise LoadError }       # raises LoadError
+		# 
+		# Returns the exception matched so you can check the message, attributes, etc..
+		#
+		def assert_raises *excs
+			msg = "#{excs.pop.to_str}.\n" if excs.last.respond_to?(:to_str)
+			excs << StandardError if excs.empty?
+			begin
+				yield
+			rescue Exception => raised
+				if excs.any?{ |ex| raised.kind_of? ex }
+					pass
+					return raised
+				elsif raised.is_a?(StandardError)
+					flunk exception_details(raised, "#{msg}#{mu_pp(excs)} exception expected, not")
+				else # Unhandled generic Exception
+					raise raised
+				end
+			else
+				flunk "#{msg}#{mu_pp(excs)} expected but nothing was raised."
+			end
+		end
+		alias assert_raise assert_raises
+		
+		#
+		# The block should not raise an exception listed in _excs_, or a generic +StandardError+ if no
+		# exceptions are given. The last argument given can be a message containing additional failure details.
+		# If the raised exception isn't expected two things may happen:
+		# * if it's a +StandardError+ a failure will be reported:
+		#     assert_nothing_raised(ArgumentError){ raise NameError }   # fails!
+		# * otherwise it's re-raised, eventually reporting an error:
+		#     assert_nothing_raised(NameError){ raise LoadError }       # raises LoadError
+		#
+		def assert_nothing_raised *excs
+			msg = "#{excs.pop.to_str}.\n" if excs.last.respond_to?(:to_str)
+			excs << StandardError if excs.empty?
+			begin
+				yield
+			rescue Exception => raised
+				specified = excs.any?{ |ex| raised.kind_of? ex }
+				if specified || raised.is_a?(StandardError)
+					msg = message msg do
+						"Unexpected exception raised:\n#{exception_details raised}"
+					end
+					flunk msg
+				else # Unhandled generic Exception
+					raise raised
+				end
+			else
+				pass
+			end
+		end
+		
+		#
+		# Same as +assert_msg_raised+, but uses #normalize_values (passing _normalize_.+to_proc+)
+		# before the comparison.
+		# 
+		#   exp_msg = "Can't modify frozen String"
+		#   assert_msg_raised(                exp_msg){ "".freeze << 'a' }   # fails!
+		#   assert_msg_raised_but(:capitalize,exp_msg){ "".freeze << 'a' }   # passes
+		#
+		def assert_msg_raised_but normalize, exp_msg, *excs, &blk
+			whole = [false,true].include?(excs.first) ? excs.shift : true
+			raised = assert_raises(*excs,&blk)
+			if exp_msg
+				act_msg = raised.message
+				if exp_msg.respond_to?(:to_str)
+					exp_msg,act_msg = normalize_values(exp_msg.to_str,act_msg,&normalize)
+					if whole
+						assert_equal exp_msg, act_msg, 'Wrong exception message'
+					else
+						# Better than the message of assert_match implicitly called
+						msg = message 'Wrong exception message (expected should be included in actual)' do
+							diff exp_msg, act_msg
+						end
+						assert act_msg=~/(?<!\w)#{Regexp.escape(exp_msg)}(?!\w)/, msg if exp_msg=~/\S/
+					end
+				else
+					assert_match_but normalize, exp_msg, act_msg, 'Wrong message for exception'
+				end
+			end
+			return raised
+		end
+		
+		#
+		# First uses #assert_raises passing the exceptions _excs_ and the given block.
+		# 
+		# If _exp_msg_ isn't +nil+ the check of the exception message is also performed:
+		# this can be a +String+ (which is interpreted literally) or a +Regexp+ (which should match).
+		# 
+		# If after the string message is sent the parameter +false+ the message given (expected)
+		# doesn't have to be exact: it can be only a part of the actual one.
+		# 
+		#   assert_raises{                     [].freeze << 1 }   # passes # but we may need more information...
+		#   assert_msg_raised("frozen Array"){ [].freeze << 1 }   # fails! # the message isn't complete
+		#   assert_msg_raised("frozen Array",false){ [].freeze << 1 }
+		#                                                         # passes # the message can be only a part
+		#   re = /number of arguments \(\d for \d\)/
+		#   assert_msg_raised(re,ArgumentError){ 12.floor(2) }    # passes
+		#
+		def assert_msg_raised exp_msg, *excs, &blk
+			assert_msg_raised_but nil, exp_msg, *excs, &blk
+		end
+		
+	#
+	# :section: Helper methods
+	#
+		
+		##
+		# :method:
+		# 
+		# Proxy to RDX::Util.capture_ostreams.
+		#
+		define_method :capture_io, RDX::Util.method(:capture_ostreams).to_proc
+		
+		#
+		# Returns _exp_ and _act_ in an +Array+ normalized through the block given.
+		# This method can be overridded to modify the normalization.
+		#
+		def normalize_values exp, act, &normalize
+			if normalize
+				exp = normalize.call(exp)
+				act = normalize.call(act)
+			end
+			[exp,act]
+		end
+		
+		#
+		# This differs from the original implementation in that hexadecimal values are not
+		# generalized in this step.
+		#--
+		# really escaped newlines are expanded (and not a simple backslash followed by an 'n')
+		#
+		def mu_pp_for_diff obj
+			mu_pp(obj).
+				gsub(/\\(?:n()|.)/){ |seq| $1 ? "\n" : seq }
+		end
+		
+		# Returns details for exception _exc_.
+		def exception_details exc, msg=nil
+			[
+				msg.to_s,
+				"Class: #{exc.class}",
+				"Message: #{exc.message}",
+				"---Backtrace---",
+				*exc.backtrace,
+				"---------------",
+				""
+			].join "\n"
+		end
+		
+		class << self
+			# The system +diff+ command used in +assert_equal+.
+			attr_accessor :diff
+		end
+		def self.use_default_diff
+			self.diff = if system("diff", __FILE__, __FILE__)
+				'diff -u'
+			elsif system("gdiff", __FILE__, __FILE__)
+				'gdiff -u'
+			else
+				nil
+			end
+		end
+		
+		# This no more relies on Minitest
+		def diff exp, act
+      expect = mu_pp_for_diff exp
+      butwas = mu_pp_for_diff act
+      result = nil
+			
+      need_to_diff =
+        Assertions.diff &&
+        (expect.include?("\n")    ||
+         butwas.include?("\n")    ||
+         expect.size > 30         ||
+         butwas.size > 30         ||
+         expect == butwas)
+
+      return "Expected: #{mu_pp exp}\n  Actual: #{mu_pp act}" unless
+        need_to_diff
+				
+			if exp.is_a?(String) && act.is_a?(String)
+				# leave the quotes on their own lines, so that diff compares the real content of the string
+				expect.insert(1,"\n").insert(-2,"\n")
+				butwas.insert(1,"\n").insert(-2,"\n")
+			end
+
+      Tempfile.open("expect") do |a|
+        a.puts expect
+        a.flush
+
+        Tempfile.open("butwas") do |b|
+          b.puts butwas
+          b.flush
+
+          result = `#{Assertions.diff} "#{a.path}" "#{b.path}"`
+          result.sub!(/^\-\-\- .+/, "--- expected")
+          result.sub!(/^\+\+\+ .+/, "+++ actual")
+
+          if result.empty? then
+            klass = exp.class
+            result = [
+                      "No visible difference in the #{klass}#inspect output.\n",
+                      "You should look at the implementation of #== on ",
+                      "#{klass} or its members.\n",
+                      expect,
+                     ].join
+          end
+        end
+      end
+
+      result
+    end
+		
+		# No need, since parallelization does not occurr...
+		def synchronize
+			yield
+		end
+		alias _synchronize synchronize
+		
+	end
+
+end