assert-view 0.2.0 → 0.3.0

data/Gemfile.lock

@@ -1,16 +1,16 @@
 PATH
   remote: .
   specs:
-    assert-view (0.2.0)
+    assert-view (0.3.0)
+      ansi (~> 1.3)
       undies (~> 1.1)
 
 GEM
   remote: http://rubygems.org/
   specs:
     ansi (1.3.0)
-    assert (0.4.0)
-      ansi (~> 1.3)
-      assert-view
+    assert (0.6.0)
+      assert-view (~> 0.3)
     rake (0.9.2)
     undies (1.1.0)
 

data/README.rdoc

@@ -13,30 +13,34 @@ Assert::View is a dependency of Assert and will be automatically installed when
 
     $ gem install assert   # will install assert-view as a dependency
 
-=== Usage: override the default view with a different one
-Assert uses the Assert::View::Terminal view outputting to $stdout by default (https://github.com/teaminsight/assert/blob/master/lib/assert/setup/view.rb).  To override and use a different view, add the following to your ~/.assert/options.rb file:
+=== Usage: the default view
+Assert uses the Assert::View::DefaultView outputting to $stdout by default (https://github.com/teaminsight/assert/blob/master/lib/assert/setup/view.rb).  To override and use a different view, add the following to your ~/.assert/options.rb file:
 
     require 'assert/view/different_view'
 
     # Override the Assert view option and assign it an instance of the different view
-    # Setup the view passing it the suite accessor and the IO to output on
-    Assert.options.view Assert::View::DifferentView.new(Assert.suite, $stdout)
+    # Setup the view passing it the IO to output on
+    Assert.options.view Assert::View::DifferentView.new($stdout)
 
 === Usage: define your own and override
 So, ~/.assert/option.rb is just a ruby script that is required when Assert is setting itself up.  You can use this file to define your own custom view class and then override the Assert view option like above:
 
-    # Say you wanted to tweak and make a better Terminal view
-    require 'assert/view/terminal'
+    # Say you wanted to tweak and make a better DefaultView
+    require 'assert/view/default_view'
     module Assert::View
-      class MyBetterTerminal < Terminal
+      class MyBetterDefaultView < DefaultView
         # override stuff and tweak it to your heart's content
       end
     end
 
     # Now override the view option to use your better terminal
-    Assert.options.view Assert::View::MyBetterTerminal.new(Assert.suite, $stdout)
+    Assert.options.view Assert::View::MyBetterDefaultView.new($stdout)
 
 
+You could also define an entirely new view from scratch.  Look at the existing views and read the below about writing your own view for more details.  Once you have written your new view, tell Assert to use it with the following:
+
+    Assert.options.view Assert::View::MyNewView.new($stdout)
+
 
 == Assert::View::Base class
 All views need to subclass the Assert::View::Base class.  This class implements a few core things that assert expects of its view classes:
@@ -49,46 +53,67 @@ All view initializers take two things at minimum:
 === 'suite' reader
 The suite reader provides access to the suite of tests that will be or has been run.  Use this reader to do things like count tests or test results, iterate through the tests and display detailed results, etc.  This reader provides all the model data needed to render your view.
 
-=== 'render' method
-The render method, as its name suggests, handles the overall rendering of the view.  All render methods should take the following arguments:
-* *args*: not used right now - more for view backwards compatibility in the event that args are needed
-* *runner*: runner is a block that is given to the render method by the Assert::Runner class in use.  The view class should call this block (@runner.call@) when the view is ready to run the suite of tests.  Output any view headers before calling; output any view summary/footer after calling.
-
-Here is an excerpt from the Terminal class to illustrate how a render method could be implemented:
-
-    def render(*args, &runner)
-      self.io_puts(:load_stmt)            # header info
-
-      if count(:tests) > 0
-        runner.call if runner             # run the test suite
-        self.io_puts(:detailed_results)   # show any result details
-      end
-
-      self.io_puts(:results_stmt)         # summary/footer info
-    end
-
-=== 'handle_runtime_result' method
-This method is called as the suite of tests is being run.  It is a callback for when a new test result is added to a tests results and the result is passed as the only argument.  Use of the method is totally optional.  The Terminal view uses it to output result abbreviations while the test suite is running.
+=== The Renderer
+The view renderer provided by the base class uses Undies (https://github.com/kelredd/undies) to define and render view templates.  It mixes in a 'render' method to the base view that handles creating an Undies::Template from the view's template definition and wiring up the necessary runner callbacks.
 
 === Utilities
 The base class provides a few utilities for rendering views:
-* *io_puts*: puts output to the output IO.  Pass it the string to output or a symbol of a method that returns the string to output.
-* *io_print*: same as io_puts, printing the string instead of putting it
 * *run_time*: get a string with the suite's run time in seconds
 * *run_seed*: get the seed value used to run the test suite in random order
 * *count*: helper method for counting stuff on the suite, ie: 'count(:tests)'
+* etc...  Check out the base class for all utilities (https://github.com/teaminsight/assert-view/blob/master/lib/assert/view/base.rb)
+
+== Anatomy of a View
+
+So I'd like to explain some key things about Assert views in detail to understand the anatomy of a view and hopefully help you understand how to create your own.
+
+First off, all views need to subclass Assert::View::Base.  The base class provides a bunch of utilities and handles all the necessary callbacks between a view and Assert's Runner class.  In addition, the base class provides all methods necessary to render the view's template.  Beyond that, a View has 3 main parts:
+=== 1 - Options
+The base class mixes in Assert's options helpers so that options can be specified on any view.  The base class provides a few key options:
+* *default_passed_abbrev*:  ["."] the default abbreviation for passed results
+* *default_failed_abbrev*:  ["F"] ditto for failed results
+* *default_errored_abbrev*: ["E"] ditto for errored results
+* *default_skipped_abbrev*: ["S"] ditto for skipped results
+* *default_ignored_abbrev*: ["I"] ditto for ignored results
+
+In addition, the DefaultView specifies a few options of its own:
+* *styled*:         [true]           whether or not to show ansi-styled results, set to false for plain text output
+* *passed_styles*   [:green]         the styles to markup passing result output with
+* *failed_styles*   [:red, :bold]    ditto for failed result output
+* *errored_styles*  [:yellow, :bold] ditto for errored result output
+* *skipped_styles*  [:cyan]          ditto for skipped result output
+* *ignored_styles*  [:magenta]       ditto for ignored result output
+
+Use options in your views to override the base default options or to define your own for tweaking behavior and customization.
+
+=== 2 - Template / Template Helpers
+The base class provides a 'template' class method.  Use this method to define an Undies template to render your view.  Check out Undies for details on how to create an Undies template.  Templates are given two locals to work with:
+* *view*: this local refers to the instance of the view class.  Use it to get data or run logic.
+* *runner*: this is a block used to callback to Assert's runner and run the tests.  Pass this local to the base 'run_tests' method to control when (in rendering your view) the tests are run.  Optionally pass a block to 'run_tests' that will be called each time a new result is generated by the running tests.  Use this to render live runtime result data.
+
+If you need to define some helper methods for your view to use, add them to a helpers module (check out: https://github.com/teaminsight/assert-view/blob/master/lib/assert/view/helpers/ansi.rb).  Use the 'helper' class method on your view to mix those helpers in to the view's template scope and then you can use them in your template.
+
+=== 3 - Data/Logic
+Assert views encourage defining your view's data handling and business logic seperately from your view's template.  Define instance methods on your view to access, process, and handle data and business logic.  Your template can then access them using its 'view' local.
+
+
+
+== Other Views
+TODO: put in notes about other views available for use...
 
 
 
 == Roll Your Own!
 
-Assert::View is designed to be extended and customized.  Using the Base class, create your own view classes and use them as you see fit.  If you feel like sharing, fork the repo, and add a pull requests.  Bonus points to anyone who rips off other testing frameworks views (LeftRight, Turn, etc.)
+Check out the different views available here.  Use a few and customize them using their options.  If you find you can't see your test results how you like or you prefer the way an alternate testing library outputs test results, create your own view class.  Write it inline in your '.assert/options.rb' file and hook it up with Assert's view option.  If you want to share it with everyone, fork this gem, add it in, and submit a pull request.
+
+TODO: put in guidlines for submitting new views...
 
 
 
 == License
 
-Copyright (c) 2011 Kelly D. Redding and Team Insight
+Copyright (c) 2011 Kelly Redding and Team Insight
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/assert-view.gemspec

@@ -20,5 +20,6 @@ Gem::Specification.new do |s|
   s.add_development_dependency("bundler")
   s.add_development_dependency("assert")
 
+  s.add_dependency("ansi", ["~> 1.3"])
   s.add_dependency("undies", ["~> 1.1"])
 end

data/lib/assert/view/base.rb

@@ -1,9 +1,53 @@
 require 'assert/options'
-require 'assert/view/renderer'
 
 module Assert::View
 
+  # this module is mixed in to the Assert::View::Base class
+  # it use Undies to define and render view templates
+  module Renderer
+    require 'undies'
+
+    def self.included(receiver)
+      receiver.send(:extend, ClassMethods)
+    end
+
+    # define rendering template class to use for rendering
+    # need to overwrite the '_' and '__' meths to add trailing newlines
+    # b/c streaming output doesn't add any whitespace
+    class Template < ::Undies::Template
+
+      def _(data="", nl=true);  super(data.to_s + (nl ? "\n" : "")); end
+      def __(data="", nl=true); super(data.to_s + (nl ? "\n" : "")); end
+
+    end
+
+    # this method is required by assert and is called by the test runner
+    # use Undies to render the template
+    # using the view's template file
+    # streaming to the view's output io
+    # passing in the view itself and any runner_callback as locals
+    def render(*args, &runner_callback)
+      locals = {
+        :view => self,
+        :runner => runner_callback
+      }
+      Template.new(self.output_io, locals, &self.class.template)
+    end
+
+    module ClassMethods
+
+      # make any helper methods available to the template
+      def helper(helper_klass)
+        Template.send(:include, helper_klass)
+      end
+
+    end
+
+  end
+
+
   class Base
+
     include Assert::Options
     options do
       default_passed_abbrev   '.'
@@ -19,6 +63,15 @@ module Assert::View
     # * 'self.helper': used to provide helper mixins to the renderer template
     include Renderer
 
+    # set the view's template by passing a block, get by calling w/ no args
+    def self.template(&block)
+      if block
+        @template = block
+      else
+        @template
+      end
+    end
+
     attr_accessor :suite, :output_io, :runtime_result_callback
 
     def initialize(output_io, suite=Assert.suite)
@@ -30,17 +83,6 @@ module Assert::View
       self
     end
 
-
-
-    # TODO: look for files in the .assert dir
-    # TODO: allow option for specifying which template to use
-    # TODO: test
-    def template_file
-      File.expand_path("./templates/#{self.options.template}.rb", File.dirname(__FILE__))
-    end
-
-
-
     # called by the view template
     # store off any result_callback
     # call the runner callback to actually run the tests
@@ -68,7 +110,6 @@ module Assert::View
       self.suite.count(type)
     end
 
-    # TODO: test
     def tests?
       self.count(:tests) > 0
     end

data/lib/assert/view/{terminal.rb → default_view.rb}

@@ -1,10 +1,63 @@
 require 'assert/result'
 require 'assert/options'
+
 require 'assert/view/base'
+require 'assert/view/helpers/ansi'
 
 module Assert::View
 
-  class Terminal < Base
+  # This is the default view used by assert.  It renders ansi test output
+  # designed for terminal viewing.
+
+  class DefaultView < Base
+    helper Helpers::AnsiStyles
+    options do
+      styled          true
+      passed_styles   :green
+      failed_styles   :red, :bold
+      errored_styles  :yellow, :bold
+      skipped_styles  :cyan
+      ignored_styles  :magenta
+    end
+
+    template do
+      __
+      __ view.loaded_tests_statement
+
+      if view.tests?
+
+        __ view.running_tests_statement
+
+        view.run_tests(runner) do |each_result|
+          result_sym = each_result.to_sym
+          result_abbrev = view.options.send("#{result_sym}_abbrev")
+          __ ansi_styled_msg(result_abbrev, result_ansi_styles(result_sym)), false
+        end
+        __ "\n"  # add a newline after streamed runner output
+
+        view.detailed_results do |result, output|
+          __ ansi_styled_msg(result.to_s, result_ansi_styles(result))
+
+          if !output.empty?
+            __ view.result_output_start_msg
+            __ output, false
+            __ view.result_output_end_msg
+          end
+
+          __
+        end
+
+      end
+
+      # build a summary sentence w/ styled results breakdown
+      styled_results_breakdown_statement = view.results_breakdown_statement do |msg, result_type|
+        ansi_styled_msg(msg, result_ansi_styles(result_type))
+      end
+
+      __ [ view.result_count_statement, ": ", styled_results_breakdown_statement ].join('')
+      __
+      __ view.run_time_statement
+    end
 
     def loaded_tests_statement
       "Loaded suite (#{view.count(:tests)} test#{'s' if view.count(:tests) != 1})"
@@ -16,7 +69,7 @@ module Assert::View
 
     # show test details in reverse order from how they were collected (FILO)
     def detailed_tests
-      @detailed_tests ||= self.suite.ordered_tests.reverse
+      self.suite.ordered_tests.reverse
     end
 
     # get all the results that have details to show

data/lib/assert/view/version.rb

@@ -1,5 +1,5 @@
 module Assert; end
 
 module Assert::View
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/assert-view.rb

@@ -0,0 +1 @@
+require 'assert/view'

data/test/base_test.rb

@@ -14,7 +14,8 @@ module Assert::View
     subject{ @view }
 
     should have_accessors :suite, :output_io, :runtime_result_callback
-    should have_instance_methods :template_file, :run_tests, :handle_runtime_result
+    should have_class_method :template
+    should have_instance_methods :run_tests, :handle_runtime_result
     should have_instance_methods :run_time, :runner_seed, :count, :tests?, :all_passed?
     should have_instance_methods :ocurring_result_types, :result_summary_msg
     should have_instance_methods :all_passed_result_summary_msg, :to_sentence

data/test/{terminal_test.rb → default_view_test.rb}

@@ -1,6 +1,6 @@
 require 'assert'
 
-require 'assert/view/terminal'
+require 'assert/view/default_view'
 require 'stringio'
 
 module Assert::View
@@ -8,7 +8,7 @@ module Assert::View
   class TerminalTest < Assert::Context
     desc "the terminal view"
     setup do
-      @view = Assert::View::Terminal.new(Assert::Suite.new, StringIO.new("", "w+"))
+      @view = Assert::View::DefaultView.new(Assert::Suite.new, StringIO.new("", "w+"))
     end
     subject{ @view }
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: assert-view
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 19
   prerelease: 
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Kelly Redding
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-08 00:00:00 Z
+date: 2011-09-09 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   type: :development
@@ -49,6 +49,21 @@ dependencies:
   type: :runtime
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 1
+        - 3
+        version: "1.3"
+  version_requirements: *id003
+  name: ansi
+- !ruby/object:Gem::Dependency 
+  type: :runtime
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -58,7 +73,7 @@ dependencies:
         - 1
         - 1
         version: "1.1"
-  version_requirements: *id003
+  version_requirements: *id004
   name: undies
 description: A collection of views for use in the Assert testing framework
 email: 
@@ -76,17 +91,16 @@ files:
 - README.rdoc
 - Rakefile
 - assert-view.gemspec
+- lib/assert-view.rb
 - lib/assert/view.rb
 - lib/assert/view/base.rb
+- lib/assert/view/default_view.rb
 - lib/assert/view/helpers/ansi.rb
-- lib/assert/view/renderer.rb
-- lib/assert/view/templates/assert.ansi.rb
-- lib/assert/view/terminal.rb
 - lib/assert/view/version.rb
 - test/base_test.rb
+- test/default_view_test.rb
 - test/helper.rb
 - test/irb.rb
-- test/terminal_test.rb
 homepage: http://github.com/teaminsight/assert-view
 licenses: []
 
@@ -122,6 +136,6 @@ specification_version: 3
 summary: A collection of views for use in the Assert testing framework
 test_files: 
 - test/base_test.rb
+- test/default_view_test.rb
 - test/helper.rb
 - test/irb.rb
-- test/terminal_test.rb

data/lib/assert/view/renderer.rb

@@ -1,45 +0,0 @@
-require 'undies'
-
-module Assert::View
-
-  # this module is mixed in to the Assert::View::Base class
-  # it use Undies to define and render view templates
-  module Renderer
-
-    def self.included(receiver)
-      receiver.send(:extend, ClassMethods)
-    end
-
-    # define rendering template class to use for rendering
-    # need to overwrite the '_' and '__' meths to add trailing newlines
-    # b/c streaming output doesn't add any whitespace
-    class Template < ::Undies::Template
-
-      def _(data="", nl=true);  super(data.to_s + (nl ? "\n" : "")); end
-      def __(data="", nl=true); super(data.to_s + (nl ? "\n" : "")); end
-
-    end
-
-    # this method is required by assert and is called by the test runner
-    # use Undies to render the template
-    # using the view's template file
-    # streaming to the view's output io
-    # passing in the view itself and any runner_callback as locals
-    def render(*args, &runner_callback)
-      Template.new(File.expand_path(self.template_file), self.output_io, {
-        :view => self,
-        :runner => runner_callback
-      })
-    end
-
-    module ClassMethods
-
-      # make any helper methods available to the template
-      def helper(helper_klass)
-        Template.send(:include, helper_klass)
-      end
-
-    end
-
-  end
-end

data/lib/assert/view/templates/assert.ansi.rb

@@ -1,36 +0,0 @@
-__
-__ view.loaded_tests_statement
-
-if view.tests?
-
-  __ view.running_tests_statement
-
-  view.run_tests(runner) do |each_result|
-    result_sym = each_result.to_sym
-    result_abbrev = view.options.send("#{result_sym}_abbrev")
-    __ ansi_styled_msg(result_abbrev, result_ansi_styles(result_sym)), false
-  end
-  __ "\n"  # add a newline after streamed runner output
-
-  view.detailed_results do |result, output|
-    __ ansi_styled_msg(result.to_s, result_ansi_styles(result))
-
-    if !output.empty?
-      __ view.result_output_start_msg
-      __ output, false
-      __ view.result_output_end_msg
-    end
-
-    __
-  end
-
-end
-
-# build a summary sentence w/ styled results breakdown
-styled_results_breakdown_statement = view.results_breakdown_statement do |msg, result_type|
-  ansi_styled_msg(msg, result_ansi_styles(result_type))
-end
-
-__ [ view.result_count_statement, ": ", styled_results_breakdown_statement ].join('')
-__
-__ view.run_time_statement