clean_test 0.10.0

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+coverage
+html

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.3@clean_test --create

data/.travis.yml

@@ -0,0 +1,12 @@
+notifications:
+  email:
+    on_success: always
+script: 'bundle exec rake'
+rvm: 
+  - 1.9.2
+  - 1.9.3
+  - 1.8.7
+  - ree
+  - ruby-head
+  - rbx
+  - jruby

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.rdoc

@@ -0,0 +1,343 @@
+= Clean Tests
+
+Author::  Dave Copeland (mailto:davetron5000 at g mail dot com)
+Copyright:: Copyright (c) 2012 by Dave Copeland
+License:: Distributes under the Apache License, see LICENSE.txt in the source distro
+
+Get your Test::Unit test cases readable and fluent, without RSpec, magic, or crazy meta-programming.
+
+This library is a set of small, simple tools to make your Test::Unit test cases easy to understand.  This isn't a massive change in how you write tests, but simply some helpful things will make your tests easier to read.
+
+The main problems this library solves are:
+
+* Understanding what part of a test method is setup, test, and evaluation
+* Understanding what elements of a test are relevant to the test, and which are arbitrary placeholders
+* Removing the requirement that your tests are method names
+
+<b>Note: this gem is still called <tt>test_unit-given</tt> in RubyGems; I'm in the middle of changing the name</b>
+
+== Install
+
+    gem install clean_test
+
+Or, with bundler:
+
+    gem "clean_test", :require => false
+
+== Overview
+
+    class Circle
+      attr_reader :name
+      attr_reader :radius
+
+      def initialize(radius,name)
+        @radius = radius
+        @name = name
+      end
+
+      def area
+        @radius * @radius * 3.14
+      end
+
+      def to_s
+        "circle of radius #{radius}, named #{name}"
+      end
+
+    end
+
+    require 'clean_test/test_case'
+
+    class CircleTest < Clean::Test::TestCase
+      test_that "area is computed correctly" {
+        Given {
+          @circle = Circle.new(10,any_string)
+        }
+        When {
+          @area = @circle.area
+        }
+        Then {
+          assert_equal 314,@area
+        }
+      }
+
+      test_that "to_s includes the name" {
+        Given { 
+          @name = "foo"
+          @circle = Circle.new(any_int,@name)
+        }
+        When {
+          @string = @circle.to_s
+        }
+        Then {
+          assert_match /#{@name}/,@string
+        }
+      }
+    end
+
+What's going on here?
+
+* We can clearly see which parts of our test are setting things up (stuff inside +Given+), which parts are executing the code we're testing (stuff in +When+) and which parts are evalulating the results (stuff in +Then+)
+* We can see which values are relevant to the test - only those that are literals.  In the first test, the +name+ of our circle is not relevant to the test, so instead of using a dummy value like <tt>"foo"</tt>, we use +any_string+, which makes it clear that the value <i>does not matter</i>.  Similarly, in the second test, the radius is irrelevant, so we use +any_int+ to signify that it doesn't matter.
+* Our tests are clearly named and described with strings, but we didn't need to bring in active support.
+* A side effect of this structure is that we use instance vars to pass data between Given/When/Then blocks. This means that instance vars "jump out" as important variables to the test; non-instance vars "fade away" into the background.
+
+But, don't fret, this is not an all-or-nothing proposition.  Use whichever parts you like.  Each feature is in a module that you can include as needed, or you can do what we're doing here and extend Clean::Test::TestCase to get everything at once.
+
+== More Info
+
+* Clean::Test::TestCase is the base class that gives you everything
+* Clean::Test::GivenWhenThen provides the Given/When/Then construct
+* Clean::Test::TestThat provides +test_that+
+* Clean::Test::Any provides the +any_string+ and friends.
+
+== Questions you might have
+
+=== Why?
+
+I'm tired of unreadable tests.  Tests should be good, clean code, and it shoud be easy to see what's being tested.  This is especially important when there is a lot of setup required to simulate something.
+
+I also don't believe we need to resort ot a lot of metaprogramming tricks just to get our tests in this shape.  RSpec, for example, creates strange constructs for things that are much more straightforward in plain Ruby.  I like Test::Unit, and with just a bit of helper methods, we can make nice, readable tests, using just Ruby.
+
+=== But the test methods are longer!
+
+And?  I don't mind a test method that's a bit longer if that makes it easy to understand.  Certainly, a method like this is short:
+
+
+    def test_radius
+      assert_equal 314,Circle.new(10).radius
+    end
+
+But, we rarely get such simple methods *and* this test method isn't very modifiable; everything is on one line and it doesn't encourage re-use.  We can do better.
+
+=== What about mocks?
+
+Mocks create an interesting issue, because the "assertions" are the mock expectations you setup before you call the method under test.  This means that the "then" side of things is out of order.
+
+    class CircleTest < Test::Unit::Given::TestCase
+      test_that "our external diameter service is being used" do
+        Given {
+          @diameter_service = mock()
+          @diameter_service.expects(:get_diameter).with(10).returns(400)
+          @circle = Circle.new(10,@diameter_service)
+        }
+        When  {
+          @diameter = @circle.diameter
+        }
+        Then {
+          // assume mocks were called
+        }
+      end
+    end
+
+This is somewhat confusing.  We could solve it using two blocks provided by this library, +the_test_runs+, and +mocks_shouldve_been_called+, like so:
+
+    class CircleTest < Test::Unit::Given::TestCase
+      test_that "our external diameter service is being used" do
+        Given {
+          @diameter_service = mock()
+        }
+        When the_test_runs
+        Then {
+          @diameter_service.expects(:get_diameter).with(10).returns(400)
+        }
+        Given {
+          @circle = Circle.new(10,@diameter_service)
+        }
+        When  {
+          @diameter = @circle.diameter
+        }
+        Then mocks_shouldve_been_called
+      end
+    end
+
+Although both <tt>the_test_runs</tt> and <tt>mocks_shouldve_been_called</tt> are no-ops,
+they allow our tests to be readable and make clear what the assertions are that we are making.
+
+Yes, this makes our test a bit longer, but it's *much* more clear.
+
+=== What about block-based assertions, like +assert_raises+
+
+Again, things are a bit out of order in a class test case, but you can clean this up without this library or any craziness, by just using Ruby:
+
+    class CircleTest < Clean::Test::TestCase
+
+      test_that "there is no diameter method" do
+        Given {
+          @circle = Circle.new(10)
+        }
+        When {
+          @code = lambda { @circle.diameter }
+        }
+        Then {
+          assert_raises(NoMethodError,&@code)
+        }
+      end
+    end
+
+=== My tests require a lot of setup, so I use contexts in shoulda/RSpec.  What say you?
+
+Duplicated setup can be tricky.  A problem with heavily nested contexts in Shoulda or RSpec is that it can be hard to piece together what all the "Givens" of a particular test actually are.  As a reaction to this, a lot of developers tend to just duplicate setup code, so that each test "stands on its own".  This makes adding features or changing things difficult, because it's not clear what duplicated code is the same by happenstance, or the same because it's *supposed* to be the same.
+
+To deal with this, we simply use Ruby and <i>method extraction</i>.  Let's say we have a +Salutation+ class that takes a +Person+ and a +Language+ in its constructor, and then provides methods to "greet" that person
+
+    class Salutation
+      def initialize(person,language)
+        raise "person required" if person.nil?
+        raise "language required" if language.nil?
+      end
+
+      # ... methods
+    end
+
+To test this class, we always need a non-nil person and language.  We might end up with code like this:
+
+    class SalutationTest << Clean::Test::TestCase
+      test_that "greeting works" do
+        Given {
+          person = Person.new("David","Copeland",:male)
+          language = Language.new("English","en")
+          @salutation = Salutation.new(person,language)
+        }
+        When { 
+          @greeting = @salutation.greeting
+        }
+        Then {
+          assert_equal "Hello, David!",@salutation.greeting
+        }
+      end
+
+      test_that "greeting works for no first name" do
+        Given {
+          person = Person.new(nil,"Copeland",:male)
+          language = Language.new("English","en")
+          @salutation = Salutation.new(person,language)
+        }
+        When { 
+          @greeting = @salutation.greeting
+        }
+        Then {
+          assert_equal "Hello, Mr. Copeland!",@salutation.greeting
+        }
+      end
+    end
+
+In both cases, the language is the same, and the person is slightly different.  Method extraction:
+
+    class SalutationTest << Clean::Test::TestCase
+      test_that "greeting works" do
+        Given {
+          @salutation = Salutation.new(male_with_first_name("David"),english)
+        }
+        When { 
+          @greeting = @salutation.greeting
+        }
+        Then {
+          assert_equal "Hello, David!",@salutation.greeting
+        }
+      end
+
+      test_that "greeting works for no first name" do
+        Given {
+          @salutation = Salutation.new(male_with_no_first_name("Copeland"),english)
+        }
+        When { 
+          @greeting = @salutation.greeting
+        }
+        Then {
+          assert_equal "Hello, Mr. Copeland!",@salutation.greeting
+        }
+      end
+
+    private
+      def male_with_first_name(first_name)
+        Person.new(first_name,any_string,:male)
+      end
+
+      def male_with_no_first_name(last_name)
+        Person.new(nil,last_name,:male)
+      end
+
+      def english; Language.new("English","en"); end
+    end
+
+=== What did that have to do with this gem?
+
+Nothing.  That's the point.  You have the power already.  Note that, since +Given+ takes a block, you can re-use things that way, if you like:
+
+    class SalutationTest << Clean::Test::TestCase
+      test_that "greeting works" do
+        Given english_salutation_for(male_with_first_name("David")
+        When { 
+          @greeting = @salutation.greeting
+        }
+        Then {
+          assert_equal "Hello, David!",@salutation.greeting
+        }
+      end
+
+      test_that "greeting works for no first name" do
+        Given english_salutation_for(male_with_first_name("Copeland")
+        When { 
+          @greeting = @salutation.greeting
+        }
+        Then {
+          assert_equal "Hello, Mr. Copeland!",@salutation.greeting
+        }
+      end
+
+    private
+      def male_with_first_name(first_name)
+        Person.new(first_name,any_string,:male)
+      end
+
+      def male_with_no_first_name(last_name)
+        Person.new(nil,last_name,:male)
+      end
+
+      def english_salutation_for(person)
+        lambda {
+          @salutation = Salutation.new(person,Language.new("English","en"))
+        }
+      end
+    end
+
+This sort of thing can get confusing, but sometimes works well.
+
+=== Why Any instead of Faker?
+
+Faker is used by Any under the covers, but Faker has two problems:
+
+* We aren't _faking_ values, we're using _arbitrary_ values.  There's a difference semantically, even if the mechanics are the same
+* Faker requires too much typing to get arbitrary values.  I'd rather type +any_string+ than <tt>Faker::Lorem.words(1).join(' ')</tt>
+
+=== What about Factory Girl?
+
+Again, FactoryGirl goes through metaprogramming hoops to do something we can already do in Ruby: call methods.  Factory Girl also places factories in global scope, making tests more brittle.  You either have a ton of tests depending on the same factory or you have test-specific factories, all in global scope.  It's just simpler and more maintainable to use methods and modules for this.  To re-use "factories" produced by simple methods, just put them in a module.
+
+Further, the +Any+ module is extensible, in that you can do stuff like <tt>any Person</tt>, but you can, and should, just use methods.  Any helps out with primitives that we tend to use a lot: numbers and strings.  It's just simpler and, with less moving parts, more predictable.  This means you spend more time on your tests than on your test infrastructure.
+
+=== What about not using the base class?
+
+To use Any on its own:
+
+    require 'clean_test/any'
+
+    class MyTest < Test::Unit::TestCase
+      include Clean::Test::Any
+    end
+
+To use GivenWhenThen on its own:
+
+    require 'clean_test/given_when_then'
+
+    class MyTest < Test::Unit::TestCase
+      include Clean::Test::GivenWhenThen
+    end
+
+To use TestThat on its own:
+
+    require 'clean_test/test_that'
+
+    class MyTest < Test::Unit::TestCase
+      include Clean::Test::TestThat
+    end

data/Rakefile

@@ -0,0 +1,29 @@
+require 'bundler'
+gem 'rdoc' # I need to use the installed RDoc gem, not what comes with the system
+require 'rake/clean'
+require 'rake/testtask'
+require 'rdoc/task'
+
+include Rake::DSL
+
+Bundler::GemHelper.install_tasks
+
+desc 'run tests'
+Rake::TestTask.new do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.ruby_opts << "-rrubygems"
+  t.test_files = FileList['test/bootstrap.rb','test/test_*.rb']
+end
+
+desc 'build rdoc'
+RDoc::Task.new do |rd|
+  rd.main = "README.rdoc"
+  rd.generator = 'hanna'
+  rd.rdoc_files.include("README.rdoc","lib/**/*.rb","bin/**/*")
+  rd.title = 'Test::Unit::Given - make your unit tests clear'
+  rd.markup = "tomdoc"
+end
+CLOBBER << 'coverage'
+
+task :default => :test

data/clean_test.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "clean_test/version"
+
+Gem::Specification.new do |s|
+  s.name        = "clean_test"
+  s.version     = Clean::Test::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["David Copeland"]
+  s.email       = ["davetron5000@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Clean up your Test::Unit tests}
+  s.description = %q{You can easily make your plain Ruby Test::Unit test cases clean and clear with Given/When/Then, placeholder values, and textual descriptions without resorting to metaprogramming or complex frameworks.  Use as much or as little as you like}
+
+  s.rubyforge_project = "clean_test"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.add_dependency("faker")
+  s.add_development_dependency("rdoc")
+  s.add_development_dependency("rake")
+  s.add_development_dependency("simplecov")
+end