chefspec-ohai 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 11e687172fecfd2d53cc1ef2673016f514ec63d9
-  data.tar.gz: 98a404207ad5fd570eef99d05a0d00d574d38ff5
+  metadata.gz: dc24aef40b78fd3ccb6d3d0d56d9a8bc4fee80f6
+  data.tar.gz: c78deb2e5878b3607fdb82f5cf38992a9053f364
 SHA512:
-  metadata.gz: 745621819bab095aff4f0ba16901530cf50aac836b74fb2055af4105dc6eb0bb5f9eb5e0656cc1b79e2f0e59f8799c9a77e01deb702c0eecf20a8a1c0e743d5a
-  data.tar.gz: 9c9ee91f577b6f7d25477a905d2797b83de2a028c838bba3c4da457ed64fc3e828037a203d33b46623b32accdad250190595218e12dafcdbfa73227aabde8e1a
+  metadata.gz: 57c1d88dc767c76a638a042c7e18e495a720937f0b134164d07b26ca5c55e2c06c7a158d8fcd197a001a1d64f242e4f6c605190db0df455c515caa1b04efe1eb
+  data.tar.gz: 9f3d6ce35c6dcac9e3763a281dce0ab1ef4a871a0c470b7e490ec039a61ec337ce345b215477125d357b4cd397df9d114921964431b7ffe66e148a3cd1f9a011

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Franklin Webber
+Copyright (c) 2018 Franklin Webber
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -38,7 +38,21 @@ Or install it yourself as:
 
 ## Usage
 
-First you will want to load the helpers within `spec/spec_helper.rb` file:
+Define your plugin within your cookbook in `cookbook/files/httpd_modules.rb`:
+
+```ruby
+Ohai.plugin(:Apache) do
+  provides 'apache/modules'
+
+  collect_data(:default) do
+    apache Mash.new
+    modules_cmd = shell_out('apachectl -t -D DUMP_MODULES')
+    apache[:modules] = modules_cmd.stdout
+  end
+end
+```
+
+First, you will want to load the helpers within `spec/spec_helper.rb` file:
 
 ```ruby
 require 'chefspec'            # Auto-generated with cookbook
@@ -53,7 +67,7 @@ plugin tests within the cookbook. I have chosen to create the directory
 
 I often choose to name the specification after the name of the file that stores
 the Ohai plugin. I were testing an Ohai plugin stored in `files/default/httpd_modules.rb`
-I would create a specifiation named `spec/unit/plugins/httpd_modules_spec.rb`.
+I would create a specification named `spec/unit/plugins/httpd_modules_spec.rb`.
 The most important thing is that the file ends with `_spec.rb` so that RSpec
 will automatically find this file and load it appropriately.
 
@@ -65,15 +79,6 @@ This gem provides an alias of RSpec's `describe` named `describe_ohai_plugin`
 which loads some additional helper methods to assist you with expressing your
 examples and the expectations within your examples.
 
-You must specify a let helper, named `:plugin_file`, which is a relative path
-within the cookbook to the file that contains the Ohai plugin.
-
-When creating this gem there are two examples that I thought that you would
-want to assert when testing your Ohai plugin:
-
-* I expect the Ohai plugin to provide particular attributes
-* I expect the Ohai plugin, when run, to set those attributes
-
 Here is a sample specification file that asserts that an Ohai plugin provides
 particular attributes and those attributes, when run (and stubbing the environment),
 are set properly.
@@ -82,28 +87,83 @@ are set properly.
 require 'spec_helper'
 
 describe_ohai_plugin :Apache do
-  let(:plugin_file) { "files/default/httpd_modules.rb" }
+  let(:plugin_file) { 'files/default/httpd_modules.rb' }
 
-  context "default collect data" do
+  context 'default collect data' do
     it "provides 'apache/modules'" do
-      expect(plugin).to provides_attribute("apache/modules")
+      expect(plugin).to provide_attribute('apache/modules')
     end
 
     it "correctly captures output" do
-      stub_plugin_shell_out('apachectl -t -D DUMP_MODULES','OUTPUT')
-      expect(plugin_attribute('apache/modules')).to eq("OUTPUT")
+      allow(plugin).to receive(:shell_out).with('apachectl -t -D DUMP_MODULES') { double(stderror: 0, stdout: 'unit tests do not like to run on systems') }
+      expect(plugin_attribute('apache/modules')).to eq('unit tests do not like to run on systems')
     end
   end
 end
 ```
 
-Here is the plugin that is being tested with that above specification:
+Run the tests within the cookbook directory:
+
+```
+$ rspec
+..
+Finished in 0.04775 seconds (files took 3.38 seconds to load)
+2 examples, 0 failures
+```
+
+## Testing other than the `collect_data :default`
+
+A plugin may collect data on different platforms. For example the following plugin:
+
+```ruby
+Ohai.plugin(:NonDefaultCollectData) do
+  provides 'application/version'
+
+  collect_data(:linux) do
+    application Mash.new
+    application[:version] = '3.0.0'
+  end
+
+  collect_data(:windows) do
+    application Mash.new
+    application[:version] = '9.0.0'
+  end
+end
+```
+
+You write tests for each platform:
+
+```ruby
+context 'linux data collection' do
+  let(:platform) { 'linux' }
+
+  it 'the attribute is correctly set' do
+    expect(plugin_attribute(attribute_name)).to eq '3.0.0'
+  end
+end
+
+context 'windows data collection' do
+  let(:platform) { 'windows' }
+
+  it 'the attribute is correctly set' do
+    expect(plugin_attribute(attribute_name)).to eq '9.0.0'
+  end
+end
+```
+
+## Ohai plugins written as Cookbook Templates
+
+Ohai plugins that are templates and not cookbook files require a little more setup. As templates require the presence of template variables or the node object that are passed to the temple you will need to define another helper in your specification `template_variables`.
+
+The following plugin defined in a template `templates/httpd_modules.rb.erb`:
 
 ```ruby
 Ohai.plugin(:Apache) do
   provides 'apache/modules'
 
   collect_data(:default) do
+    puts "<%= @template_variable %>"
+    puts "<%= node['attribute'] %>"
     apache Mash.new
     modules_cmd = shell_out('apachectl -t -D DUMP_MODULES')
     apache[:modules] = modules_cmd.stdout
@@ -111,6 +171,104 @@ Ohai.plugin(:Apache) do
 end
 ```
 
+Using a template for a plugin requires that you provide the template variables to
+populate.
+
+
+```ruby
+require 'spec_helper'
+
+describe_ohai_plugin :Apache do
+  let(:plugin_file) { 'templates/apache_modules.rb.erb' }
+
+  let(:template_variables) do
+    { template_variable: 'Free Me!', node: { 'attribute' => 'something' } }
+  end
+
+  context 'default collect data' do
+    it "provides 'apache/modules'" do
+      expect(plugin).to provide_attribute('apache/modules')
+      # OR
+      expect(plugin).to provides_attribute('apache/modules')
+    end
+
+    it 'correctly captures output' do
+      allow(plugin).to receive(:shell_out).with('apachectl -t -D DUMP_MODULES') { double(stderror: 0, stdout: 'unit tests do not like to run on systems') }
+      expect(plugin_attribute('apache/modules')).to eq('unit tests do not like to run on systems')
+    end
+  end
+end
+```
+
+## Testing a plugin with a dependency on another plugin
+
+A plugin may have a dependency on another plugin. A plugin may be defined as:
+
+```ruby
+Ohai.plugin(:FirstNetwork) do
+  provides 'first_network/ipv4', 'first_network/interface'
+
+  depends 'other_plugin'
+
+  collect_data(:default) do
+    first_network Mash.new
+
+    name, data = network['interfaces'].first
+    first_network[:interface] = name
+    first_network[:ipv4] = data['addresses'].first.first
+  end
+end
+```
+
+Within the test you can write expectations that the the plugin has a dependency on the plugin. When it comes to creating the test data, that requires stubbing the plugin calls to the dependent content.
+
+```ruby
+
+describe_ohai_plugin :FirstNetwork do
+  let(:plugin_file) { 'files/first_network.rb' }
+
+  it 'provides the first network address' do
+    expect(plugin).to provide_attribute('first_network/ipv4')
+  end
+
+  it 'provides the first network interface' do
+    expect(plugin).to provide_attribute('first_network/interface')
+  end
+
+  it 'depends on another plugin' do
+    expect(plugin).to depend_on_attribute('network')
+  end
+
+  context 'default data collection' do
+    before do
+      allow(plugin).to receive(:network).and_return(network_data)
+    end
+
+    let(:network_data) do
+      {
+        'interfaces' => {
+          'lo' => {
+            'state' => 'unknown',
+            'addresses' => {
+              '127.0.0.1' => {
+                'family' => 'inet'
+              }
+            }
+          }
+        }
+      }
+    end
+
+    it 'the first network interface is correctly set' do
+      expect(plugin_attribute('first_network/interface')).to eq('lo')
+    end
+
+    it 'the first network address is correctly set' do
+      expect(plugin_attribute('first_network/ipv4')).to eq('127.0.0.1')
+    end
+  end
+```
+
 ## Development
 
 This gem only provides a subset of the features that are possible to specify when

data/chefspec-ohai.gemspec

@@ -23,4 +23,7 @@ This gem provides additional helpers to RSpec to be used in conjunction with Che
 
   spec.add_development_dependency "bundler", "~> 1.9"
   spec.add_development_dependency "rake", "~> 10.0"
+
+  spec.add_dependency "chefspec", "> 5.0.0"
+  spec.add_dependency "ohai", "> 14.0.0"
 end

data/lib/chefspec/ohai.rb

@@ -20,7 +20,7 @@ shared_context 'Ohai Plugins', type: :ohai_plugin do
   # for use within the specifications.
   let(:plugin) do
     ohai_plugin_class = Ohai.plugin(subject) {}
-    ohai_plugin_class.new(plugin_data)
+    ohai_plugin_class.new(plugin_data, Ohai::Log)
   end
 
   # When an Ohai plugin is created there is a Hash of data that must be provided.
@@ -29,7 +29,87 @@ shared_context 'Ohai Plugins', type: :ohai_plugin do
   let(:plugin_data) { Hash.new }
 
   # Loads the plugin source from the specified plugin_file helper
-  let(:plugin_source) { File.read(plugin_file) }
+  let(:plugin_source) do
+    source = File.read(plugin_file)
+    if plugin_file.start_with?('templates')
+      ERB.new(source).result(plugin_template_binding)
+    else
+      source
+    end
+  end
+
+  # This helper is required to be defined by any Ohai plugin that is defined
+  # as a template. This hash of values will used to create the instance variables
+  # and define the conents of the node object which are used when generating the
+  # resulting template.
+  let(:template_variables) do
+    raise %(
+When you define a plugin_source based on a template a hash of template variables needs to be provided.
+
+Example:
+    let(:template_variables) do
+      { name: 'value_inserted_into_plugin', node: { 'ipaddress' : '127.0.0.1' } }
+    end
+ )
+  end
+
+  # Return a binding created with the hash of values defined in the template_variables
+  # helper.
+  let(:plugin_template_binding) do
+    PluginBinding.new(template_variables).expose_binding!
+  end
+
+
+  # To provide a space to instance variables that will be used by any Ohai
+  # plugins that use ERB templating to insert content.
+  class PluginBinding
+
+    # Create a new object that will define instance variables out of the hash's
+    # key-value pairs. This will create a safe place to define instance variables
+    # within a binding that can used when rendering the content of the ERB.
+    def initialize(template_variables)
+      Hash(template_variables).each do |key,value|
+        instance_variable_set("@#{key}",value)
+      end
+    end
+
+    # Within a template you can use `node[:attribute]`. This method provides
+    # support for that by creating this method that maps to the @node instance
+    # variable. This means that if you want to define a Ohai plugin that uses
+    # the node object and test it, then you are required to provide the values
+    # to make that work for the test.
+    #
+    # NOTE: A consideration here would be to use Fauxhai instead of requiring a
+    #       user to provide each attribute. This would get time consumsing to
+    #       create tests if the Ohai plugin used a lot of node attributes.
+    def node
+      if @node.nil?
+        raise NoNodeDataProvidedToTemplatePlugin
+      end
+      @node
+    end
+
+    # This exposes the private #binding method to allow it to be used as the specified
+    # binding when parsing ERB template.
+    def expose_binding!
+      binding
+    end
+
+    class NoNodeDataProvidedToTemplatePlugin < StandardError
+
+      def message
+        "The Ohai plugin attempted to retrieve an attribute from the `node` object. However, no node attributes were defined in the template_variables helper.
+Add a template_variables helper within your ohai plugin specification and include a `node` key that returns the data you need to satisfy the requirements of your plugin.
+
+Example:
+    let(:template_variables) do
+      { node: { 'ipaddress' => '127.0.0.1' } }
+    end"
+      end
+    end
+
+  end
+
   # Determine the plugin_path from the specified plugin_file
   let(:plugin_path) { File.dirname(plugin_file) }
   # This helper defines the path to the plugin file. This must be specified
@@ -45,9 +125,12 @@ Example:
  )
   end
 
+
+  let(:platform) { 'default' }
+
   # A Loader requires a controller. This controller may need to be overriden so
   # it is provided as a helper.
-  let(:plugin_controller) { double('plugin_controller') }
+  let(:plugin_controller) { Ohai::System.new }
   # The plugin_loader will evaluate the source of the plugin with the controller
   let(:plugin_loader) { Ohai::Loader.new(plugin_controller) }
 
@@ -61,6 +144,9 @@ Example:
     ps = plugin_source
     pp = plugin_path
     plugin_loader.instance_eval { load_v7_plugin_class(ps,pp) }
+    if platform != 'default'
+      allow(plugin).to receive(:collect_os).and_return(platform)
+    end
   end
 
   after :each do
@@ -89,16 +175,45 @@ Example:
   # does provide the correct body of attributes. The Ohai plugin class returns
   # an array of attributes that it provides through `#provides_attrs` which
   # is evaluated to ensure that the expected value is within that list.
-  RSpec::Matchers.define :provides_attribute do |expected|
+
+  # @see https://relishapp.com/rspec/rspec-expectations/v/2-4/docs/custom-matchers/define-matcher
+  RSpec::Matchers.define :provide_attribute do |expected|
     match do |plugin|
       expect(plugin.class.provides_attrs).to include(expected)
     end
+
+    failure_message do |actual|
+      "Expected the plugin to provide '#{expected}'. Plugin's defined attributes: #{plugin.class.provides_attrs.map { |p| "'#{p}'" }.join(', ')}"
+    end
+
+    failure_message_when_negated do |actual|
+      "Expected the plugin to NOT provide '#{expected}'. Plugin's defined attributes: #{plugin.class.provides_attrs.map { |p| "'#{p}'" }.join(', ')}"
+    end
   end
 
-  # Provides a simplier way to stub out the shell_out that is probably going on
-  # within the Ohai plugin.
-  def stub_plugin_shell_out(command,result)
-    allow(plugin).to receive(:shell_out).with(command) { double(stdout: result) }
+  # Provide support for the plural provides_attribute so that the authors
+  # of the specification can choose what they think makes the most sense
+  alias_method :provides_attribute, :provide_attribute
+
+
+  # This provides a new matcher when wanting to make assertions that the plugin
+  # has the correct dependencies. The Ohai plugin returns an array of dependencies
+  # that it provides through `#dependencies` which is evaluated to ensure that
+  # the expected value is within that list.
+
+  # @see https://relishapp.com/rspec/rspec-expectations/v/2-4/docs/custom-matchers/define-matcher
+  RSpec::Matchers.define :depend_on_attribute do |expected|
+    match do |plugin|
+      expect(plugin.dependencies).to include(expected)
+    end
+
+    failure_message do |actual|
+      "Expected the plugin to depend on '#{expected}'. Plugin's dependencies: #{plugin.dependencies.map { |d| "'#{d}'" }.join(', ')}"
+    end
+
+    failure_message_when_negated do |actual|
+      "Expected the plugin to NOT depend on '#{expected}'. Plugin's dependencies: #{plugin.dependencies.map { |d| "'#{d}'" }.join(', ')}"
+    end
   end
 
   # To make the process of verifying the attributes a little more streamlined
@@ -112,14 +227,63 @@ Example:
   # that must be traversed to get to the value desired. That is done here and
   # then returned.
   def plugin_attribute(attribute)
-    plugin.run
+    begin
+      plugin.run
+    rescue Exception => e
+      raise PluginFailedToRunError.new(plugin.name,plugin_file,e)
+    end
 
     components = attribute.split('/')
     top_level_mash_name = components.first
     attributes = components[1..-1]
 
     top_level_mash = plugin.send(top_level_mash_name)
-    attributes.inject(top_level_mash) { |mash,child| mash[child] }
+
+    if top_level_mash.nil? && !attributes.empty?
+      raise PluginAttributeUndefinedError.new(attribute,{})
+    end
+
+    attributes.inject(top_level_mash) do |mash,child|
+      begin
+        mash[child]
+      rescue Exception => e
+        raise PluginAttributeUndefinedError.new(attribute, { top_level_mash_name => top_level_mash })
+      end
+    end
+  end
+
+  class PluginFailedToRunError < RuntimeError
+    def initialize(plugin_name,plugin_path,exception)
+      @plugin_name = plugin_name
+      @plugin_path = plugin_path
+      @exception = exception
+
+      # Fix the backtrace path from the fixtures directory to the plugin file
+      exception.backtrace.unshift exception.backtrace.shift.gsub('spec/fixtures',plugin_path)
+    end
+
+    attr_reader :plugin_name, :plugin_path, :exception
+
+    def message
+      "Plugin #{plugin_name} #{plugin_path} failed:\n#{exception.message}"
+    end
+  end
+
+  class PluginAttributeUndefinedError < RuntimeError
+    def initialize(desired_attribute,plugin_attribute_data)
+      @desired_attribute = desired_attribute
+      @plugin_attribute_data = plugin_attribute_data
+
+    end
+
+    attr_reader :desired_attribute, :plugin_attribute_data
+
+    def message
+      "Plugin does not define attribute path '#{desired_attribute}'. Does the definition or test have a misspelling? Does the plugin properly initialize the entire attribute path?
+
+Plugin Attribute Data:
+#{plugin_attribute_data.to_yaml}\n---"
+    end
   end
 
 end

data/lib/chefspec/ohai/version.rb

@@ -1,5 +1,5 @@
 module Chefspec
   module Ohai
-    VERSION = "0.1.1"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chefspec-ohai
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Franklin Webber
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-07 00:00:00.000000000 Z
+date: 2018-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: chefspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+- !ruby/object:Gem::Dependency
+  name: ohai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 14.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 14.0.0
 description: |-
   Ohai plugins often go untested within the cookbooks that we create.
   When an Ohai plugin fails it is often a trial-and-error process that requires us to redeploy it.
@@ -49,6 +77,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rspec"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt