kintama 0.1.1

data/README.md

@@ -0,0 +1,247 @@
+Hello
+=====
+
+This is a tool for testing code. Or maybe it's a tool for exploring ways to test code. See below.
+
+Huh? Really? Another one?
+====
+
+... Yeah, I know. To be honest, I'm not 100% sure why I'm doing this. Here are some guesses though:
+
+My testing tools of choice, at the moment, are [Test::Unit][] with [shoulda][] to provide nested contexts, but not really it's macros.
+
+I'm not a huge fan of [Test::Unit][]. Whenever I've tried to extend its behaviour I've hit snags, and found its code difficult to understand (particularly as lots of it don't seem to be regularly used - I'm looking at you, [TkRunner][] and friends). I also don't really love [RSpec][], but I think that's just a personal preference (I learned with test/unit, and I didn't want to relearn all of the matcher stuff).
+
+I like [shoulda][], because like [RSpec][], it lets me nest groups of tests in ways that help remove duplication in setups. However, [I don't have a lot of confidence that shoulda is going to stick around in its current, useful-for-stuff-that-isnt-RSpec form](http://robots.thoughtbot.com/post/701863189/shoulda-rails3-and-beyond).
+
+I like some of the more verbose output that [Cucumber][] and [RSpec][] produce, but as I mentioned above, I don't care for [RSpec][]'s matcher-heavy syntax. It's basically impossible to reproduce that output on anything that uses [Test::Unit][] as a base (see [MonkeySpecDoc][] for an example, which fails because it cannot support any more than one level of nesting)
+
+I also like things like [`before(:all)`][before_all], and [`fast_context`][fast_context], but don't like having to hack around inside [Test::Unit][] to implement them (I already have with [`test_startup`][test_startup]; it works but who knows for how long).
+
+
+Related work
+------------
+
+In the spirit of [shoulda][], a small library called [context][] adds the simple nested context structures to [Test::Unit][], but that's the problem - we can't build anything on top of [Test::Unit][].
+
+Ditto for [contest][].
+
+Probably the closest thing I've seen is [baretest][]. If you look around the code, some of the implementation details are quite similar to those that have evolved in this code (context-ish objects with parents). However, in many ways baretest is more complex, and the final API that it provides is quite foreign compared to [shoulda][].
+
+Another alternative test framework is [riot][], which claims to be fast, but also appears to constrain the way that tests are written by avoiding instance variables in setups, for example.
+
+[Testy][] is interesting - it looks like its output is YAML!. [Tryouts][] is thinking outside the box, using comment examples.
+
+[Zebra][] addresses the apparent duplication of the test name and the test body, but does it by introducing an [RSpec][]-esque method on every object. Wild. Also, it's an extension of [Test::Unit][], so that's strike two for me, personally.
+
+I have no idea what to make of [Shindo][].
+
+[Exemplor][]... oh my god why am I contributing to this mess.
+
+Erm.
+
+Exploring future testing
+------------------------
+
+I wanted to explore how easy it would be to reproduce a test framework with a modern, [shoulda][]/RSpec-esque syntax, but that was simple enough to be understandable when anyone needed to change it.
+
+I also wanted to be able to start exploring different ways of expressing test behaviour, outside of the classic `setup -> test -> teardown` cycle, but didn't feel that I could use test/unit as a basis for this kind of speculative work without entering a world of pain.
+
+Hence... _this_.
+
+
+Examples
+========
+
+These will all be very familiar to most people who are already users of [shoulda][]:
+
+    require 'kintama'
+
+    context "A thing" do
+      setup do
+        @thing = Thing.new
+      end
+      should "act like a thing" do
+        assert_equal "thingish", @thing.nature
+      end
+    end
+
+Simple, right? Note that we don't need an outer subclass of `Test::Unit::TestCase`; it's nice to lose that noise, but otherwise so far so same-old-same-old. That's kind-of the point. Anyway, here's what you get when you run this:
+
+    A thing
+      should act like a thing: F
+
+    1 tests, 1 failures
+
+    1) A thing should act like a thing:
+      uninitialized constant Thing (at ./examples/simple.rb:6)
+
+Firstly, it's formatted nicely. There are no cryptic line numbers or `bind` references like [shoulda][]. If you run it from a terminal, you'll get colour output too. That's nice.
+
+
+Aliases
+----
+
+There are a bunch of aliases you can use in various ways. If you don't like:
+
+    context "A thing" do
+
+you could also write:
+
+    describe Thing do # like RSpec! ...
+    given "a thing" do # ...
+    testcase "a thing" do # ...
+
+It's trivial to define other aliases that might make your tests more readable. Similarly for defining the tests themselves, instead of:
+
+    should "act like a thing" do
+
+you might prefer:
+
+    it "should act like a thing" do # ...
+    test "acts like a thing" do # ...
+
+Sometimes just having that flexibility makes all the difference.
+
+
+Setup, teardown, nested contexts
+--------------
+
+These work as you'd expect based on shoulda or RSpec:
+
+    given "a Thing" do
+      setup do
+        @thing = Thing.new
+      end
+
+      it "should be happy" do
+        assert @thing.happy?
+      end
+
+      context "that is prodded" do
+        setup do
+          @thing.prod!
+        end
+
+        should "not be happy" do
+          assert_false @thing.happy?
+        end
+      end
+
+      teardown do
+        @thing.cleanup_or_something
+      end
+    end
+
+You can also add (several) global `setup` and `teardown` blocks, which will be run before (or after) every test. For example:
+
+    Kintama.setup do
+      @app = ThingApp.new
+    end
+
+    given "a request" do
+      it "should work" do
+        assert_equal 200, @app.response.status
+      end
+    end
+
+
+Helpers
+-------
+
+If you want to make methods available in your tests, you have a few options. You can define them inline:
+
+    context "my face" do
+      should "be awesome" do
+        assert_equal "awesome", create_face.status
+      end
+
+      helpers do
+        def create_face
+          Face.new(:name => "james", :eyes => "blue", :something => "something else")
+        end
+      end
+    end
+
+Ideally I would've liked to make this syntatically similar to defining a private method in a class, but for various reasons that was not possible. Anyway, your other options are including a module:
+
+    module FaceHelper
+      def create_face
+        # etc ...
+      end
+    end
+
+    context "my face" do
+      include FaceHelper
+      should "be awesome" do
+        assert_equal "awesome", create_face.status
+      end
+    end
+
+Or, if you're going to use the method in all your tests, you can add the module globally:
+
+    Kintama.add FaceHelper
+
+or just define the method globally:
+
+    Kintama.add do
+      def create_face
+        # etc ...
+      end
+    end
+
+### Aside: what happens if you do define a method in the context?
+
+It becomes available within context (and subcontext) definitions. Here's an example:
+
+    context "blah" do
+      def generate_tests_for(thing)
+        it "should work with #{thing}" do
+          assert thing.works
+        end
+      end
+
+      [Monkey.new, Tiger.new].each do |t|
+        generate_tests_for(t)
+      end
+    end
+
+This is a bit like defining a 'class method' in a `TestCase` and then being able to call it to generate contexts or tests within that `TestCase`. It's not that tricky once you get used to it.
+
+
+And now, the more experimental stuff
+====================================
+
+Wouldn't it be nice to be able to introspect a failed test without having to re-run it? Well, you can. Lets imagine this test:
+
+    context "A thing" do
+      setup do
+        @thing = Thing.new
+      end
+      should "act like a thing" do
+        assert_equal "thingish", @thing.nature
+      end
+    end
+
+Well... TO BE CONTINUED.
+
+
+
+[Test::Unit]: http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/
+[TkRunner]: http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit/UI/Tk/TestRunner.html
+[RSpec]: http://rspec.info
+[Cucumber]: http://cukes.info
+[MonkeySpecDoc]: http://jgre.org/2008/09/03/monkeyspecdoc/
+[before_all]: http://rspec.info/documentation/
+[fast_context]: https://github.com/lifo/fast_context
+[test_startup]: https://github.com/freerange/test_startup
+[shoulda]: https://github.com/thoughtbot/shoulda
+[baretest]: https://github.com/apeiros/baretest
+[riot]: https://github.com/thumblemonks/riot
+[context]: https://github.com/jm/context
+[contest]: https://github.com/citrusbyte/contest
+[Testy]: https://github.com/ahoward/testy
+[Tryouts]: https://github.com/delano/tryouts
+[Zebra]: https://github.com/jamesgolick/zebra
+[Shindo]: https://github.com/geemus/shindo
+[Exemplor]: https://github.com/quackingduck/exemplor

data/lib/kintama.rb

@@ -0,0 +1,100 @@
+module Kintama
+  autoload :Runnable, 'kintama/runnable'
+  autoload :Context, 'kintama/context'
+  autoload :Test, 'kintama/test'
+  autoload :TestFailure, 'kintama/test'
+  autoload :Runner, 'kintama/runner'
+  autoload :Assertions, 'kintama/assertions'
+
+  class << self
+    def reset
+      @default_context = Class.new(Runnable)
+      @default_context.send(:include, Kintama::Context)
+    end
+
+    def default_context
+      reset unless @default_context
+      @default_context
+    end
+
+    # Create a new context. Aliases are 'testcase' and 'describe'
+    def context(name, parent=default_context, &block)
+      default_context.context(name, parent, &block)
+    end
+    alias_method :testcase, :context
+    alias_method :describe, :context
+
+    # Create a new context starting with "given "
+    def given(name, parent=default_context, &block)
+      default_context.given(name, parent, &block)
+    end
+
+    # Add a setup which will run at the start of every test.
+    def setup(&block)
+      default_context.setup(&block)
+    end
+
+    # Add a teardown which will be run at the end of every test.
+    def teardown(&block)
+      default_context.teardown(&block)
+    end
+
+    # Makes behaviour available within tests:
+    #
+    #   module SomeModule
+    #     def blah
+    #     end
+    #   end
+    #   Kintama.include SomeModule
+    #
+    # Any methods will then be available within setup, teardown or tests.
+    def include(mod)
+      default_context.send(:include, mod)
+    end
+
+    # Make new testing behaviour available for the definition of tests.
+    # Methods included in this way are available during the definition of tests.
+    def extend(mod)
+      default_context.extend(mod)
+    end
+
+    # Adds the hook to automatically run all known tests using #run when
+    # ruby exits; this is most useful when running a test file from the command
+    # line or from within an editor
+    def add_exit_hook
+      return if @__added_exit_hook
+      at_exit { exit(Runner.default.run ? 0 : 1) }
+      @__added_exit_hook = true
+    end
+
+    # Tries to determine whether or not this is a sensible situation to automatically
+    # run all tests when ruby exits. At the moment, this is true when either:
+    # - the test was run via rake
+    # - the test file was run as the top-level ruby script
+    #
+    # This method will always return false if the environment variable
+    # KINTAMA_EXPLICITLY_DONT_RUN is not nil.
+    def should_run_on_exit?
+      return false if ENV["KINTAMA_EXPLICITLY_DONT_RUN"]
+      return test_file_was_run? || run_via_rake?
+    end
+
+    private
+
+    def test_file_was_run?
+      caller.last.split(":").first == $0
+    end
+
+    def run_via_rake?
+      caller.find { |line| File.basename(line.split(":").first) == "rake_test_loader.rb" } != nil
+    end
+  end
+end
+
+[:context, :given, :describe, :testcase].each do |method|
+  unless self.respond_to?(method)
+    eval %|def #{method}(*args, &block); Kintama.#{method}(*args, &block); end|
+  end
+end
+
+Kintama.add_exit_hook if Kintama.should_run_on_exit?

data/lib/kintama/assertions.rb

@@ -0,0 +1,38 @@
+module Kintama
+  module Assertions
+    def assert(expression, message="failed")
+      raise Kintama::TestFailure, message unless expression
+    end
+
+    def flunk
+      assert false, "flunked."
+    end
+
+    def assert_equal(expected, actual, message="Expected #{expected.inspect} but got #{actual.inspect}")
+      assert actual == expected, message
+    end
+
+    def assert_not_equal(expected, actual, message)
+      assert actual != expected, message
+    end
+
+    def assert_nil(object, message="#{object.inspect} was not nil")
+      assert_equal nil, object, message
+    end
+
+    def assert_not_nil(object, message="should not be nil")
+      assert_not_equal nil, object, message
+    end
+
+    def assert_kind_of(klass, thing, message="should be a kind of #{klass}")
+      assert thing.is_a?(klass)
+    end
+
+    def assert_raises(message="should raise an exception", &block)
+      yield
+      raise Kintama::TestFailure, message
+    rescue
+      # do nothing, we expected this, but now no TestFailure was raised.
+    end
+  end
+end

data/lib/kintama/context.rb

@@ -0,0 +1,187 @@
+module Kintama
+  module Context
+    def setup # noop
+    end
+
+    def teardown # noop
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      # Create a new context. If this is called within a context, a new subcontext
+      # will be created. Aliases are 'testcase' and 'describe'
+      def context(name, parent=self, &block)
+        c = Class.new(parent)
+        c.send(:include, Kintama::Context)
+        c.name = name.to_s
+        c.class_eval(&block)
+        c
+      end
+      alias_method :testcase, :context
+      alias_method :describe, :context
+
+      # Create a new context starting with "given "
+      def given(name, parent=self, &block)
+        context("given " + name, parent, &block)
+      end
+
+      def setup_blocks
+        @setup_blocks ||= []
+      end
+
+      def teardown_blocks
+        @teardown_blocks ||= []
+      end
+
+      # Define the setup for this context.
+      # It will also be run for any subcontexts, before their own setup blocks
+      def setup(&block)
+        self.setup_blocks << block
+
+        # redefine setup for the current set of blocks
+        blocks = self.setup_blocks
+        define_method(:setup) do
+          super
+          blocks.each { |b| instance_eval(&b) }
+        end
+      end
+
+      # Define the teardown for this context.
+      # It will also be run for any subcontexts, after their own teardown blocks
+      def teardown(&block)
+        self.teardown_blocks << block
+
+        # redefine teardown for the current set of blocks
+        blocks = self.teardown_blocks
+        define_method(:teardown) do
+          blocks.each { |b| instance_eval(&b) }
+          super
+        end
+      end
+
+      # Defines the subject of any matcher-based tests.
+      def subject(&block)
+        define_method(:subject, &block)
+      end
+
+      # Define a test to run in this context.
+      def test(name, &block)
+        c = Class.new(self)
+        c.send(:include, Kintama::Test)
+        c.name = name
+        c.block = block if block_given?
+      end
+
+      # Define a test to run in this context. The test name will start with "should "
+      # You can either supply a name and block, or a matcher. In the latter case, a test
+      # will be generated using that matcher.
+      def should(name_or_matcher, &block)
+        if name_or_matcher.respond_to?(:matches?)
+          test("should " + name_or_matcher.description) do
+            assert name_or_matcher.matches?(subject), name_or_matcher.failure_message
+          end
+        else
+          test("should " + name_or_matcher, &block)
+        end
+      end
+
+      # Define a test using a negated matcher, e.g.
+      #
+      #   subject { 'a' }
+      #   should_not equal('b')
+      #
+      def should_not(matcher)
+        test("should not " + matcher.description) do
+          assert !matcher.matches?(subject), matcher.negative_failure_message
+        end
+      end
+
+      # Define a test to run in this context. The test name will start with "it "
+      def it(name, &block)
+        test("it " + name, &block)
+      end
+
+      def inherited(child)
+        children << child
+      end
+
+      def children
+        @children ||= []
+      end
+
+      def tests
+        children.select { |c| c.is_a_test? }.sort_by { |t| t.name }
+      end
+
+      def subcontexts
+        children.select { |c| c.is_a_context? }.sort_by { |s| s.name }
+      end
+
+      # Returns true if this context has no known failed tests.
+      def passed?
+        failures.empty?
+      end
+
+      # Returns an array of tests in this and all subcontexts which failed in
+      # the previous run
+      def failures
+        ran_tests.select { |t| !t.passed? } + subcontexts.map { |s| s.failures }.flatten
+      end
+
+      def pending
+        tests.select { |t| t.pending? } + subcontexts.map { |s| s.pending }.flatten
+      end
+
+      def [](name)
+        subcontexts.find { |s| s.name == name } || tests.find { |t| t.name == name }
+      end
+
+      def method_missing(name, *args, &block)
+        if self[de_methodize(name)]
+          self[de_methodize(name)]
+        else
+          begin
+            super
+          rescue NameError, NoMethodError => e
+            if parent
+              parent.send(name, *args, &block)
+            else
+              raise e
+            end
+          end
+        end
+      end
+
+      def respond_to?(name)
+        self[name] ||
+        super ||
+        (parent ? parent.respond_to?(name) : false)
+      end
+
+      # Runs all tests in this context and any subcontexts.
+      # Returns true if all tests passed; otherwise false
+      def run(runner=nil)
+        @ran_tests = []
+        runner.context_started(self) if runner
+        tests.each { |t| instance = t.new; instance.run(runner); ran_tests << instance }
+        subcontexts.each { |s| s.run(runner) }
+        runner.context_finished(self) if runner
+        passed?
+      end
+
+      private
+
+      def de_methodize(name)
+        name.to_s.gsub("_", " ")
+      end
+
+      def ran_tests
+        @ran_tests || []
+      end
+    end
+  end
+end