nutrasuite 0.2.1 → 0.2.2

data/lib/nutrasuite/contexts.rb

@@ -1,5 +1,25 @@
+# Public: Namespace module for all Nutrasuite functionality.
 module Nutrasuite
+  # Public: ContextHelpers contains all of the Nutrasuite Context methods. This
+  # will be included in Test::Unit::TestCase by default.
   module ContextHelpers
+
+    # Public: These methods will each define a context and push it onto the
+    # context stack for the duration of the passed in block.
+    #
+    # Signature
+    #   <article> "name of the context"
+    #
+    # Examples
+    #
+    #   a "User with a bad hair day" do
+    #     ...tests...
+    #   end
+    #
+    #   the "SingletonObject" do
+    #     ...tests...
+    #   end
+    #
     ["a", "an", "and", "that", "the"].each do |article|
       eval <<-HERE
         def #{article}(name, &block)
@@ -9,7 +29,21 @@ module Nutrasuite
       HERE
     end
 
-    # Code to be run before the context
+    # Public: use before to declare steps that need to be run before every test
+    # in a context.
+    def before(&block)
+      if Context.current_context?
+        Context.current_context.setups << block
+      else
+        warn "Not in a context"
+      end
+    end
+
+    # Deprecated: As much as I'd like to use setup and teardown, they screw up
+    # at times with ActiveSupport test cases. Better to use before and after.
+    #
+    # This method will be removed by 0.3.0. Please adjust your tests
+    # accordingly.
     def setup(&block)
       if Context.current_context?
         Context.current_context.setups << block
@@ -18,7 +52,21 @@ module Nutrasuite
       end
     end
 
-    # Code to be run when the context is finished
+    # Public: use after to declare steps that need to be run after every test in
+    # a context.
+    def after(&block)
+      if Context.current_context?
+        Context.current_context.teardowns << block
+      else
+        warn "Not in a context"
+      end
+    end
+
+    # Deprecated: As mich as I'd like to use setup and teardown, they screw up
+    # at times with ActiveSupport test cases. Better to use before and after.
+    #
+    # This method will be removed by 0.3.0. Please adjust your tests
+    # accordingly.
     def teardown(&block)
       if Context.current_context?
         Context.current_context.teardowns << block
@@ -27,16 +75,50 @@ module Nutrasuite
       end
     end
 
-    # Defines an actual test based on the given context
+    # Public: defines a test to be executed. Will run any setup blocks on the
+    # context stack before execution, then execute the specified test, then will
+    # run any teardown blocks on the context stack after the test has executed.
+    #
+    # name - The name of the test, used for human-readable test identification.
+    # &block - the body of the test, can use any and all assertions that would
+    #          otherwise be available to a MiniTest test.
+    #
+    # Examples
+    #
+    #   it "tests that true is truthy" do
+    #     assert true
+    #   end
+    #
     def it(name, &block)
       build_test(name, &block)
     end
 
-    # Defines a test based on the given context that will be skipped for now
+    # Public: defines a test method that should be skipped. Context
+    # setup/teardown will still be executed, but the actual test method will
+    # show up as a MiniTest skip with a description of "not yet implemented."
+    #
+    # This method exists to make it easy to switch a test between a pending and
+    # an active state: just switch the method name from "it" to "it eventually."
+    #
+    # name - The name of the test, used for human-readable test identification.
+    # &block - the body of the test. Doesn't have to be functional ruby as the
+    #          block will be skipped in this method.
+    #
+    # Examples
+    #
+    #   it_eventually "has some really smart logic" do
+    #     assert self.has_smart_logic?
+    #   end
+    #
     def it_eventually(name, &block)
       build_test("eventually #{name}", :skip => true, &block)
     end
 
+    # Internal: This method actually builds out the test method that MiniTest
+    # knows how to execute. It's responsible for running the current list of
+    # setups and teardowns and relies on 'define_method' to set up a test method
+    # that MiniTest can parse and execute.
+    #
     def build_test(name, options = {}, &block)
       test_name = Context.build_test_name(name)
 
@@ -61,16 +143,35 @@ module Nutrasuite
       end
     end
 
+    # Internal: warn simply outputs a warning message for the user if they
+    # appear to be using Nutrasuite incorrectly.
+    # 
     def warn(message)
       puts " * Warning: #{message}"
     end
 
   end
 
+  # Internal: The Context class represents each context that can go on the
+  # context stack. Each context is responsible for tracking its specific
+  # information (mostly its name and its setup and teardown methods). Contexts
+  # should only be created using one of the article methods in ContextHelpers.
   class Context
 
+    # Internal: Get the name, setup methods, and teardown methods for this
+    # Context.
     attr_reader :name, :setups, :teardowns
 
+    # Internal: Create a new Context object.
+    #
+    # name   - The name of the context, which will be prepended to any nested
+    #          contexts/tests in the final test name
+    # &block - The block that defines the contents of the context; should
+    #          consist of:
+    #          - test definitions
+    #          - sub-context definitions
+    #          - setup and teardown declarations
+    #
     def initialize(name, &block)
       @name = name
       @block = block
@@ -79,10 +180,25 @@ module Nutrasuite
       @teardowns = []
     end
 
+    # Internal: build runs the block that defines the context's contents, thus
+    # setting up any nested contexts and tests.
+    #
     def build
       @block.call
     end
 
+    # Internal: builds a test name based on the current state of the context
+    # stack.
+    #
+    # Examples
+    #
+    #   # Assuming the context stack looks like "a user","that is an admin":
+    #   Context.build_test_name("has admin privileges") 
+    #   #=> "test a user that is an admin has admin privileges"
+    #
+    # Returns a string name for a method that will automatically be executed by
+    # MiniTest.
+    #
     def self.build_test_name(name="")
       full_name = "test "
       context_stack.each do |context|
@@ -91,6 +207,13 @@ module Nutrasuite
       full_name << name
     end
 
+    # Internal: pushes a new context onto the stack, builds that context out,
+    # and then removes it from the stack.
+    #
+    # This method should be the only means by which contexts get built, as it
+    # ensures that the context is removed from the context stack when it's done
+    # building itself.
+    #
     def self.push(name, &block)
       context = Context.new(name, &block)
       context_stack.push(context)
@@ -100,21 +223,36 @@ module Nutrasuite
       context_stack.pop
     end
 
+    # Internal: get the context stack, or initialize it to an empty list if
+    # necessary.
+    #
+    # Returns: an Array representing the context stack.
     def self.context_stack
       @context_stack ||= []
     end
 
+    # Internal: get the current context.
+    #
+    # Returns: the context currently at the top of the stack, or nil if there
+    # are no contexts in the stack at the moment.
     def self.current_context
       context_stack.last
     end
 
+    # Internal: determine whether there is currently a context active.
+    #
+    # Returns: true if there is at least one context on the stack, false
+    # otherwise.
     def self.current_context?
       !context_stack.empty?
     end
   end
 end
 
-# backwards compatibility with some slightly older versions of minitest
+# In slightly older versions of MiniTest the TestCase#current method is not
+# defined, but Nutrasuite definitely needs it in order to be useful. This bit of
+# monkey-patching hackery ensures that this method is present even if you're
+# using an older version of the library.
 unless defined? MiniTest::Unit::TestCase.current
   class MiniTest::Unit::TestCase
     def initialize name

data/lib/nutrasuite/version.rb

@@ -1,3 +1,3 @@
 module Nutrasuite
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/test/unit/contexts_test.rb

@@ -15,11 +15,11 @@ class ContextsTest < Test::Unit::TestCase
   end
 
   a "Context" do
-    setup do
+    before do
       @a = 5
     end
 
-    it "runs setups before tests" do
+    it "runs befores before tests" do
       assert_equal @a, 5
     end
 
@@ -28,33 +28,44 @@ class ContextsTest < Test::Unit::TestCase
     end
 
     that "has a nested Context" do
-      setup do
+      before do
         @b = 10
       end
 
-      it "runs both setups" do
+      it "runs both befores" do
         assert_equal @a, 5
         assert_equal @b, 10
       end
     end
 
-    that "has a nested Context with multiple setups" do
-      setup do
+    that "has a nested Context with multiple befores" do
+      before do
         @b = 6
       end
 
-      setup do
+      before do
         @c = 7
         @b = @b + 1
       end
 
-      it "runs all setups in order" do
+      it "runs all befores in order" do
         assert_equal @b, 7
         assert_equal @b, @c
       end
     end
   end
 
+  a "Second context" do
+    before do
+      @b = true
+    end
+
+    it "isn't affected by befores from other contexts" do
+      assert @b
+      assert @a.nil?
+    end
+  end
+
   the "'the' context" do
     it "works" do
       assert true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nutrasuite
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-26 00:00:00.000000000 Z
+date: 2012-03-04 00:00:00.000000000 Z
 dependencies: []
 description: Nutrasuite is a low-calorie syntax sweetener for minitest
 email: