docs: add tutorial for testing custom facts

[jeefberkey]

It would be helpful to have another tile on this page http://rspec-puppet.com/documentation/ for testing custom facts in modules.

[rodjek]

rspec-puppet itself doesn't support testing facts as they can be tested easily enough in normal rspec. I can write an example and throw it up on there though.

[jeefberkey]

There are a few paradigms that make it a little confusing, like how to mock Facter::Core::Execution or confine. Things like that wouldn't be clear to someone who was only experienced with using rspec-puppet, not regular rspec.

[waveclaw]

Having some authoritative documentation on how to test facts with rspec-puppet would be nice. Yes, technically facter is a different tool.

rspec-puppet does a wonderful job of enable testing of Puppet DSL for which I am thankful. But if the modules provide facts through custom Ruby code the module's author(s) should test these facts, too.

Learning from reading GitHub repositories and trial-and-error was very slow. I currently base a lot of ideas off of facts in Puppet Enterprise's standard library module.

I'm currently having to do awkward things I expect should be handled better. I am no "Rubyist" even if I have to write 10-100 lines of Ruby for every line of Puppet DSL. I use rspec_mock to stub out the Facter::Core::Execution calls. Sometimes I completely avoid confine in facts just to make test setup tractable. For complicated facts I build a utility module in the Facter::Util namespace and test that using regular rspec.

A documentation tile could answer some important questions.

Is adding a custom path to sets of fact spec tests preferred or expected? By convention I have put fact tests in the /spec/function directory. I have done this for many years now. At this point using /spec/function is a "Tribal Standard" at the places I have worked using Puppet.

How should testing exceptions be best handled in facts? Recall that using mocks requires either returning fake values during exceptions or setting allow_message_expectations_on_nil to true.

Is there a better way to reset facter between fact tests than the boilerplate bellow?

  before :each do
    Facter::Util::Loader.any_instance.stubs(:load_all)
    Facter.clear
    Facter.clear_messages
  end

Is is better to hard-code example data or to dynamically lookup example data inside the fact?

[realflash]

Please please yes. I have been thrown into Ruby and rpsec and puppet-rspec all at the same time by our adoption of Puppet, and have no idea where to start with testing my custom fact.