(PDOC-2) Add tests around face and HTML generation

Add tests to ensure that the face (puppet yardoc) works from end to
end. In other words, ensure that when given a module, puppet yardoc can
successfully evaluate the .pp and .rb files present in the module and
produce the expected HTML.

Gemfile

@@ -10,6 +10,7 @@ group :test do
   gem 'mocha'
   gem 'puppetlabs_spec_helper'
   gem 'nokogiri'
+  gem 'rspec-html-matchers'
 end
 
 group :development do

spec/unit/puppet/examples/test/lib/puppet/functions/4x_function.rb

@@ -0,0 +1,5 @@
+# function 4x
+#
+# This is a function which is used to test puppet strings
+Puppet::Functions.create_function(:function4x) do
+end

spec/unit/puppet/examples/test/lib/puppet/parser/functions/function3x.rb

@@ -0,0 +1,3 @@
+Puppet::Parser::Functions.newfunction(:function3x, :doc => "This is the
+function documentation for `function3x`") do |args|
+end

spec/unit/puppet/examples/test/manifests/init.pp

@@ -1,6 +1,16 @@
+# Class: test
+#
+#   This class exists to serve as fixture data for testing the puppet strings face
+#
+# @example
+#   class { "test": }
+#
+# @param package_name The name of the package
+# @param service_name The name of the service
 class test (
   $package_name = $test::params::package_name,
   $service_name = $test::params::service_name,
+
 ) inherits test::params {
 
   # validate parameters here
@@ -9,4 +19,9 @@ class test (
   class { 'test::config': } ~>
   class { 'test::service': } ->
   Class['test']
+
+  File {
+    owner => 'user',
+    path => 'some/file/path',
+  }
 }

spec/unit/puppet/face_spec.rb

@@ -1,5 +1,8 @@
 require 'spec_helper'
 require 'puppet/face/yardoc'
+require 'rspec-html-matchers'
+require 'tmpdir'
+require 'stringio'
 
 describe Puppet::Face do
 
@@ -27,6 +30,41 @@ describe Puppet::Face do
       YARD::CLI::Yardoc.expects(:run).with('--debug', 'some_file.rb')
       Puppet::Face[:yardoc, :current].yardoc('--debug', 'some_file.rb')
     end
+
+    describe "when generating HTML for documentation" do
+      it "should properly generate HTML for manifest comments" do
+
+        YARD::Logger.instance.io = StringIO.new
+
+        using_module('test') do |tmp|
+          Dir.chdir('test')
+
+          Puppet::Face[:yardoc, :current].yardoc
+
+          expect(read_html(tmp, 'test', 'test.html')).to have_tag('.docstring .discussion', :text => /This class/)
+        end
+      end
+
+      it "should properly generate HTML for 3x function comments" do
+        using_module('test') do |tmp|
+          Dir.chdir('test')
+
+          Puppet::Face[:yardoc, :current].yardoc
+
+          expect(read_html(tmp, 'test', 'ParserFunctions.html')).to have_tag('.docstring .discussion', :text => /documentation for `function3x`/)
+        end
+      end
+
+      it "should properly generate HTML for 4x function comments" do
+        using_module('test') do |tmp|
+          Dir.chdir('test')
+
+          Puppet::Face[:yardoc, :current].yardoc
+
+          expect(read_html(tmp, 'test', 'test.html')).to have_tag('.docstring .discussion', :text => /This class/)
+        end
+      end
+    end
   end
 
   describe "modules action" do
@@ -60,4 +98,23 @@ describe Puppet::Face do
       expect{Puppet::Face[:yardoc, :current].server}.to raise_error(RuntimeError, "This face requires Ruby 1.9 or greater.")
     end
   end
+
+  # Helper methods to handle file operations around generating and loading HTML
+  def using_module(modulename, &block)
+    Dir.mktmpdir do |tmp|
+      module_location = File.join(File.dirname(__FILE__), "examples", modulename)
+      FileUtils.cp_r(module_location, tmp)
+      old_dir = Dir.pwd
+      begin
+        Dir.chdir(tmp)
+        yield(tmp)
+      ensure
+        Dir.chdir(old_dir)
+      end
+    end
+  end
+
+  def read_html(dir, modulename, file)
+    File.read(File.join(dir, modulename, 'doc', file))
+  end
 end