README.md in puppet-check-1.3.0 vs README.md in puppet-check-1.3.1

- old
+ new

@@ -4,10 +4,11 @@ - [Description](#description) - [Usage](#usage) - [CLI](#cli) - [Rake](#rake) - [Docker](#docker) + - [Vagrant](#vagrant) - [Exit Codes](#exit-codes) - [Optional Dependencies](#optional-dependencies) - [Contributing](#contributing) ## Description @@ -110,18 +111,23 @@ - Puppetlabs Spec Helper has extra layers of gems in between it and the gems executing the checks. - Puppetlabs Spec Helper does not allow interfacing through it to the gems executing the checks. - 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. 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 lightweight 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 >= 2.0.0`. All other dependencies should be fine with various versions. Puppet Check can be used either with a CLI or Rake tasks. Please note both interfaces will ignore any directories named `fixtures` or specified paths with that directory during file checks and spec tests. +#### Reek +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. + #### Important Note for Ruby 1.9.3 and PuppetCheck <= 1.2.1 -If you are using Ruby 1.9.3, there is an issue where `Hiera <= 3.2.0` has an unspecified version dependency on JSonPure. Since JSonPure 2.0.2 requires `ruby >= 2.0.0`, this breaks Hiera installs on Ruby 1.9.3, which breaks Puppet installs, which breaks PuppetCheck installs. Therefore, you will need to either restrict your installed version of JSonPure to something lower than 2.0.2 if you are using Ruby 1.9.3, or use `Hiera >= 3.2.1`. +If you are using Ruby 1.9.3 (and therefore also PuppetCheck <= 1.2.1), there is an issue where `Hiera <= 3.2.0` has an unspecified version dependency on JSonPure. Since JSonPure 2.0.2 requires `ruby >= 2.0.0`, this breaks Hiera installs on Ruby 1.9.3, which breaks Puppet installs, which breaks PuppetCheck installs. Therefore, you will need to either restrict your installed version of JSonPure to something lower than 2.0.2 if you are using Ruby 1.9.3, or use `Hiera >= 3.2.1`. ### CLI ``` usage: puppet-check [options] paths -f, --future Enable future parser @@ -135,11 +141,11 @@ The command line interface enables the ability to select the Puppet future parser, additional style checks besides the syntax checks, and to specify PuppetLint and Rubocop checks to ignore. If you require a more robust interface to PuppetLint, Rubocop, and Reek, then please use `.puppet-lint.rc`, `.rubocop.yml` and `*.reek` config files. The `.puppet-lint.rc` can be specified with the `-c` argument. If it is not specified, then PuppetLint will automatically load one from `.puppet-lint.rc`, `~/.puppet-lint.rc`, or `/etc/puppet-lint.rc`, in that order of preference. The nearest `.rubocop.yml` and `*.reek` will be automatically respected. Example: ``` -puppet-check -s --puppet-lint no-hard_tabs-check,no-140chars-check --rubocop Metrics/LineLength,Style/Encoding path/to/code_and_data +puppet-check -s --puppet-lint no-hard_tabs-check,no-140chars-check --rubocop Metrics/LineLength,Style/Encoding -o yaml path/to/code_and_data ``` ### Rake Interfacing with Puppet-Check via `rake` requires a `require puppet-check/tasks` in your Rakefile. This generates the following `rake` commands: @@ -154,11 +160,11 @@ You can add style 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.output_format = yaml +PuppetCheck.output_format = 'yaml' ``` 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. @@ -206,10 +212,12 @@ "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. + #### 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. @@ -234,18 +242,43 @@ ENTRYPOINT ["rake", "puppetcheck"] ``` You can also build your own general container for testing various Puppet situations by removing the last three lines. You can then test each module, directory environment, etc. on top of that container by merely adding and modifying the final three lines to a Dockerfile that uses the container you built from the first four lines. This is recommended usage due to being very efficient and stable. +### Vagrant + +As an alternative to Docker, you can also use Vagrant for quick and disposable testing, but it is not as portable as Docker for these testing purposes. Below is an example Vagrantfile for this purpose. + +```ruby +Vagrant.configure(2) do |config| + # a reliable and small box at the moment + config.vm.box = 'fedora/23' + + config.vm.provision 'shell', inline: <<-SHELL + # cd to 'sync' if this is recent Vagrant; cd to '/vagrant' if this is older Vagrant + cd sync || cd /vagrant + # you need ruby and any other extra dependencies that come from packages; in this example we install git to use it for downloading external module dependencies + sudo dnf install ruby rubygems git -y + # you need puppet-check and any other extra dependencies that come from gems; in this example we install reek because the ruby ABI is 2.2 and then rspec-puppet and rake for extra testing + sudo gem install --no-rdoc --no-ri puppet-check reek rspec-puppet rake + # this is needed for the ruby json parser to not flip out on fresh os installs for some reason (change encoding value as necessary) + export LANG='en_US.UTF-8' + # execute your tests; in this example we are executing the full suite of tests + rake puppetcheck + SHELL +end +``` + +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. ### Optional dependencies -- **reek**: will automatically (with `bundler`, otherwise manually) be installed as a dependency and checks enabled during style checks if your Ruby version is `>= 2.1.0`. - **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**: 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`. - **beaker**: install this if you want to use Puppet Check to execute the acceptance tests during `rake`. - **git**: install this if you want to use Puppet Check to download external module dependencies with `git` commands during RSpec Puppet testing. - **mercurial**: install this if you want to use Puppet Check to download external module dependencies with `hg` commands during RSpec Puppet testing.