lib/tap/test/file_test.rb in tap-test-0.3.0 vs lib/tap/test/file_test.rb in tap-test-0.4.0
- old
+ new
@@ -3,19 +3,19 @@
module Tap
module Test
# FileTest facilitates access and utilization of test-specific files and
- # directories. FileTest provides each test method with a Tap::Root
- # (method_root) specific for the method, and defines a new assertion method
- # (assert_files) to facilitate tests which involve the production and/or
- # modification of files.
+ # directories. FileTest provides each test method with a Tap::Root
+ # (method_root) specific for the method, and defines a new assertion
+ # method (assert_files) to facilitate tests which involve the production
+ # and/or modification of files.
#
# [file_test_doc_test.rb]
# class FileTestDocTest < Test::Unit::TestCase
# acts_as_file_test
- #
+ #
# def test_something
# # each test class has a class test root (ctr)
# # and each test method has a method-specific
# # root (method_root)
#
@@ -34,33 +34,53 @@
#
# # the assert_files method compares files produced
# # by the block the expected files, ensuring they
# # are the same (see the documentation for the
# # simplest use of assert_files)
- #
+ #
# expected_file = method_root.prepare(:expected, 'output.txt') {|file| file << 'expected output' }
#
# # passes
# assert_files do
# method_root.prepare(:output, 'output.txt') {|file| file << 'expected output' }
# end
# end
# end
#
+ # ==== Cleanup
+ #
+ # By default the method_root directory is cleaned up at the end of the
+ # test, making FileTest very conveient for creating temporary test files.
+ # To prevent cleanup, either set the KEEP_OUTPUTS or KEEP_FAILURES ENV
+ # variable to 'true'. The cleanup directories can be specified manually
+ # using cleanup_dirs class variable:
+ #
+ # class LimitedCleanupTest < Test::Unit::TestCase
+ #
+ # # only cleanup the method_root[:output] directory
+ # acts_as_file_test :cleanup_dirs => [:output]
+ # end
+ #
+ # This technique is useful when you want to keep certain static files
+ # under version control, for instance.
+ #
+ # ==== Requirements
+ #
# FileTest requires that a method_name method is provided by the including
- # class, in order to properly set the directory for method_root.
+ # class, in order to properly set the directory for method_root.
+ # Test::Unit::TestCase satisfies this requirement already.
module FileTest
def self.included(base) # :nodoc:
super
base.extend FileTest::ClassMethods
- base.cleanup_dirs = [:output, :tmp]
+ base.cleanup_dirs = [:root]
end
- # The test-method-specific Tap::Root which may be used to
- # access test files. method_root is a duplicate of ctr
- # reconfigured so that method_root.root is ctr[method_name.to_sym]
+ # The test-method-specific Tap::Root which may be used to access test
+ # files. method_root is a duplicate of ctr reconfigured so that
+ # method_root.root is ctr[method_name.to_sym]
attr_reader :method_root
# Sets up method_root and calls cleanup. Be sure to call super when
# overriding this method.
def setup
@@ -68,30 +88,23 @@
@method_root = ctr.dup.reconfigure(:root => ctr[method_name.to_sym])
cleanup
end
# Cleans up the method_root.root directory by removing the class
- # cleanup_dirs (by default :tmp and :output). The root directory
- # will also be removed if it is empty.
- #
+ # cleanup_dirs (by default :root, ie the method_root directory itself).
+ # The root directory will be removed if it is empty.
+ #
# Override as necessary in subclasses.
def cleanup
self.class.cleanup_dirs.each do |dir|
clear_dir(method_root[dir])
end
try_remove_dir(method_root.root)
end
- # Calls cleanup unless flagged otherwise by an ENV variable. To prevent
- # cleanup (when debugging for example), set the 'KEEP_OUTPUTS' or
- # 'KEEP_FAILURES' ENV variables:
- #
- # % rap test KEEP_OUTPUTS=true
- # % rap test KEEP_FAILURES=true
- #
- # Cleanup is only suppressed for failing tests when KEEP_FAILURES is
- # specified. Be sure to call super when overriding this method.
+ # Calls cleanup unless flagged otherwise by an ENV variable (see above).
+ # Be sure to call super when overriding this method.
def teardown
# check that method_root still exists (nil may
# indicate setup was overridden without super)
unless method_root
raise "teardown failure: method_root is nil (does setup call super?)"
@@ -114,21 +127,21 @@
self.class.class_test_root or raise "setup failure: no class_test_root has been set for #{self.class}"
end
# Runs a file-based test that compares files created by the block with
# files in an expected directory. The block receives files from the
- # input directory, and should return a list of files relative to the
+ # input directory, and should return a list of files relative to the
# output directory. Only the files returned by the block are compared;
# additional files in the output directory are effectively ignored.
#
# === Example
# Lets define a test that transforms input files into output files in a
# trivial way, simply by replacing 'input' with 'output' in the file.
#
# class FileTestDocTest < Test::Unit::TestCase
# acts_as_file_test
- #
+ #
# def test_assert_files
# assert_files do |input_files|
# input_files.collect do |path|
# input = File.read(path)
# output_file = method_root.path(:output, File.basename(path))
@@ -150,11 +163,11 @@
# | |- one.txt
# | `- two.txt
# `- input
# |- one.txt
# `- two.txt
- #
+ #
# [input/one.txt]
# test input 1
#
# [input/two.txt]
# test input 2
@@ -163,11 +176,11 @@
# test output 1
#
# [expected/two.txt]
# test output 2
#
- # When you run the test, the assert_files passes the input files to the
+ # When you run the test, the assert_files passes the input files to the
# block. When the block completes, assert_files compares the output
# files returned by the block with the files in the expected directory.
# In this case, the files are equal and the test passes.
#
# Say you changed the content of one of the expected files:
@@ -179,11 +192,11 @@
# expected files. The test also fails if there are missing or extra
# files.
#
# === Options
# A variety of options adjust the behavior of assert_files:
- #
+ #
# :input_dir specify the directory to glob for input files
# (default method_root[:input])
# :output_dir specify the output directory
# (default method_root[:output])
# :expected_dir specify the directory to glob for expected files
@@ -193,22 +206,22 @@
# :include_input_directories specifies directories to be included in the
# input_files array (by default dirs are excluded)
# :include_expected_directories specifies directories to be included in the
# expected-output file list comparison
# (by default dirs are excluded)
- #
+ #
# assert_files will fail if <tt>:expected_files</tt> was not specified
- # in the options and no files were found in <tt>:expected_dir</tt>. This
- # check tries to prevent silent false-positive results when you forget to
- # put expected files in their place.
+ # in the options and no files were found in <tt>:expected_dir</tt>. This
+ # check tries to prevent silent false-positive results when you forget
+ # to put expected files in their place.
#
# === File References
#
- # Sometimes the same files will get used across multiple tests. To allow
- # separate management of test files and prevent duplication, file
- # references can be provided in place of test files. For instance, with a
- # test directory like:
+ # Sometimes the same files will get used across multiple tests. To
+ # allow separate management of test files and prevent duplication, file
+ # references can be provided in place of test files. For instance, with
+ # a test directory like:
#
# method_root
# |- expected
# | |- one.txt.ref
# | `- two.txt.ref
@@ -216,11 +229,11 @@
# | |- one.txt.ref
# | `- two.txt.ref
# `- ref
# |- one.txt
# `- two.txt
- #
+ #
# The input and expected files (all references in this case) can be
# dereferenced to the 'ref' paths like so:
#
# assert_files :reference_dir => method_root[:ref] do |input_files|
# input_files # => ['method_root/ref/one.txt', 'method_root/ref/two.txt']
@@ -234,24 +247,13 @@
#
# Dereferencing occurs relative to the input_dir/expected_dir
# configurations; a reference_dir must be specified for dereferencing to
# occur (see Utils.dereference for more details).
#
- # === Keeping Outputs
- #
- # By default FileTest cleans up everything under method_root except the
- # input and expected directories. For ease in debugging, ENV variable
- # flags can be specified to prevent cleanup for all tests (KEEP_OUTPUTS)
- # or just tests that fail (KEEP_FAILURES). These flags can be specified
- # from the command line if you're running the tests with rake or rap:
- #
- # % rake test keep_outputs=true
- # % rap test keep_failures=true
- #
#--
# TODO:
- # * add debugging information to indicate, for instance,
- # when dereferencing is going on.
+ # * add debugging information to indicate, for instance, when
+ # dereferencing is going on.
def assert_files(options={}, &block) # :yields: input_files
transform_test(block, options) do |expected_file, output_file|
unless FileUtils.cmp(expected_file, output_file)
flunk "<#{expected_file}> not equal to\n<#{output_file}>"
end
\ No newline at end of file