rspec-illustrate 0.1.1 → 0.1.2

data/README.md

@@ -1,4 +1,4 @@
-# Rspec::Illustrate [![Gem Version](https://badge.fury.io/rb/rspec-illustrate.svg)](http://badge.fury.io/rb/rspec-illustrate)
+# RSpec::Illustrate [![Gem Version](https://badge.fury.io/rb/rspec-illustrate.svg)](http://badge.fury.io/rb/rspec-illustrate)
 
 
 This is an RSpec extension gem that allows you to define illustrative objects in

data/Rakefile

@@ -7,4 +7,8 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.rspec_opts = "--format RSpec::Formatters::IllustratedDocumentationFormatter"
 end
 
+RSpec::Core::RakeTask.new(:html) do |t|
+  t.rspec_opts = "--format RSpec::Formatters::IllustratedHtmlFormatter --out ./doc/specs.html"
+end
+
 task :default => :spec

data/lib/rspec/formatters/illustrated_documentation_formatter.rb

@@ -24,6 +24,12 @@ module RSpec
   module Formatters
     include RSpec::Core::Formatters
 
+    # An extension to the {RSpec::Core::Formatters::DocumentationFormatter} that
+    # renders the illustrations after each example. A title/label for each
+    # illustration can be set by setting the label option (@see
+    # RSpec::Illustrate#illustrate).
+    # If you want to filter the illustrations based on the test result, you can use
+    # the options show_when_passed, show_when_failed and show_when_pending.
     class IllustratedDocumentationFormatter < DocumentationFormatter
       include RSpec::Formatters
 
@@ -37,21 +43,35 @@ module RSpec
         super(output)
       end
 
+      # @see RSpec::Core::Formatters::DocumentationFormatter#example_passed
       def example_passed(passed)
         super(passed)
         write_illustrations(passed, :show_when_passed, :illustration_passed)
       end
 
+      # @see RSpec::Core::Formatters::DocumentationFormatter#example_failed
       def example_failed(failure)
         super(failure)
         write_illustrations(failure, :show_when_failed, :illustration_failed)
       end
 
+      # @see RSpec::Core::Formatters::DocumentationFormatter#example_pending
       def example_pending(pending)
         super(pending)
         write_illustrations(pending, :show_when_pending, :illustration_pending)
       end
 
+      # @private
+      # Writes the filtered illustrations of an example to the output stream.
+      #
+      # @param notification [RSpec::Core::Notifications::ExampleNotification]
+      #                     The example notificiation that contains the
+      #                     illustrations.
+      # @param filter_key   [Symbol]
+      #                     The option that each illustration should have a truthy
+      #                     value of if they are to be written
+      # @param color_type   [Symbol]
+      #                     The symbol that corresponds to a configurable color
       def write_illustrations(notification, filter_key, color_type)
         illustrations = filter(illustrations_of(notification), filter_key)
         return if illustrations.empty?
@@ -59,14 +79,26 @@ module RSpec
         output.puts colored(indented(formatted(illustrations)), color_type)
       end
 
+      # @private
+      # @param text [String] The text to be colored
+      # @param color_type [Symbol]
+      # @return [String] The text wrapped in color codes.
       def colored(text, color_type)
         RSpec::Core::Formatters::ConsoleCodes.wrap(text, color_type)
       end
 
+      # @private
+      # @param text [String]
+      # @return [String] The text where each newline is properly indented.
       def indented(text)
         current_indentation << text.gsub(/\n/, "\n#{current_indentation}")
       end
 
+      # @private
+      # Convert the illustrations to a string using the configurable illustration
+      # formatter {RSpec::Configuration#illustration_formatter}.
+      # @param illustrations [Array<Hash>] The illustrations
+      # @return [String] a text concatenation of the illustrations
       def formatted(illustrations)
         formatter_proc = RSpec.configuration.illustration_formatter
 

data/lib/rspec/formatters/illustrated_html_formatter.rb

@@ -0,0 +1,97 @@
+RSpec::Support.require_rspec_core "formatters/html_formatter"
+require 'rspec/formatters/illustration_formatter.rb'
+
+RSpec.configure do |c|
+  c.add_setting(:illustration_html_formatter, :default =>
+                lambda {|illustration|
+                  html = "<dd>"
+
+                  if illustration.has_key?(:label) then
+                    html << "<span>#{illustration[:label].to_s}</span>"
+                  end
+
+                  content = illustration[:content]
+                  if content.respond_to?(:to_html) then
+                    html << content.to_html
+                  else
+                    html << "<pre>#{content.to_s}</pre>"
+                  end
+
+                  return html << "</dd>"
+                })
+end
+
+module RSpec
+  module Formatters
+    include RSpec::Core::Formatters
+
+    # An extension to the {RSpec::Core::Formatters::HtmlFormatter} that
+    # renders the illustrations after each example. A title/label for each
+    # illustration can be set by setting the label option (@see
+    # RSpec::Illustrate#illustrate).
+    # If you want to filter the illustrations based on the test result, you can use
+    # the options show_when_passed, show_when_failed and show_when_pending.
+    class IllustratedHtmlFormatter < HtmlFormatter
+      include RSpec::Formatters
+
+      # This registers the notifications this formatter supports, and tells
+      # us that this was written against the RSpec 3.x formatter API.
+      RSpec::Core::Formatters.register self, :example_passed,
+                                             :example_failed,
+                                             :example_pending
+
+      def initialize(output)
+        super(output)
+      end
+
+      # @see RSpec::Core::Formatters::HtmlFormatter#example_passed
+      def example_passed(passed)
+        super(passed)
+        write_illustrations(passed, :show_when_passed)
+      end
+
+      # @see RSpec::Core::Formatters::HtmlFormatter#example_failed
+      def example_failed(failure)
+        super(failure)
+        write_illustrations(failure, :show_when_failed)
+      end
+
+      # @see RSpec::Core::Formatters::HtmlFormatter#example_pending
+      def example_pending(pending)
+        super(pending)
+        write_illustrations(pending, :show_when_pending)
+      end
+
+      # @private
+      # Writes the filtered illustrations of an example to the output stream.
+      #
+      # @param notification [RSpec::Core::Notifications::ExampleNotification]
+      #                     The example notificiation that contains the
+      #                     illustrations.
+      # @param filter_key   [Symbol]
+      #                     The option that each illustration should have a truthy
+      #                     value of if they are to be written
+      def write_illustrations(notification, filter_key)
+        illustrations = filter(illustrations_of(notification), filter_key)
+        return if illustrations.empty?
+
+        output.puts formatted(illustrations)
+      end
+
+      # @private
+      # Convert the illustrations to a string using the configurable illustration
+      # html formatter {RSpec::Configuration#illustration_html_formatter}.
+      # @param illustrations [Array<Hash>] The illustrations
+      # @return [String] a html concatenation of the illustrations
+      def formatted(illustrations)
+        formatter_proc = RSpec.configuration.illustration_html_formatter
+
+        illustrations.collect{|illustration|
+          formatter_proc.call(illustration)
+        }.join("\n")
+      end
+
+    end
+  end
+end
+

data/lib/rspec/formatters/illustration_formatter.rb

@@ -2,12 +2,22 @@
 module RSpec
   module Formatters
 
+    # @private
+    # @param notification [RSpec::Core::Notifications::ExampleNotification]
+    #        The example notification to be formatted.
+    # @return [Array<Hash>] The list of illustrations in the example, where each
+    #         illustration is represented by a { Hash } containing its properties.
     def illustrations_of(notification)
-      notification.example.metadata[:illustrations]
+      notification.example.metadata[:illustrations] || []
     end
 
     module_function :illustrations_of
 
+    # @private
+    # @param illustrations [Array<Hash>] A list of illustrations ({ Hash })
+    # @param filter_key [Symbol] The property that each illustration must have.
+    # @return [Array<Hash>] The illustrations that have truthy property values for
+    #                       filter_key.
     def filter(illustrations, filter_key)
       illustrations.select{|illustration| illustration[filter_key]}
     end

data/lib/rspec/illustrate.rb

@@ -2,8 +2,15 @@ require 'rspec/illustrate/version'
 require 'rspec/core'
 
 module RSpec
+  # Extension module to RSpec that allows you to define illustrations in the
+  # examples that will be forwarded to the output formatter.
   module Illustrate
 
+    # Stores an object in the surrounding example's metadata, which can be used
+    # by the output formatter as an illustration for the example.
+    # @param content The object that will act as an illustration.
+    # @param args [Array<Hash, Symbol>] Additional options.
+    # @return The given illustration object.
     def illustrate(content, *args)
       illustration = { :content => content,
                        :show_when_passed  => true,

data/lib/rspec/illustrate/version.rb

@@ -1,5 +1,6 @@
-module Rspec
+module RSpec
   module Illustrate
-    VERSION = "0.1.1"
+    # The version used by gemspec
+    VERSION = "0.1.2"
   end
 end

data/rspec-illustrate.gemspec

@@ -5,7 +5,7 @@ require 'rspec/illustrate/version'
 
 Gem::Specification.new do |spec|
   spec.name          = "rspec-illustrate"
-  spec.version       = Rspec::Illustrate::VERSION
+  spec.version       = RSpec::Illustrate::VERSION
   spec.authors       = ["Erik Schlyter"]
   spec.email         = ["erik@erisc.se"]
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-illustrate
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-16 00:00:00.000000000 Z
+date: 2015-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-core
@@ -91,6 +91,7 @@ files:
 - Rakefile
 - bin/setup
 - lib/rspec/formatters/illustrated_documentation_formatter.rb
+- lib/rspec/formatters/illustrated_html_formatter.rb
 - lib/rspec/formatters/illustration_formatter.rb
 - lib/rspec/illustrate.rb
 - lib/rspec/illustrate/version.rb
@@ -116,7 +117,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 807417647878713660
+      hash: 2396350347062895824
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23