octofacts is a tool that enables Puppet developers to provide complete sets of facts for rspec-puppet tests. It works by saving facts from actual hosts as fixture files, and then presenting a straightforward programming interface to select and manipulate those facts within tests. Using nearly real-life facts is a good way to ensure that rspec-puppet tests match production as closely as possible.
octofacts is actively used in production at GitHub. This project is actively maintained by the original authors and the rest of the Site Reliability Engineering team at GitHub.
The octofacts project is distributed with two components:
-
The
octofactsgem is called within your rspec-puppet tests, to provide facts from indexed fact fixture files in your repository. This allows you to replace a hard-codedlet (:facts) { ... }hash with more realistic facts from recent production runs. -
The
octofacts-updatergem is a utility to maintain the indexed fact fixture files consumed byoctofacts. It pulls facts from a data source (e.g. PuppetDB, fact caches, or SSH), indexes your facts, and can even create Pull Requests on GitHub to update those fixture files for you.
To use octofacts in your rspec-puppet tests, those tests must be executed with Ruby 2.1 or higher and rspec-puppet 2.3.2 or higher, and executed on a Unix-like operating system. We explicitly test octofacts with Linux and Mac OS, but do not test under Windows.
To use octofacts-updater, we recommend using PuppetDB, and if you do you'll need version 3.0 or higher.
Once you complete the initial setup and generate fact fixtures, you'll be able to use code like this in your rspec-puppet tests:
describe "modulename::classname" do
let(:node) { "fake-node.example.net" }
let(:facts) { Octofacts.from_index(app: "my_app_name", role: "my_role_name") }
it "should do whatever..."
...
end
end
The basics:
- Quick start tutorial - covers installation and basic configuration <-- New users start here
- Automating fixture generation with octofacts-updater
More advanced usage:
- Plugin reference for octofacts-updater
- Using manipulators to adjust fact values
- Additional examples of octofacts capabilities
Please see our contributing document if you would like to participate!
We would specifically appreciate contributions in these areas:
- Any updates you make to make octofacts compatible with your site -- there are probably assumptions made from the original environment that need to be more flexible.
- Any interesting anonymization plugins you write for octofacts-updater -- you may place these in the contrib/plugins directory.
If you have a problem or suggestion, please open an issue in this repository, and we will do our best to help. Please note that this project adheres to its Code of Conduct.
octofacts is licensed under the MIT license.