README.md in puppet-check-1.4.0 vs README.md in puppet-check-1.4.1

- old
+ new

@@ -127,10 +127,11 @@ - Puppetlabs Spec Helper has no CLI. - Puppetlabs Spec Helper intrinsically only executes spec tests against one module at a time. - Puppetlabs Spec Helper requires an additional config file for RSpec Puppet support. - Puppetlabs Spec Helper does not update external module dependencies in a stateful/persistent workspace and fails gracefully instead. - Puppetlabs Spec Helper requires extra configuration items to setup self-module RSpec testing. +- Puppetlabs Spec Helper does not frontend to Octocatalog Diff. It is worth nothing that there is no current development objective for Puppet Check to achieve the same advanced level of robustness for spec testing that Puppetlabs Spec Helper enables. If you are performing standard spec testing on your Puppet code and data, then Puppet Check's spec testing is a fantastic lighter and faster alternative to Puppetlabs Spec Helper. If you require advanced and intricate capabilities in your spec testing (e.g. direct interfacing to the `Puppet::Parser::Scope` API), then you will likely prefer Puppetlabs Spec Helper's spec testing in conjunction with Puppet Check's file validation. ## Usage Puppet Check requires `ruby >= 2.0.0`, `puppet >= 3.4`, and `puppet-lint >= 1.1.0`. `Octocatalog-diff >= 1.0.0` if you are performing smoke/regression checks. All other dependencies should be fine with various versions. Puppet Check can be used with a CLI, Rake tasks, or API, from your system, rbenv, rvm, Docker, or Vagrant. Please note all interfaces (API by default, but can be modified) will ignore any directories named `fixtures` or specified paths with that directory during file checks and spec tests. @@ -139,19 +140,21 @@ Reek dropped support for Ruby 2.0 when it went to 4.0. Since dependencies by Ruby version are allowed in Gemfiles but not gemspecs, this means that PuppetCheck installed with `bundler` will automatically pick up the correct version of Reek for your Ruby version and install it. If you are installing PuppetCheck via `gem`, then you can install reek normally with `gem` with Ruby >= 2.1, but you will need to specify `gem install reek -v 3.11` if you are using Ruby 2.0. ### CLI ``` usage: puppet-check [options] paths + --version Display the current version. -f, --future Enable future parser + --fail-on-warnings Fail on warnings -s, --style Enable style checks - --smoke Enable smoke testing + --smoke Enable smoke testing -r, --regression Enable regression testing (in progress, do not use) -o, --output format Format for results output (default is text): text, json, or yaml - --octoconfig config_file Octocatalog-diff configuration file to use. - -n, --octonodes node1.example.com,node2.example.com - Octocatalog-diff nodes to test catalog on. - --puppet-lint arg_one,arg_two + --octoconfig config_file Octocatalog-diff configuration file to use. + -n node1.example.com,node2.example.com, + --octonodes Octocatalog-diff nodes to test catalog on. + --puppet-lint arg_one,arg_two Arguments for PuppetLint ignored checks -c, --config file Load PuppetLint options from file. --rubocop arg_one,arg_two Arguments for Rubocop disabled cops ``` @@ -174,17 +177,20 @@ #### puppetcheck:file You can add style, smoke, and regression checks to and select the future parser for the `rake puppetcheck:file`, or change the output format, by adding the following after the require: ```ruby -PuppetCheck.style_check = true -PuppetCheck.future_parser = true -PuppetCheck.smoke_check = true -PuppetCheck.regression_check = true # in progress, do not use -PuppetCheck.output_format = 'yaml' -PuppetCheck.octoconfig = '.octocatalog-diff.cfg.rb' -PuppetCheck.octonodes = %w(localhost.localdomain) +PuppetCheck.settings[:style_check] = true +PuppetCheck.settings[:fail_on_warnings] = true +PuppetCheck.settings[:future_parser] = true +PuppetCheck.settings[:smoke_check] = true +PuppetCheck.settings[:regression_check] = true # in progress, do not use +PuppetCheck.settings[:output_format] = 'yaml' +PuppetCheck.settings[:octoconfig] = '.octocatalog-diff.cfg.rb' +PuppetCheck.settings[:octonodes] = %w(localhost.localdomain) +PuppetCheck.settings[:puppetlint_args] = ['--puppetlint-arg-one', '--puppetlint-arg-two'] +PuppetCheck.settings[:rubocop_args] = ['--except', 'rubocop-arg-one,rubocop-arg-two'] ``` Please note that `rspec` does not support yaml output and therefore would still use the default 'progress' formatter even if `yaml` is specified as the format option to Puppet Check. The style checks from within `rake puppetcheck:file` are directly interfaced to `puppet-lint`, `rubocop`, and `reek`. This means that all arguments and options should be specified from within your `.puppet-lint.rc`, `.rubocop.yml`, and `*.reek`. The capability to pass style arguments and options from within the `Rakefile` task block will be considered for future versions. @@ -194,11 +200,11 @@ Please note it is perfectly acceptable to only execute standard RSpec tests in your modules and not use the extended RSpec Puppet matchers. If no Puppet module directories are identified during directory parsing, then no RSpec Puppet related actions (including those described below) will be performed. Prior to executing the spec tests, Puppet Check will parse everything in the current path and identify all `spec` directories not within `fixtures` directories. It will then execute RSpec Puppet setup actions inside all directories one level above that contain a `manifests` directory. This is assumed to be a Puppet module directory. These setup actions include creating all of the necessary directories inside of `spec/fixtures`, creating a blank `site.pp` if it is missing, symlinking everything from the module that is needed into fixtures (automatically replaces functionality of self module symlink in `.fixtures.yaml` from Puppetlabs Spec Helper), and creates the `spec_helper.rb` if it is missing. Note these setup actions can replace `rspec-puppet-init` from RSpec Puppet and currently are both faster and more accurate. -Puppet Check will also automatically download specified external module dependencies for and during RSpec Puppet testing. Currently `git`, `puppet forge`, and `hg` commands are supported. They can be implemented in the following way in your modules' `metadata.json`: +Puppet Check will also automatically download specified external module dependencies for and during RSpec Puppet testing. Currently `git`, `puppet forge`, `svn`, and `hg` commands are supported. They can be implemented in the following way in your modules' `metadata.json`: ```json "dependencies": [ { "name": "module-name", @@ -212,10 +218,15 @@ }, { "name": "module-name", "hg": "hg-url", "args": "hg clone optional-arguments" + }, + { + "name": "module-name", + "svn": "svn-url", + "args": "svn co optional arguments" } ] ``` Example: @@ -232,11 +243,11 @@ "git": "https://github.com/puppetlabs/puppetlabs-lvm.git" } ] ``` -Note that `args` will be ignored during `git pull` and `hg pull/hg update` when the modules are updated instead of freshly cloned. +Note that `args` will be ignored during `git pull`, 'svn update', and `hg pull/hg update` when the modules are updated instead of freshly cloned. #### puppetcheck:beaker The spec tests will be executed against everything that matches the pattern `**/acceptance`. Any of these directories inside of a `fixtures` directory will be ignored. This means everything in the current path that appears to be a Puppet module acceptance test for your module (not dependencies) will be regarded as such and executed during this rake task. Please note this is merely a frontend to Beaker and that Beaker itself has a self-contained scope compared to all the other tools Puppet Check interfaces with and utilizes. This means if you want to add Beaker-RSpec, Serverspec, etc., or perform advanced configurations, those would be all be performed within Beaker itself. This task merely provides an interface to integrate Beaker in with your other testing infrastructure. @@ -247,19 +258,20 @@ ```ruby # file checks require 'puppet-check' -PuppetCheck.future_parser = true # default false -PuppetCheck.style_check = true # default false -PuppetCheck.smoke_check = true # default false -PuppetCheck.regression_check = true # in progress, do not use; default false -PuppetCheck.output_format = 'yaml' # also 'json'; default 'text' -PuppetCheck.octoconfig = '$HOME/octocatalog-diff.cfg.rb' # default '.octocatalog-diff.cfg.rb' -PuppetCheck.octonodes = %w(server.example.com) # default: %w(localhost.localdomain) -PuppetCheck.puppetlint_args = ['--puppetlint-arg-one', '--puppetlint-arg-two'] # default [] -PuppetCheck.rubocop_args = ['--except', 'rubocop-arg-one,rubocop-arg-two'] # default [] +PuppetCheck.settings[:future_parser] = true # default false +PuppetCheck.settings[:fail_on_warnings] = true # default false +PuppetCheck.settings[:style_check] = true # default false +PuppetCheck.settings[:smoke_check] = true # default false +PuppetCheck.settings[:regression_check] = true # in progress, do not use; default false +PuppetCheck.settings[:output_format] = 'yaml' # also 'json'; default 'text' +PuppetCheck.settings[:octoconfig] = '$HOME/octocatalog-diff.cfg.rb' # default '.octocatalog-diff.cfg.rb' +PuppetCheck.settings[:octonodes] = %w(server.example.com) # default: %w(localhost.localdomain) +PuppetCheck.settings[:puppetlint_args] = ['--puppetlint-arg-one', '--puppetlint-arg-two'] # default [] +PuppetCheck.settings[:rubocop_args] = ['--except', 'rubocop-arg-one,rubocop-arg-two'] # default [] PuppetCheck.new.run([dirs, files]) # rspec checks (as part of a RSpec::Core::RakeTask.new block with |task|) require 'puppet-check/rspec_puppet_support' @@ -316,12 +328,12 @@ ``` To overcome the lack of convenient portability, you could try spinning up the Vagrant instance at the top level of your Puppet code and data and then descend into directories to execute tests as necessary. Cleverness or patience will be necessary if you decide to use Vagrant for testing and desire portability. ### Exit Codes -- 0: PuppetCheck exited with no internal exceptions or errors in your Puppet code and data. -- 1: PuppetCheck exited with an internal exception (takes preference over other non-zero exit codes) or failed spec test. -- 2: PuppetCheck exited with one or more errors in your Puppet code and data. +- 0: PuppetCheck exited with no internal exceptions or errors in your code and data. +- 1: PuppetCheck exited with an internal exception (takes preference over other non-zero exit codes) or failed spec test(s). +- 2: PuppetCheck exited with one or more errors in your code and data. Alternatively, PuppetCheck exited with one or more warnings in your code and data and you specified to fail on warnings. ### Optional dependencies - **rake**: install this if you want to use Puppet Check with `rake` tasks in addition to the CLI. - **rspec**: install this if you want to use Puppet Check to execute the spec tests for your Ruby files during `rake`. - **rspec-puppet**: install this if you want to use Puppet Check to execute the spec tests for your Puppet files during `rake`.