test_construct 0.0.1 → 1.0.0

data/README.md

@@ -1,6 +1,25 @@
 # TestConstruct
 
-TODO: Write a gem description
+> "This is the construct. It's our loading program. We can load anything, from clothing to equipment, weapons, and training simulations, anything we need" -- Morpheus
+
+TestConstruct is a DSL for creating temporary files and directories during testing.
+
+## SYNOPSIS
+
+    class ExampleTest < Test::Unit::TestCase
+      include TestConstruct::Helpers
+
+      def test_example
+        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
+
+    end
 
 ## Installation
 
@@ -18,7 +37,111 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+To use TestConstruct, you need to include the TestConstruct module in your class like so:
+
+    include TestConstruct::Helpers
+
+Using construct is as simple as calling `within_construct` and providing a block. All files and directories that are created within that block are created within a temporary directory. The temporary directory is always deleted before `within_construct` finishes.
+
+There is nothing special about the files and directories created with TestConstruct, so you can use plain old Ruby IO methods to interact with them.
+
+### Creating files
+
+The most basic use of TestConstruct is creating an empty file with the:
+
+    within_construct do |construct|
+      construct.file('foo.txt')
+    end
+
+Note that the working directory is, by default, automatically changed to the temporary directory created by TestConstruct, so the following assertion will pass:
+
+    within_construct do |construct|
+      construct.file('foo.txt')
+      assert File.exist?('foo.txt')
+    end
+
+You can also provide content for the file, either with an optional argument or using the return value of a supplied block:
+
+    within_construct do |construct|
+      construct.file('foo.txt', 'Here is some content')
+      construct.file('bar.txt') do
+        <<-EOS
+        The block will return this string, which will be used as the content.
+        EOS
+      end
+    end
+
+If you provide block that accepts a parameter, construct will pass in the IO object. In this case, you are responsible for writing content to the file yourself - the return value of the block will not be used:
+
+    within_construct do |construct|
+      construct.file('foo.txt') do |file|
+        file << "Some content\n"
+        file << "Some more content"
+      end
+    end
+
+Finally, you can provide the entire path to a file and the parent directories will be created automatically:
+
+    within_construct do |construct|
+      construct.file('foo/bar/baz.txt')
+    end
+
+### Creating directories
+
+It is easy to create a directory:
+
+    within_construct do |construct|
+      construct.directory('foo')
+    end
+
+You can also provide a block. The object passed to the block can be used to create nested files and directories (it's just a [Pathname](http://www.ruby-doc.org/stdlib/libdoc/pathname/rdoc/index.html) instance with some extra functionality, so you can use it to get the path of the current directory).
+
+Again, note that the working directory is automatically changed while in the block:
+
+    within_construct do |construct|
+      construct.directory('foo') do |dir|
+        dir.file('bar.txt')
+        assert File.exist?('bar.txt') # This assertion will pass
+      end
+    end
+
+Again, you can provide paths and the necessary directories will be automatically created:
+
+
+    within_construct do |construct|
+      construct.directory('foo/bar/') do |dir|
+        dir.directory('baz')
+        dir.directory('bazz')
+      end
+    end
+
+Please read test/construct_test.rb for more examples.
+
+### Disabling chdir
+
+In some cases, you may wish to disable the default behavior of automatically changing the current directory. For example, changing the current directory will prevent Ruby debuggers from displaying source code correctly.
+
+If you disable, automatic chdir, note that your old assertions will not work:
+
+```
+within_construct(:chdir => false) do |construct|
+  construct.file("foo.txt")
+  # Fails. foo.txt was created in construct, but 
+  # the current directory is not the construct!
+  assert File.exists?("foo.txt")
+end
+```
+
+To fix, simply use the `Pathname` passed to the block:
+
+```
+within_construct(:chdir => false) do |construct|
+  construct.file("foo.txt")
+  # Passes
+  assert File.exists?(construct+"foo.txt")
+end
+```
+
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,10 @@
 require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task :default => [:test]

data/lib/test_construct/helpers.rb

@@ -0,0 +1,28 @@
+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!)
+    end
+
+    def create_construct(chdir = true)
+      path = (Pathname(TestConstruct.tmpdir) +
+        "#{CONTAINER_PREFIX}-#{$PROCESS_ID}-#{rand(1_000_000_000)}")
+      path.mkpath
+      path.extend(PathnameExtensions)
+      path.construct__chdir_default = chdir
+      path
+    end
+
+  end
+
+  extend Helpers
+end

data/lib/test_construct/pathname_extensions.rb

@@ -0,0 +1,53 @@
+module TestConstruct
+  module PathnameExtensions
+
+    attr_accessor :construct__chdir_default
+
+    def directory(path, opts = {})
+      chdir = opts.fetch(:chdir, construct__chdir_default)
+      subdir = (self + path)
+      subdir.mkpath
+      subdir.extend(PathnameExtensions)
+      subdir.maybe_change_dir(chdir) do
+        yield(subdir) if block_given?
+      end
+      subdir
+    end
+
+    def file(filepath, contents = nil, &block)
+      path = (self+filepath)
+      path.dirname.mkpath
+      File.open(path,'w') do |f|
+        if(block)
+          if(block.arity==1)
+            block.call(f)
+          else
+            f << block.call
+          end
+        else
+          f << contents
+        end
+      end
+      path
+    end
+
+    def maybe_change_dir(chdir, &block)
+      if(chdir)
+        self.chdir(&block)
+      else
+        block.call
+      end
+    end
+
+    # Note: Pathname implements #chdir directly, but it is deprecated in favor
+    # of Dir.chdir
+    def chdir(&block)
+      Dir.chdir(self, &block)
+    end
+
+    def destroy!
+      rmtree
+    end
+
+  end
+end

data/lib/test_construct/version.rb

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

data/lib/test_construct.rb

@@ -1,5 +1,23 @@
+require "tmpdir"
+
 require "test_construct/version"
+require "test_construct/helpers"
+require "test_construct/pathname_extensions"
 
 module TestConstruct
-  # Your code goes here...
+
+  CONTAINER_PREFIX = 'construct_container'
+
+  def self.tmpdir
+    dir = nil
+    Dir.chdir Dir.tmpdir do dir = Dir.pwd end # HACK FOR OS X
+    dir
+  end
+
+  def self.destroy_all!
+    Pathname.glob(File.join(tmpdir, CONTAINER_PREFIX + "*")) do |container|
+      container.rmtree
+    end
+  end
+
 end

data/test/test_construct_test.rb

@@ -0,0 +1,475 @@
+require 'test_helper'
+
+class TestConstructTest < Minitest::Test
+  include TestConstruct::Helpers
+
+  def teardown
+    TestConstruct.destroy_all!
+  end
+
+  testing 'using within_construct explicitly' do
+
+    test 'creates construct' do
+      num = rand(1_000_000_000)
+      TestConstruct.stubs(:rand).returns(num)
+      directory = false
+      TestConstruct::within_construct do |construct|
+        directory = File.directory?(File.join(TestConstruct.tmpdir, "construct_container-#{$PROCESS_ID}-#{num}"))
+      end
+      assert directory
+
+      directory = false
+      TestConstruct.within_construct do |construct|
+        directory = File.directory?(File.join(TestConstruct.tmpdir, "construct_container-#{$PROCESS_ID}-#{num}"))
+      end
+      assert directory
+    end
+
+  end
+
+  testing 'creating a construct container' do
+
+    test 'exists' do
+      num = rand(1_000_000_000)
+      self.stubs(:rand).returns(num)
+      within_construct do |construct|
+        assert File.directory?(File.join(TestConstruct.tmpdir, "construct_container-#{$PROCESS_ID}-#{num}"))
+      end
+    end
+
+    test 'yields to its block' do
+      sensor = 'no yield'
+      within_construct do
+        sensor = 'yielded'
+      end
+      assert_equal 'yielded', sensor
+    end
+
+    test 'block argument is container directory Pathname' do
+      num = rand(1_000_000_000)
+      self.stubs(:rand).returns(num)
+      within_construct do |container_path|
+        expected_path = (Pathname(TestConstruct.tmpdir) +
+          "construct_container-#{$PROCESS_ID}-#{num}")
+        assert_equal(expected_path, container_path)
+      end
+    end
+
+    test 'does not exist afterwards' do
+      path = nil
+      within_construct do |container_path|
+        path = container_path
+      end
+      assert !path.exist?
+    end
+
+    test 'removes entire tree afterwards' do
+      path = nil
+      within_construct do |container_path|
+        path = container_path
+        (container_path + 'foo').mkdir
+      end
+      assert !path.exist?
+    end
+
+    test 'removes dir if block raises exception' do
+      path = nil
+      begin
+        within_construct do |container_path|
+          path = container_path
+          raise 'something bad happens here'
+        end
+      rescue
+      end
+      assert !path.exist?
+    end
+
+    test 'does not capture exceptions raised in block' do
+      err = RuntimeError.new('an error')
+      begin
+        within_construct do
+          raise err
+        end
+      rescue RuntimeError => e
+        assert_same err, e
+      end
+    end
+
+  end
+
+  testing 'creating a file in a container' do
+
+    test 'exists while in construct block' do
+      within_construct do |construct|
+        construct.file('foo.txt')
+        assert File.exists?(construct + 'foo.txt')
+      end
+    end
+
+    test 'does not exist after construct block' do
+      filepath = 'unset'
+      within_construct do |construct|
+        filepath = construct.file('foo.txt')
+      end
+      assert !File.exists?(filepath)
+    end
+
+    test 'has empty file contents by default' do
+      within_construct do |construct|
+        construct.file('foo.txt')
+        assert_equal '', File.read(construct + 'foo.txt')
+      end
+    end
+
+    test 'writes contents to file' do
+      within_construct do |construct|
+        construct.file('foo.txt','abcxyz')
+        assert_equal 'abcxyz', File.read(construct+'foo.txt')
+      end
+    end
+
+    test 'contents can be given in a block' do
+      within_construct do |construct|
+        construct.file('foo.txt') do
+          <<-EOS
+File
+Contents
+          EOS
+        end
+        assert_equal "File\nContents\n", File.read(construct+'foo.txt')
+      end
+    end
+
+    test 'contents block overwrites contents argument' do
+      within_construct do |construct|
+        construct.file('foo.txt','abc') do
+          'xyz'
+        end
+        assert_equal 'xyz', File.read(construct+'foo.txt')
+      end
+    end
+
+    test 'block is passed File object' do
+      within_construct do |construct|
+        construct.file('foo.txt') do |file|
+          assert_equal((construct+'foo.txt').to_s, file.path)
+        end
+      end
+    end
+
+    test 'writes to File object passed to block' do
+      within_construct do |construct|
+        construct.file('foo.txt') do |file|
+          file << 'abc'
+        end
+        assert_equal 'abc', File.read(construct+'foo.txt')
+      end
+    end
+
+    test 'closes file after block ends' do
+      within_construct do |construct|
+        construct_file = nil
+        construct.file('foo.txt') do |file|
+          construct_file = file
+        end
+        assert construct_file.closed?
+      end
+    end
+
+    test 'block return value not used as content if passed File object' do
+      within_construct do |construct|
+        construct.file('foo.txt') do |file|
+          file << 'abc'
+          'xyz'
+        end
+        assert_equal 'abc', File.read(construct+'foo.txt')
+      end
+    end
+
+    test 'contents argument is ignored if block takes File arg' do
+      within_construct do |construct|
+        construct.file('foo.txt','xyz') do |file|
+          file << 'abc'
+        end
+        assert_equal 'abc', File.read(construct+'foo.txt')
+      end
+    end
+
+    test 'returns file path' do
+      within_construct do |construct|
+        assert_equal(construct+'foo.txt', construct.file('foo.txt'))
+      end
+    end
+
+    test 'creates file including path in one call' do
+      within_construct do |construct|
+        construct.file('foo/bar/baz.txt')
+        assert (construct+'foo/bar/baz.txt').exist?
+      end
+    end
+
+    test 'creates file including path in one call when directories exists' do
+      within_construct do |construct|
+        construct.directory('foo/bar')
+        construct.file('foo/bar/baz.txt')
+        assert (construct+'foo/bar/baz.txt').exist?
+      end
+    end
+
+    test 'creates file including path with chained calls' do
+      within_construct do |construct|
+        construct.directory('foo').directory('bar').file('baz.txt')
+        assert (construct+'foo/bar/baz.txt').exist?
+      end
+    end
+
+  end
+
+    testing 'creating a subdirectory in container' do
+
+    test 'exists while in construct block' do
+      within_construct do |construct|
+        construct.directory 'foo'
+        assert (construct+'foo').directory?
+      end
+    end
+
+    test 'does not exist after construct block' do
+      subdir = 'unset'
+      within_construct do |construct|
+        construct.directory 'foo'
+        subdir = construct + 'foo'
+      end
+      assert !subdir.directory?
+    end
+
+    test 'returns the new path name' do
+      within_construct do |construct|
+        assert_equal((construct+'foo'), construct.directory('foo'))
+      end
+    end
+
+    test 'yield to block' do
+      sensor = 'unset'
+      within_construct do |construct|
+        construct.directory('bar') do
+          sensor = 'yielded'
+        end
+      end
+      assert_equal 'yielded', sensor
+    end
+
+    test 'block argument is subdirectory path' do
+      within_construct do |construct|
+        construct.directory('baz') do |dir|
+          assert_equal((construct+'baz'),dir)
+        end
+      end
+    end
+
+    test 'creates nested directory in one call' do
+      within_construct do |construct|
+        construct.directory('foo/bar')
+        assert (construct+'foo/bar').directory?
+      end
+    end
+
+    test 'creates a nested directory in two calls' do
+      within_construct do |construct|
+        construct.directory('foo').directory('bar')
+        assert (construct+'foo/bar').directory?
+      end
+    end
+
+  end
+
+  testing "subdirectories changing the working directory" do
+
+    test 'forces directory stays the same' do
+      within_construct do |construct|
+        old_pwd = Dir.pwd
+        construct.directory('foo', :chdir => false) do
+          assert_equal old_pwd, Dir.pwd
+        end
+      end
+    end
+
+    test 'defaults chdir setting from construct' do
+      within_construct(:chdir => false) do |construct|
+        old_pwd = Dir.pwd
+        construct.directory('foo') do
+          assert_equal old_pwd, Dir.pwd
+        end
+      end
+    end
+
+    test 'overrides construct default' do
+      within_construct(:chdir => false) do |construct|
+        old_pwd = Dir.pwd
+        construct.directory('foo', :chdir => true) do |dir|
+          assert_equal dir.to_s, Dir.pwd
+        end
+      end
+    end
+
+    test 'current working directory is within subdirectory' do
+      within_construct do |construct|
+        construct.directory('foo') do |dir|
+          assert_equal dir.to_s, Dir.pwd
+        end
+      end
+    end
+
+    test 'current working directory is unchanged outside of subdirectory' do
+      within_construct do |construct|
+        old_pwd = Dir.pwd
+        construct.directory('foo')
+        assert_equal old_pwd, Dir.pwd
+      end
+    end
+
+    test 'current working directory is unchanged after exception' do
+      within_construct do |construct|
+        old_pwd = Dir.pwd
+        begin
+          construct.directory('foo') do
+            raise 'something bad happens here'
+          end
+        rescue
+        end
+        assert_equal old_pwd, Dir.pwd
+      end
+    end
+
+    test 'captures exceptions raised in block' do
+      within_construct do |construct|
+        error = assert_raises RuntimeError do
+          construct.directory('foo') do
+            raise 'fail!'
+          end
+        end
+        assert_equal 'fail!', error.message
+      end
+    end
+
+    test 'checking for a file is relative to subdirectory' do
+      within_construct do |construct|
+        construct.directory('bar')  do |dir|
+          dir.file('foo.txt')
+          assert File.exists?('foo.txt')
+        end
+      end
+    end
+
+    test 'checking for a directory is relative to subdirectory' do
+      within_construct do |construct|
+        construct.directory('foo') do |dir|
+          dir.directory('mydir')
+          assert File.directory?('mydir')
+        end
+      end
+    end
+
+  end
+
+  testing "changing the working directory" do
+
+    test 'forces directory stays the same' do
+      old_pwd = Dir.pwd
+      within_construct(:chdir => false) do |construct|
+        assert_equal old_pwd, Dir.pwd
+      end
+    end
+
+    test 'current working directory is within construct' do
+      within_construct do |construct|
+        assert_equal construct.to_s, Dir.pwd
+      end
+    end
+
+    test 'current working directory is unchanged outside of construct' do
+      old_pwd = Dir.pwd
+      within_construct do |construct|
+      end
+      assert_equal old_pwd, Dir.pwd
+    end
+
+    test 'current working directory is unchanged after exception' do
+      old_pwd = Dir.pwd
+      begin
+        within_construct do |construct|
+          raise 'something bad happens here'
+        end
+      rescue
+      end
+      assert_equal old_pwd, Dir.pwd
+    end
+
+    test 'does not capture exceptions raised in block' do
+      error = assert_raises RuntimeError do
+        within_construct do
+          raise 'fail!'
+        end
+      end
+      assert_equal 'fail!', error.message
+    end
+
+    test 'checking for a file is relative to container' do
+      within_construct do |construct|
+        construct.file('foo.txt')
+        assert File.exists?('foo.txt')
+      end
+    end
+
+    test 'checking for a directory is relative to container' do
+      within_construct do |construct|
+        construct.directory('mydir')
+        assert File.directory?('mydir')
+      end
+    end
+
+  end
+
+  testing "#create_construct" do
+
+    test "returns a working Construct" do
+      it = create_construct
+      it.directory "foo"
+      it.file "bar", "CONTENTS"
+      assert (it + "foo").directory?
+      assert_equal "CONTENTS", (it + "bar").read
+    end
+
+  end
+
+  testing "#chdir" do
+
+    test "executes its block in the context of the construct" do
+      it = create_construct
+      refute_equal it.to_s, Dir.pwd
+      sensor = :unset
+      it.chdir do
+        sensor = Dir.pwd
+      end
+      assert_equal it.to_s, sensor
+    end
+
+    test "leaves construct directory on block exit" do
+      it = create_construct
+      it.chdir do
+        # NOOP
+      end
+      refute_equal it.to_s, Dir.pwd
+    end
+  end
+
+  testing "#destroy!" do
+
+    test "removes the construct container" do
+      it = create_construct
+      it.destroy!
+      assert !File.exist?(it.to_s)
+    end
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,24 @@
+require 'minitest'
+require "minitest/autorun"
+
+require 'mocha/setup'
+require 'test_construct'
+
+class Minitest::Test
+
+  def self.testing(name)
+    @group = name
+    yield
+    @group = nil
+  end
+
+  def self.test(name, &block)
+    name = name.strip.gsub(/\s\s+/, " ")
+    group = "#{@group}: " if @group
+    test_name = "test_: #{group}#{name}".to_sym
+    defined = instance_methods.include? test_name
+    raise "#{test_name} is already defined in #{self}" if defined
+    define_method(test_name, &block)
+  end
+
+end

data/test_construct.gemspec

@@ -20,4 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest", "~> 5.0.8"
+  spec.add_development_dependency "mocha", "~> 0.14.0"
+  spec.add_development_dependency "debugger"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: test_construct
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-27 00:00:00.000000000 Z
+date: 2013-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -44,6 +44,54 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 5.0.8
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 5.0.8
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+- !ruby/object:Gem::Dependency
+  name: debugger
+  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
@@ -58,7 +106,11 @@ files:
 - README.md
 - Rakefile
 - lib/test_construct.rb
+- lib/test_construct/helpers.rb
+- lib/test_construct/pathname_extensions.rb
 - lib/test_construct/version.rb
+- test/test_construct_test.rb
+- test/test_helper.rb
 - test_construct.gemspec
 homepage: ''
 licenses:
@@ -85,4 +137,6 @@ rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Creates temporary files and directories for testing.
-test_files: []
+test_files:
+- test/test_construct_test.rb
+- test/test_helper.rb