|
1 | 1 | # rubygem-simp-spec-helpers |
| 2 | + |
2 | 3 | rspec-puppet helper methods for SIMP module testing |
| 4 | + |
| 5 | +[](http://www.apache.org/licenses/LICENSE-2.0.html) |
| 6 | +[](https://travis-ci.org/simp/rubygem-simp-spec-helpers) |
| 7 | +[](https://rubygems.org/gems/simp-spec-helpers) |
| 8 | +[](https://rubygems.org/gems/simp-spec-helpers) |
| 9 | + |
| 10 | +#### Table of Contents |
| 11 | + |
| 12 | +<!-- vim-markdown-toc GFM --> |
| 13 | + |
| 14 | +* [Overview](#overview) |
| 15 | + * [This gem is part of SIMP](#this-gem-is-part-of-simp) |
| 16 | + * [Features](#features) |
| 17 | +* [Setup](#setup) |
| 18 | + * [Gemfile](#gemfile) |
| 19 | + * [Fixtures](#fixtures) |
| 20 | +* [Usage](#usage) |
| 21 | + * [In a Unit Test](#in-a-unit-test) |
| 22 | + * [Environment Variables](#environment-variables) |
| 23 | +* [Reference](#reference) |
| 24 | +* [Limitations](#limitations) |
| 25 | + * [Some versions of bundler fail on FIPS-enabled Systems](#some-versions-of-bundler-fail-on-fips-enabled-systems) |
| 26 | +* [Development](#development) |
| 27 | + * [License](#license) |
| 28 | + * [History](#history) |
| 29 | + |
| 30 | +<!-- vim-markdown-toc --> |
| 31 | + |
| 32 | +## Overview |
| 33 | + |
| 34 | +The `simp-spec-helpers` gem provides common rspec tasks to support the SIMP unit testing process. |
| 35 | + |
| 36 | +### This gem is part of SIMP |
| 37 | + |
| 38 | +This gem is part of (the build tooling for) the [System Integrity Management Platform](https://github.com/NationalSecurityAgency/SIMP), a compliance-management framework built on [Puppet](https://puppetlabs.com/). |
| 39 | + |
| 40 | + |
| 41 | +### Features |
| 42 | + |
| 43 | +* Customizable RPM packaging based on a Puppet module's [`metadata.json`][metadata.json] |
| 44 | +* RPM signing |
| 45 | +* Rubygem packaging |
| 46 | + |
| 47 | +## Setup |
| 48 | + |
| 49 | +### .fixtures.yml |
| 50 | + |
| 51 | +You must include the compliance_markup module in your .fixtures.yml: |
| 52 | + |
| 53 | +``` yaml |
| 54 | +--- |
| 55 | +fixtures: |
| 56 | + repositories: |
| 57 | +... |
| 58 | + compliance_markup: https://github.com/simp/pupmod-simp-compliance_markup |
| 59 | +... |
| 60 | +``` |
| 61 | + |
| 62 | +### Gemfile |
| 63 | + |
| 64 | +The Gemfile for your puppet module should have the following included (with updated |
| 65 | +versions where necessary): |
| 66 | + |
| 67 | +``` ruby |
| 68 | +group :test do |
| 69 | + gem 'puppet', 'puppet', ENV.fetch('PUPPET_VERSION', '~> 5.5') |
| 70 | + gem 'rspec' |
| 71 | + gem 'rspec-puppet' |
| 72 | + gem 'hiera-puppet-helper' |
| 73 | + gem 'puppetlabs_spec_helper' |
| 74 | + gem 'metadata-json-lint' |
| 75 | + gem 'puppet-strings' |
| 76 | + gem 'simp-spec-helpers' |
| 77 | + gem 'simp-rspec-puppet-facts', ENV.fetch('SIMP_RSPEC_PUPPET_FACTS_VERSION', '~> 2.2') |
| 78 | + gem 'simp-rake-helpers', ENV.fetch('SIMP_RAKE_HELPERS_VERSION', '~> 5.9') |
| 79 | + gem 'facterdb' |
| 80 | +end |
| 81 | +``` |
| 82 | + |
| 83 | +## Usage |
| 84 | + |
| 85 | +### In a Unit Test |
| 86 | + |
| 87 | +In your puppet module, create a file spec/spec_helper.rb with the following contents: |
| 88 | + |
| 89 | +``` ruby |
| 90 | +require 'simp/rspec-puppet-facts' |
| 91 | +include Simp::RspecPuppetFacts |
| 92 | +require 'simp/spec_helpers' |
| 93 | +include Simp::SpecHelpers |
| 94 | +require 'pathname' |
| 95 | + |
| 96 | +fixture_path = File.expand_path(File.join(__FILE__, '..', 'fixtures')) |
| 97 | +module_name = File.basename(File.expand_path(File.join(__FILE__,'../..'))) |
| 98 | + |
| 99 | +global_spec_helper(fixture_path, module_name) |
| 100 | + |
| 101 | +# Get any local methods in spec_helper_local.rb |
| 102 | +local_spec_helper = File.join(File.dirname(File.expand_path(__FILE__)),"spec_helper_local.rb") |
| 103 | +require_relative 'spec_helper_local' if File.exists?(local_spec_helper) |
| 104 | + |
| 105 | +``` |
| 106 | +Require the spec helper at the top of each unit test file. |
| 107 | + |
| 108 | +```ruby |
| 109 | +require 'spec_helper' |
| 110 | +``` |
| 111 | +Place any module specific configurations or overrides in a file spec/spec_helper_local.rb. |
| 112 | + |
| 113 | +For example to use RSPEC instead of MOCHA to mock the environment place the following |
| 114 | +in spec/spec_helper_local.rb: |
| 115 | + |
| 116 | +``` ruby |
| 117 | +RSpec.configure do |c| |
| 118 | + c.mock_framework = :rspec |
| 119 | + c.mock_with :rspec |
| 120 | +end |
| 121 | +``` |
| 122 | + |
| 123 | +### Environment Variables |
| 124 | + |
| 125 | +PUPPET_DEBUG set to anything will enable debug |
| 126 | + |
| 127 | +### Limitations |
| 128 | + |
| 129 | +Just some more information on why you need to include compliance_markup: |
| 130 | + |
| 131 | +The helper module sets up the hiera.yml to include the compliance |
| 132 | +module. It should just ignore this if compliance_markup is not included |
| 133 | +but, because of a quirk in the testing framework, it doesn't. When it |
| 134 | +tries to compile you will get an error like: |
| 135 | +If you do not it will barf with an error that looks like |
| 136 | +``` ruby |
| 137 | + error during compilation: Evaluation Error: Error while evaluating a Function Call, undefined method `load_typed' for nil:NilClass |
| 138 | +``` |
| 139 | +if compliance_markup is not in the fixtures file. |
| 140 | + |
| 141 | + |
| 142 | + |
| 143 | +### Available methods |
| 144 | + |
| 145 | +Besides the global_spec_helper that is used to set up RSPEC the following |
| 146 | +methods are installed and can be used in your tests: |
| 147 | + |
| 148 | + |
| 149 | +#### set_hieradata(hieradata) |
| 150 | + This can be used from inside your spec tests to load custom hieradata within |
| 151 | + any context. |
| 152 | + |
| 153 | + Example: |
| 154 | + |
| 155 | + describe 'some::class' do |
| 156 | + context 'with version 10' do |
| 157 | + let(:hieradata){ "#{class_name}_v10" } |
| 158 | + ... |
| 159 | + end |
| 160 | + end |
| 161 | + |
| 162 | + Then, create a YAML file at spec/fixtures/hieradata/some__class_v10.yaml. |
| 163 | + |
| 164 | + Hiera will use this file as it's base of information stacked on top of |
| 165 | + 'default.yaml' and <module_name>.yaml per the defaults above. |
| 166 | +
|
| 167 | + Note: Any colons (:) are replaced with underscores (_) in the class name. |
| 168 | +
|
| 169 | +
|
| 170 | +#### set_environment |
| 171 | + This can be used from inside your spec tests to set the testable environment. |
| 172 | + You can use this to stub out an ENC. |
| 173 | +
|
| 174 | + Example: |
| 175 | +
|
| 176 | + context 'in the :foo environment' do |
| 177 | + let(:environment){:foo} |
| 178 | + ... |
| 179 | + end |
| 180 | +
|
| 181 | +#### normalize_compliance_results |
| 182 | + Can be used to removed expected errors in compliance data due to test configuration. |
| 183 | + See pupmod-simp-pupmod for example. |
| 184 | +
|
| 185 | +
|
| 186 | +]s |
0 commit comments