From d5ffc4d8dac1b17cd180cc00118c00e8c5bdfe01 Mon Sep 17 00:00:00 2001
From: Hailee Kenney <hailee@puppetlabs.com>
Date: Mon, 8 Sep 2014 15:39:31 -0700
Subject: [PATCH] (PDOC-2) Refactor tests for 4x function handler

Update the spec tests which cover the Puppet 4x function handler
to be more specific and cover different test cases. Prior to this commit,
they would simply check that the right objects had been added to the
Registry for one example. Now, they examine multiple examples and ensure that
the code objects not only exist but that the details about them are what we
would expect for each specific scenario.
---
 Gemfile                                       |   1 -
 .../yardoc/yard/examples/puppet4_function.rb  |   7 --
 .../unit/puppetx/yardoc/yard/handlers_spec.rb | 101 ++++++++++++++++--
 3 files changed, 90 insertions(+), 19 deletions(-)
 delete mode 100644 spec/unit/puppetx/yardoc/yard/examples/puppet4_function.rb

diff --git a/Gemfile b/Gemfile
index bd32072..5fcd95e 100644
--- a/Gemfile
+++ b/Gemfile
@@ -9,7 +9,6 @@ group :test do
   gem 'rspec'
   gem 'mocha'
   gem 'puppetlabs_spec_helper'
-  gem 'nokogiri'
   gem 'rspec-html-matchers'
 end
 
diff --git a/spec/unit/puppetx/yardoc/yard/examples/puppet4_function.rb b/spec/unit/puppetx/yardoc/yard/examples/puppet4_function.rb
deleted file mode 100644
index fc65f89..0000000
--- a/spec/unit/puppetx/yardoc/yard/examples/puppet4_function.rb
+++ /dev/null
@@ -1,7 +0,0 @@
-require 'puppet'
-
-Puppet::Functions.create_function(:puppet4_function) do
-  def puppet4_function(x,y)
-    x >= y ? x : y
-  end
-end
diff --git a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb
index adbbeb6..37098c2 100644
--- a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb
+++ b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb
@@ -2,6 +2,43 @@ require 'spec_helper'
 require 'puppetx/yardoc/yard/handlers'
 
 describe Puppetx::Yardoc::YARD::Handlers do
+
+  # TODO: Relocate/refactor helper methods
+  def parse_file(file, thisfile = __FILE__, log_level = log.level, ext = '.pp')
+    Registry.clear
+    path = File.join(File.dirname(thisfile), 'examples', file.to_s + ext)
+    YARD::Parser::SourceParser.parse(path, [], log_level)
+  end
+
+  def parse(string)
+    Registry.clear
+    YARD::Parser::SourceParser.parse_string(string)
+  end
+
+  RSpec::Matchers.define :document_a do |arguments|
+    match do |actual|
+      compare_values(actual).empty?
+    end
+
+    failure_message do |actual|
+      mismatches = compare_values(actual)
+      mismatches.collect do |key, value|
+        "Expected #{key} to be <#{value[1]}>, but got <#{value[0]}>."
+      end.join("\n")
+    end
+
+    def compare_values(actual)
+      mismatched_arguments = {}
+      expected.each do |key, value|
+        actual_value = actual.send(key)
+        if actual_value != value
+          mismatched_arguments[key] = [actual_value, value]
+        end
+      end
+      mismatched_arguments
+    end
+  end
+
   describe "DefinedTypeHanlder" do
     it "should add a defined type object in the Registry" do
       parse_file :defined_type, __FILE__, log.level, '.pp'
@@ -11,21 +48,63 @@ describe Puppetx::Yardoc::YARD::Handlers do
   end
 
   describe "FutureParserDispatchHandler" do
-    before(:each) {parse_file :puppet4_function, __FILE__, log.level, '.rb'}
-
-    it "should add a puppet namespace object to the Registry" do
-      namespace = Registry.at("FutureParserFunctions")
-      expect(namespace.type).to be(:puppetnamespace)
+    def the_method()
+      Registry.at("FutureParserFunctions#the_function")
     end
 
-    it "should add a future parser function object to the Registry" do
-      function = Registry.at("FutureParserFunctions#puppet4_function")
-      expect(function.type).to be(:method)
+    def the_namespace()
+      Registry.at("FutureParserFunctions")
     end
 
-    it "should add a method object to the Registry" do
-      method = Registry.at("#puppet4_function")
-      expect(method.type).to be(:method)
+    it "should parse single-line documentation strings before a given function" do
+      comment = "The summary"
+      parse <<-RUBY
+        # #{comment}
+        Puppet::Functions.create_function(:the_function) do
+        end
+      RUBY
+
+      expect(the_method).to document_a(:type => :method, :docstring => comment)
+      expect(the_namespace).to document_a(:type => :puppetnamespace)
+    end
+
+    it "should parse multi-line documentation strings before a given function" do
+      parse <<-RUBY
+        # The summary
+        #
+        # The longer description
+        Puppet::Functions.create_function(:the_function) do
+        end
+      RUBY
+
+      comment = "The summary\n\nThe longer description"
+      expect(the_method).to document_a(:type => :method, :docstring => comment)
+      expect(the_namespace).to document_a(:type => :puppetnamespace)
+    end
+
+    it "should not parse documentation before a function if it is followed by two new lines" do
+      parse <<-RUBY
+        # The summary
+        #
+        # The longer description
+
+
+        Puppet::Functions.create_function(:the_function) do
+        end
+      RUBY
+
+      expect(the_method).to document_a(:type => :method, :docstring => "")
+      expect(the_namespace).to document_a(:type => :puppetnamespace)
+    end
+
+    it "should not add anything to the Registry if incorrect ruby code is present" do
+      parse <<-RUBY
+        # The summary
+        Puppet::Functions.create_function(:the function do
+        end
+      RUBY
+
+      expect(Registry.all).to be_empty
     end
   end