test_construct 1.0.0 → 2.0.0

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# TestConstruct Changelog
+
+## v2.0.0
+
+Enhancements:
+
+* Add RSpec 2 support (@avdi)
+* Option to persist directories after test run or after failure (@avdi)
+* Add naming of created directories (@avdi)
+
+Other:
+
+* Non-backwards-compatible change to `TestConstruct::Helpers#create_construct` method signature (takes option hash now)

data/README.md

@@ -142,6 +142,79 @@ within_construct(:chdir => false) do |construct|
 end
 ```
 
+### Keeping directories around
+
+You may find it convenient to keep the created directory around after a test has completed, in order to manually inspect its contents.
+
+```ruby
+within_construct do |construct|
+  # ...
+  construct.keep
+end
+```
+
+Most likely you only want the directory to stick around if something goes wrong. To do this, use the `:keep_on_error` option.
+
+```ruby
+within_construct(keep_on_error: true) do |construct|
+  # ...
+  raise "some error"
+end
+```
+
+TestConstruct will also annotate the exception error message to tell you where the generated files can be found.
+
+### Setting the base directory
+
+By default, TestConstruct puts its temporary container directories in your system temp dir. You can change this with the `:base_dir` option:
+
+```ruby
+tmp_dir = File.expand_path("../../tmp", __FILE__)
+within_construct(base_dir: tmp_dir) do |construct|
+  construct.file("foo.txt")
+  # Passes
+  assert File.exists?(tmp_dir+"/foo.txt")
+end
+```
+
+### Naming the created directories
+
+Normally TestConstruct names the container directories it creates using a combination of a `test-construct-` prefix, the current process ID, and a random number. This ensures that the name is unlikely to clash with directories left over from previous runs. However, it isn't very meaningful. You can optionally make the directory names more recognizable by specifying a `:name` option. TestConstruct will take the string passed, turn it into a normalized "slug" without any funny characters, and append it to the end of the generated dirname.
+
+```ruby
+within_construct(name: "My best test ever!") do |construct|
+  # will generate something like:
+  # /tmp/construct-container-1234-5678-my-best-test-ever
+end
+```
+
+### RSpec Integration
+
+TestConstruct comes with RSpec integration. Just require the `test_construct/rspec_integration` file in your `spec_helper.rb` or in your spec file. Then tag the tests you want to execute in the context of a construct container with `test_construct: true` using RSpec metadata:
+
+```ruby
+require "test_construct/rspec_integration"
+
+describe Foo, test_construct: true do
+  it "should do stuff" do
+    example.metadata[:construct].file "somefile"
+    example.metadata[:construct].directory "somedir"
+    # ...
+  end
+end
+```
+
+By default, the current working directory will be switched to the construct container within tests; the container name will be derived from the name of the current example; and if a test fails, the container will be kept around. Information about where to find it will be added to the test failure message.
+
+You can tweak any TestConstruct options by passing a hash as the value of the `:test_construct` metadata key.
+
+```ruby
+require "test_construct/rspec_integration"
+
+describe Foo, test_construct: {keep_on_error: false} do
+  # ...
+end
+```
 
 ## Contributing
 

data/examples/foobar_spec.rb

@@ -0,0 +1,34 @@
+# Run with:
+# rspec -Ilib examples/foobar_spec.rb
+
+require 'rspec'
+require 'test_construct/rspec_integration'
+
+describe "Foobar", test_construct: true do
+
+  it "creates file" do
+    example.metadata[:construct].directory "alice/rabbithole" do |d|
+      d.file "white_rabbit.txt", "I'm late!"
+      File.read("white_rabbit.txt").should == "I'm late!"
+    end
+  end
+
+  it "leaves file on error" do
+    example.metadata[:construct].directory "alice/rabbithole" do |d|
+      d.file "white_rabbit.txt", "I'm late!"
+      raise "Whoops"
+    end
+  end
+
+end
+
+describe "Foobar", test_construct: { keep_on_error: false} do
+
+  it "doesn't leave file on error" do
+    example.metadata[:construct].directory "alice/rabbithole" do |d|
+      d.file "white_rabbit.txt", "I'm late!"
+      raise "Whoops"
+    end
+  end
+
+end

data/examples/foobar_test.rb

@@ -0,0 +1,38 @@
+# Run with:
+# ruby -Ilib examples/foobar_test.rb
+
+require 'test_construct'
+require 'test/unit'
+
+class FoobarTest < Test::Unit::TestCase
+  include TestConstruct::Helpers
+
+  def test_directory_and_files
+    within_construct do |c|
+      c.directory 'alice/rabbithole' do |d|
+        d.file 'white_rabbit.txt', "I'm late!"
+
+        assert_equal "I'm late!", File.read('white_rabbit.txt')
+      end
+    end
+  end
+
+  def test_keeping_directory_on_error
+    within_construct(keep_on_error: true) do |c|
+      c.directory 'd' do |d|
+        d.file 'doughnut.txt'
+        raise "whoops"
+      end
+    end
+  end
+
+  def test_deleting_directory_on_error
+    within_construct(keep_on_error: false) do |c|
+      c.directory 'd' do |d|
+        d.file 'doughnut.txt'
+        raise "whoops"
+      end
+    end
+  end
+
+end

data/lib/test_construct/helpers.rb

@@ -1,27 +1,66 @@
+require 'English'
+require 'pathname'
+
 module TestConstruct
 
   module Helpers
     extend self
 
     def within_construct(opts = {})
-      chdir = opts.fetch(:chdir, true)
-      container = create_construct(chdir)
-      container.maybe_change_dir(chdir) do
-        yield(container)
-      end
-    ensure
-      container.destroy! if container.respond_to?(:destroy!)
+      container = setup_construct(opts)
+      yield(container)
+    rescue Exception => error
+      raise unless container
+      teardown_construct(container, error, opts)
+      raise error
+    else
+      teardown_construct(container, nil, opts)
     end
 
-    def create_construct(chdir = true)
-      path = (Pathname(TestConstruct.tmpdir) +
-        "#{CONTAINER_PREFIX}-#{$PROCESS_ID}-#{rand(1_000_000_000)}")
+    def create_construct(opts = {})
+      chdir_default = opts.delete(:chdir) { true }
+      base_path     = Pathname(opts.delete(:base_dir) { TestConstruct.tmpdir })
+      name          = opts.delete(:name) { "" }
+      slug          = name.downcase.tr_s("^a-z0-9", "-")[0..63]
+      if opts.any?
+        raise "[TestConstruct] Unrecognized options: #{opts.keys}"
+      end
+      dir = "#{CONTAINER_PREFIX}-#{$PROCESS_ID}-#{rand(1_000_000_000)}"
+      dir << "-" << slug unless slug.empty?
+      path = base_path + dir
       path.mkpath
       path.extend(PathnameExtensions)
-      path.construct__chdir_default = chdir
+      path.construct__chdir_default = chdir_default
       path
     end
 
+    # THIS METHOD MAY HAVE EXTERNAL SIDE-EFFECTS, including:
+    # - creating the container directory tree
+    # - changing the current working directory
+    #
+    # It is intended to be paired with #teardown_construct
+    def setup_construct(opts = {})
+      opts  = opts.dup
+      chdir = opts.fetch(:chdir, true)
+      opts.delete(:keep_on_error) { false } # not used in setup
+      container = create_construct(opts)
+      container.maybe_change_dir(chdir)
+      container
+    end
+
+    # THIS METHOD MAY HAVE EXTERNAL SIDE-EFFECTS, including:
+    # - removing the container directory tree
+    # - changing the current working directory
+    # - modifying any exception passed as `error`
+    #
+    # It is intended to be paired with #setup_construct
+    def teardown_construct(container, error = nil, opts = {})
+      if error && opts[:keep_on_error]
+        container.keep
+        container.annotate_exception!(error)
+      end
+      container.finalize
+    end
   end
 
   extend Helpers

data/lib/test_construct/pathname_extensions.rb

@@ -1,13 +1,13 @@
 module TestConstruct
   module PathnameExtensions
 
-    attr_accessor :construct__chdir_default
-
+    attr_accessor :construct__chdir_default, :construct__root, :construct__orig_dir
     def directory(path, opts = {})
       chdir = opts.fetch(:chdir, construct__chdir_default)
       subdir = (self + path)
       subdir.mkpath
       subdir.extend(PathnameExtensions)
+      subdir.construct__root = construct__root || self
       subdir.maybe_change_dir(chdir) do
         yield(subdir) if block_given?
       end
@@ -33,9 +33,16 @@ module TestConstruct
 
     def maybe_change_dir(chdir, &block)
       if(chdir)
+        self.construct__orig_dir ||= Pathname.pwd
         self.chdir(&block)
       else
-        block.call
+        block.call if block
+      end
+    end
+
+    def revert_cwd
+      if construct__orig_dir
+        Dir.chdir(construct__orig_dir)
       end
     end
 
@@ -49,5 +56,30 @@ module TestConstruct
       rmtree
     end
 
+    def finalize
+      revert_cwd
+      destroy! unless keep?
+    end
+
+    def keep
+      if construct__root
+        construct__root.keep
+      else
+        @keep = true
+      end
+    end
+
+    def keep?
+      defined?(@keep) && @keep
+    end
+
+    def annotate_exception!(error)
+      error.message << exception_message_annotation
+      error
+    end
+
+    def exception_message_annotation
+      "\nTestConstruct files kept at: #{self}"
+    end
   end
 end

data/lib/test_construct/rspec_integration.rb

@@ -0,0 +1,53 @@
+require "test_construct"
+require "rspec"
+module TestConstruct
+  module RSpecIntegration
+    module_function
+
+    # the :test_construct metadata key can be either:
+    # - true (for all defaults)
+    # - a Hash of options
+    # - false/missing (disable the construct for this test)
+    def test_construct_options(example)
+      options = test_construct_default_options
+      options[:name] = example.full_description
+      metadata_options = example.metadata[:test_construct]
+      if metadata_options.is_a?(Hash)
+        options.merge!(metadata_options)
+      end
+      options
+    end
+
+    def test_construct_enabled?(example)
+      !!example.metadata[:test_construct]
+    end
+
+    def test_construct_default_options
+      {
+        base_dir:       TestConstruct.tmpdir,
+        chdir:          true,
+        keep_on_error:  true,
+      }
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include TestConstruct::Helpers
+  config.include TestConstruct::RSpecIntegration
+
+  config.before :each do
+    next unless test_construct_enabled?(example)
+    options = test_construct_options(example)
+    example.metadata[:construct] = setup_construct(options)
+  end
+
+  config.after :each do
+    next unless test_construct_enabled?(example)
+    options = test_construct_options(example)
+    teardown_construct(
+      example.metadata[:construct],
+      example.exception,
+      options)
+  end
+end

data/lib/test_construct/version.rb

@@ -1,3 +1,3 @@
 module TestConstruct
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

data/test/test_construct_test.rb

@@ -4,6 +4,7 @@ class TestConstructTest < Minitest::Test
   include TestConstruct::Helpers
 
   def teardown
+    Dir.chdir File.expand_path("../..", __FILE__)
     TestConstruct.destroy_all!
   end
 
@@ -464,7 +465,6 @@ Contents
   end
 
   testing "#destroy!" do
-
     test "removes the construct container" do
       it = create_construct
       it.destroy!
@@ -472,4 +472,70 @@ Contents
     end
   end
 
+  testing "#finalize" do
+    test "removes the construct container" do
+      it = create_construct
+      it.finalize
+      assert !File.exist?(it.to_s)
+    end
+
+    test "leaves the container if keep is flagged" do
+      it = create_construct
+      it.keep
+      it.finalize
+      assert File.exist?(it.to_s)
+    end
+
+    test "leaves the container if keep is flagged in a subdir" do
+      it = create_construct
+      subdir = it.directory "subdir"
+      subdir.keep
+      it.finalize
+      assert File.exist?(it.to_s)
+    end
+  end
+
+  testing "keep_on_error = true" do
+    test 'keeps dir when block raises exception' do
+      path = nil
+      begin
+        within_construct(keep_on_error: true) do |container_path|
+          path = container_path
+          raise 'something bad happens here'
+        end
+      rescue
+      end
+      assert path.exist?
+    end
+
+    test 'updates exception message to include location of files' do
+      path = nil
+      begin
+        within_construct(keep_on_error: true) do |container_path|
+          path = container_path
+          raise 'bad stuff'
+        end
+      rescue => e
+        error = e
+      end
+      assert_equal "bad stuff\nTestConstruct files kept at: #{path}", e.message
+    end
+  end
+
+  testing 'base_dir option' do
+    test 'determines the location of construct dirs' do
+      base_dir = File.expand_path("../temp", __FILE__)
+      within_construct(base_dir: base_dir) do |container|
+        assert_equal base_dir, container.dirname.to_s
+      end
+    end
+  end
+
+  testing 'name option' do
+    test 'used in generation of the directory name' do
+      within_construct(name: "My best test ever!") do |container|
+        assert_match /my-best-test-ever-$/, container.basename.to_s
+      end
+    end
+  end
 end

data/test_construct.gemspec

@@ -23,4 +23,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "minitest", "~> 5.0.8"
   spec.add_development_dependency "mocha", "~> 0.14.0"
   spec.add_development_dependency "debugger"
+  spec.add_development_dependency "rspec"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: test_construct
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-04 00:00:00.000000000 Z
+date: 2013-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -92,6 +92,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Creates temporary files and directories for testing.
 email:
 - ben@bbrinck.com
@@ -101,13 +117,17 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/foobar_spec.rb
+- examples/foobar_test.rb
 - lib/test_construct.rb
 - lib/test_construct/helpers.rb
 - lib/test_construct/pathname_extensions.rb
+- lib/test_construct/rspec_integration.rb
 - lib/test_construct/version.rb
 - test/test_construct_test.rb
 - test/test_helper.rb