pdqtest 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75a6265aa171ae4d88a6e97d754c6018edfe7d3a
-  data.tar.gz: b1ae71344008ff1fdaabf2df6b332c0dc8766c27
+  metadata.gz: 81c318fbee9b279339ea33b3eadb67d6a24d522e
+  data.tar.gz: fe53d0ad29c10016b86f2113b719fe7b7105fd36
 SHA512:
-  metadata.gz: '019cde9a45ac72c3f48e1d06779fcdf9d56971215cb434fe2a9cc78dd02a4bb2a699bad97fcb82cdc45e117bd6076975abf222ffa51edc04e5238a600eb3d3df'
-  data.tar.gz: 382c6283d6c0c2801d21634fe3a2709978cd35f7a715fd0d9834bf289b2dfffed77138673162e32f1ae0042335168e5409e25aad79365c937adba584d5b1e3f2
+  metadata.gz: ba76837160b19db3801709f6c0303e904d40f8ce1704bae50a0cbacf604a2095ba82a488ad65bc468122eb8583b4292c01a614221783b687cce474114750a2d4
+  data.tar.gz: 9a261e76ea262d5051b71afd1778f46a67667bbb0664175ca468ecb09496ac902b55e9e28eafd9734ffc83d61362f029efea09e16e0a85e42d32b98bf7c5a1e9

data/.gitignore

@@ -3,7 +3,6 @@
 /Gemfile.lock
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/

data/README.md

@@ -10,257 +10,19 @@ PDQTest - Puppet Docker Quick-test - is the quickest and easiest way to test you
 
 And can generate code to retrofit testing to a new or existing module, along with skeleton RSpec and acceptance tests to get you started.
 
-PDQTest runs linting, syntax and RSpec tests within the machine it is running from and then loads a docker container to perform acceptance testing.
-
-## Installation
-
-To install PDQTest on your system:
-
-### System Ruby
-```shell
-gem install pdqtest
-```
-
-### Bundler, add this line to your application's Gemfile:
-```ruby
-gem 'pdqtest
-```
-* It's advisable to specify a version number to ensure repeatable builds
-
-### Puppet modules
-To add PDQTests to a new or existing puppet module, run the command:
-```
-pdqtest init
-```
-
-This will install PDQTest into the `Gemfile` and will generate an example set of acceptance tests
-
-## Running tests
-
-### PDQTest preparation
-PDQTest needs to download a Docker image before running tests:
-
-```
-bundle exec pdqtest setup
-```
-
-This image is updated periodically, the above command will download the appropriate image for the version of `pdqtest` being used.
-
-### Module dependencies/.fixtures.yml
-There is no need to maintain a `.fixtures.yml` file and the presence of this file when using `pdqtest` is an error.
-
-#### Public modules (PuppetForge)
-Dependencies on public forge modules must be specified in your module's `metadata.json` file.
-
-#### Private modules (from git)
-If you need to download modules from git, then you must populate the `fixtures` section of `fixtures.yml`, eg:
-
-```
-repositories:
-  corporatestuff:
-    repo: 'https://nonpublicgit.megacorp.com/corporatestuff.git'
-    ref: 'mybranch'
-```
-
-##### Notes:
-* The filename is `fixtures.yml` NOT `.fixtures.yml`.  The leading dot had to be removed to avoid `puppetlabs_spec_helper` also detecting the file and trying to use it.
-* The file format of `.fixtures.yml` and `fixtures.yml` for specifing git repositories is identical
-* Only the repositories section of the file will be processed as we do not use `puppetlabs_spec_helper` to do this for us.
-
-## Merging additional facts
-PDQTest includes built-in [factsets](https://github.com/declarativesystems/puppet_factset) covering many common operating systems, however, sometimes additional facts are needed throughout a module to mock an external fact or custom fact from a different module that is expected to be some known value.  In this case, creating the directory:
-
-```
-spec/merge_facts
-```
-
-Inside the module being tested will result in all JSON files contained being merged into all OS specific factsets used for testing as generated by `pdqtest generate_rspec`.  To put it simply, drop `.json` file(s) in this directory to add them to every factset.
-
-These facts will be made automatically avaialable to facter when running acceptance testing
-
-### All tests
-If you just want to run all tests:
-
-```shell
-bundle exec pdqtest all
-```
-
-### RSpec tests
-```shell
-bundle exec pdqtest rspec
-```
-
-### Debugging failed builds
-PDQTest makes it easy to debug failed builds:
-
-```shell
-pdqtest shell
-```
-
-* Open a shell inside the docker container that would be used to run tests
-* Your code is available at `/testcase`
-
-```shell
-pdqtest --keep-container all
-```
-* Run all tests, report pass/fail status
-* Keep the container Running
-* After testing, the container used to run tests will be left running and a message will be printed showing how to enter the container used for testing.  Your code is avaiable at `/testcase`
-
-## About acceptance tests
-* Acceptance tests run within a Docker container managed by PDQTest
-* The Docker container breaks all the rules of Docker and runs a full version of Systemd to allow complete testing of Puppet code in the most portable way (basically treat docker as a high speed VM)... This is deliberate - PDQTest exists to get results, not be a perfect Docker app.
-* The test container uses a minimal version of Centos 7, there's no option to change this at present
-* The container will only be started if at least one example file is present and contains the correct magic marker
-* You can get a shell on the docker container if needed:
-  * A representitive system, identical to that which will be used to run the tests `pdqtest shell`
-  * The actual container that was just used on a test run `pdqtest --keep-container all` and run the command indicated on exit
-
-### Test workflow
-1. Scan for all example files under `/examples`.  Files must end in `.pp` and contain the magic marker `#@PDQTest` to be processed
-2. If example files are present, start the docker container
-3. For each example file:
-  * Check for a file at `/spec/acceptance/EXAMPLE_NAME__setup.sh`,   If it exists, run it inside the container.  This is a useful place to install preqrequisites, edit files, install mock services, clean up after other tests, etc.
-  * Check for a file at `/spec/acceptance/EXAMPLE_NAME__before.bats`, If it exists run BATS against it.  This is normally used to check the system state is clean or that any test prerequisites have been setup correctly
-  * Run `puppet apply` on the example file twice
-  * Check for a file at `/spec/acceptance/EXAMPLE_NAME.bats`, If it exists run BATS against it.  This is normally used to check the state of the system after running puppet.  You can do things like check services are running, check files edited correctly, or basically anything that you can write in bash!
-4. Destroy the container unless we were asked to keep it with `--keep-container`
-
-Note: `EXAMPLE_NAME` is the example filename minus the directory and `.pp`, eg the `EXAMPLE_NAME` for `examples/foo.pp` would just be `foo`.
-
-### Example files
-* Found inside `/examples`
-* Regular puppet code
-* Will be executed _twice_ (to check for idempotency) with `puppet apply`
-* _MUST_ contain the magic marker `#@PDQTest` on a line at the top of the file to indicate that this test should be processed by PDQTest
-* Basically the same as a regular puppet [smoke test](https://docs.puppet.com/puppet/latest/tests_smoke.html#module-smoke-testing) but run automatically and with system state tests
-
-### BATS tests
-If you've never seen a BATS test before and have previously been writing server spec code, you'll probably kick youself when you see how simple they are.  Here's an example:
-
-```BASH
-# Tests are really easy! just the exit status of running a command...
-@test "addition using bc" {
-  result="$(ls /)"
-  [ "$?" -eq 0 ]
-}
-```
-
-Tests are all written in BASH and the testcase passes if the stanza returns zero.  This means that basically any Linux/Unix sysadmin is now empowered to write Testcases and do TDD - score!
-
-Since our tests are written in BASH, there are of course all the usual bash quirks such as failing on incorrect spacing, bizzare variable quoting etc, but given the simplicity gained its a worthwhile tradeoff.
-
-Consider the following (real) test:
-
-```BASH
-@test "ClientAliveCountMax" {
-  grep "ClientAliveCountMax 1" /etc/ssh/sshd_config
-}
-```
-
-Here, we have done exactly what it looks like we have done - checked for the value of a particular setting in a text file.  Since our tests our plain old BASH, it means we can do things like test daemons are running with `systemctl`, test ports are open with `netstat` and do complete system tests `wget` and `curl`.  Cool!
-
-#### Worked Example
-Lets say you have two examples, `foo.pp` and `init.pp`.  In this case, the full range of files to create for acceptance testing would look like this:
-```
-mycoolmodule
-├── examples
-│   ├── foo.pp
-│   └── init.pp
-├── ...
-└── spec
-    ├── acceptance
-    │   ├── foo__before.bats
-    │   ├── foo__setup.sh
-    │   ├── foo.bats
-    │   ├── init__before.bats
-    │   ├── init__setup.sh
-    │   └── init.bats
-    ├── ...
-```
-
-* You can put any puppet code you like (includeing an empty file...) in each of the files under `/examples` and it will executed with `puppet apply`
-* If you need to test multiple different things (eg different parameters for a new type and provider), you need to create different testcase for each distinct thing to test.  See below for help generating these
-* You can skip setup or BATS testing before and/or after running `puppet apply` if desired by deleting the appropriate files
-* If you delete all of the files under `spec/acceptance` for a given example, then PDQTest will just check that puppet runs idempotently for your example
-* To disable tests temporarily for a specific example, remove the magic marker `#@PDQTest` from the desired example
-* Nested examples (subdirectories) are not supported at this time
-
-## Real world example
-See https://github.com/GeoffWilliams/puppet-filemagic for a project with lots of acceptance tests.
-
-## Test Generation
-Creating a bunch of files manually is an error prone and tedious operation so PDQTest can generate files and boilerplate code for you so that your up and running in the quickest time possible.
-
-### Skeleton
-* `pdqtest init` will generate a basic set of tests to get you started (tests init.pp)
-
-### RSpec tests
-The skeleton tests created by `pdqtest init` only cover the `init.pp` file which is useful but your likely going to need to support more classes as your modules grow.  PDQTest can generate basic RSpec testcases for each new puppet class that exists in the manifests directory for you:
-
-```shell
-pdqtest generate_rspec
-```
-
-* For every `.pp` file containing a puppet class under `/manifests`, RSpec will be generated to:
-  * Check the catalogue compiles
-  * Check the catalogue contains an instance of the class
-  * This gives developers an easy place to start writing additional RSpec tests for specific behaviour
-  * Its safe to run this command whenever you add a new class, it won't overwrite any existing RSpec testcases
-
-### Acceptance tests
-
-#### Generate boilerplate files for each example found (including those without a magic marker)
-
-```shell
-pdqtest generate_acceptance
-```
-
-#### Generate boilerplate files for one specific example
-
-```shell
-pdqtest generate_acceptance examples/mynewthing.pp
-```
-* Note:  will also create examples/mynewthing.pp if you haven't created it yet
-
-## Caching
-PDQTest will attempt to cache:
-* Puppet modules (via librarian-puppet) in `~/.pdqtest/cache/modules`
-* The yum cache in `~/.pdqtest/cache/yum`
-
-Note that since the yum cache is writen to via a docker volume from the container your running tests in, the files in this directory will be root owned.  If you need to clear your cache for whatever reason, delete the `~/.pdqtest/cache` directory (you will likely need sudo) and PDQtest will recreate it next time it runs.
-
-## Development
-
-PRs welcome :)  Please ensure suitable tests cover any new functionality and that all tests are passing before and after your development work:
-
-```shell
-bundle exec rake spec
-```
-
-## Who should use PDQTest?
-You should use pdqtest if you find it increases your productivity and enriches your life
-
-## Troubleshooting
-* If you can't find the `pdqtest` command and your using `rbenv` be sure to run `rbenv rehash` after installing the gem to create the necessary symlinks
-* Don't forget to run `pdqtest setup` before your first `pdqtest` run to download/update the Docker image
-* If you need to access private git repositories, make sure to use `fixtures.yml` not `.fixtures.yml`
-* If you need a private key to access private repositories, set this up for your regular git command/ssh and `pdqtest` will reuse the settings
-* Be sure to annotate the examples you wish to acceptance test with the magic marker comment `#@PDQTest`
-* Sometimes you might get an error: `Could not resolve the dependencies.` when executing tests.  This message is from librarian puppet and usually indicates a conflict between the `metadata.json` files somewhere in the set of modules you are attempting to use.  Running the command `librarian-puppet install --path spec/fixtures/ --destructive --verbose` should give you enough information to resolve the error
-* Be sure to run `make` or `bundle exec pdqtest all` to download dependencies when running acceptance tests.  Previous versions (re)downloaded modules as required from inside docker but this step has been replaced with a simple symlink.
-
-## Support
-This software is not supported by Puppet, Inc.  Use at your own risk.
-
-## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/declarativesystems/pdqtest.
-
-## Upgrade notes
-* Previous versions of PDQTest mounted code at `/cut` (Code Under Test), this will still work for a few versions but the preferred mountpoint is now the more obvious `/testcase`
-
-### Running tests
-* PDQTest includes a comprehensive tests for core library functions.  Please ensure tests pass before and after any PRs
-* Run all tests `bundle exec rake spec`
-* Run specific test file `bundle exec rspec ./spec/SPEC/FILE/TO/RUN.rb`
-* Run specific test case `bundle exec rspec ./spec/SPEC/FILE/TO/RUN.rb:99` (where 99 is the line number of the test)
+PDQTest runs linting, syntax and RSpec tests within the machine it is running from and then loads a docker container to perform acceptance testing, sharing the puppet module and cached dependencies from your host.
+
+## PDQTest Manual
+1. [Installation](doc/installation.md)
+2. [Enabling testing](doc/enableing_testing.md)
+3. [Running tests](doc/running_tests.md)
+4. [Test generation](doc/test_generation.md)
+5. [Puppet module dependencies](doc/puppet_module_dependencies.md)
+6. [Puppet facts](doc/puppet_facts.md)
+7. [Hiera](doc/hiera.md)
+8. [Caching](doc/caching.md)
+9. [Upgrading](doc/upgrading.md)
+10. [Examples](doc/examples.md)
+11. [Tips and tricks](doc/tips_and_tricks.md)
+12. [Troubleshooting](doc/troubleshooting.md)
+13. [Development](doc/development.md)

data/doc/acceptance_tests.md

@@ -0,0 +1,87 @@
+# Acceptance tests
+* Acceptance tests run within a Docker container managed by PDQTest
+* The Docker container breaks all the rules of Docker and runs a full version of Systemd to allow complete testing of Puppet code in the most portable way (basically treat docker as a high speed VM)... This is deliberate - PDQTest exists to get results, not be a perfect Docker app.
+* The test container uses a minimal version of Centos 7, there's no option to change this at present
+* The container will only be started if at least one example file is present **and contains the correct magic marker**
+* You can get a shell on the docker container if needed, see [Debugging failed builds](#debugging-failed-builds)
+
+### Test workflow
+1. Scan for all example files under `/examples`.  Files must end in `.pp` and contain the magic marker `#@PDQTest` to be processed
+2. If example files are present, start the docker container
+3. For each example file:
+  * Check for a file at `/spec/acceptance/EXAMPLE_NAME__setup.sh`,   If it exists, run it inside the container.  This is a useful place to install preqrequisites, edit files, install mock services, clean up after other tests, etc.
+  * Check for a file at `/spec/acceptance/EXAMPLE_NAME__before.bats`, If it exists run BATS against it.  This is normally used to check the system state is clean or that any test prerequisites have been setup correctly
+  * Run `puppet apply` on the example file twice
+  * Check for a file at `/spec/acceptance/EXAMPLE_NAME.bats`, If it exists run BATS against it.  This is normally used to check the state of the system after running puppet.  You can do things like check services are running, check files edited correctly, or basically anything that you can write in bash!
+4. Destroy the container unless we were asked to keep it with `--keep-container`
+
+Note: `EXAMPLE_NAME` is the example filename minus the directory and `.pp`, eg the `EXAMPLE_NAME` for `examples/foo.pp` would just be `foo`.
+
+### Example files
+* Found inside `/examples`
+* Regular puppet code
+* Will be executed _twice_ (to check for idempotency) with `puppet apply`
+* _MUST_ contain the magic marker `#@PDQTest` on a line at the top of the file to indicate that this test should be processed by PDQTest
+* Basically the same as a regular puppet [smoke test](https://docs.puppet.com/puppet/latest/tests_smoke.html#module-smoke-testing) but run automatically and with system state tests
+
+### BATS tests
+If you've never seen a BATS test before and have previously been writing server spec code, you'll probably kick youself when you see how simple they are.  Here's an example:
+
+```BASH
+# Tests are really easy! just the exit status of running a command...
+@test "addition using bc" {
+  result="$(ls /)"
+  [ "$?" -eq 0 ]
+}
+```
+
+Tests are all written in BASH and the testcase passes if the stanza returns zero.  This means that basically any Linux/Unix sysadmin is now empowered to write Testcases and do TDD - score!
+
+Since our tests are written in BASH, there are of course all the usual bash quirks such as failing on incorrect spacing, bizzare variable quoting etc, but given the simplicity gained its a worthwhile tradeoff.
+
+Consider the following (real) test:
+
+```BASH
+@test "ClientAliveCountMax" {
+  grep "ClientAliveCountMax 1" /etc/ssh/sshd_config
+}
+```
+
+Here, we have done exactly what it looks like we have done - checked for the value of a particular setting in a text file.  Since our tests our plain old BASH, it means we can do things like test daemons are running with `systemctl`, test ports are open with `netstat` and do complete system tests `wget` and `curl`.  Cool!
+
+#### Worked Example
+Lets say you have two examples, `foo.pp` and `init.pp`.  In this case, the full range of files to create for acceptance testing would look like this:
+```
+mycoolmodule
+├── examples
+│   ├── foo.pp
+│   └── init.pp
+├── ...
+└── spec
+    ├── acceptance
+    │   ├── foo__before.bats
+    │   ├── foo__setup.sh
+    │   ├── foo.bats
+    │   ├── init__before.bats
+    │   ├── init__setup.sh
+    │   └── init.bats
+    ├── ...
+```
+
+### Debugging failed builds
+PDQTest makes it easy to debug failed builds:
+
+```shell
+pdqtest shell
+```
+
+* Opens a shell inside the docker container that would be used to run tests
+* Your code is available at `/testcase`
+
+```shell
+pdqtest --keep-container all
+```
+* Runs all tests, report pass/fail status
+* Keeps the container Running
+* After testing, the container used to run tests will be left running and a message will be printed showing how to enter the container used for testing.  Your code is avaiable at `/testcase`
+* User is responsible for cleaning up the containers created in this mode

data/doc/caching.md

@@ -0,0 +1,6 @@
+# Caching
+PDQTest will attempt to cache:
+* Puppet modules (via librarian-puppet) in `~/.pdqtest/cache/modules`
+* The yum cache in `~/.pdqtest/cache/yum`
+
+Note that since the yum cache is writen to via a docker volume from the container your running tests in, the files in this directory will be root owned.  If you need to clear your cache for whatever reason, delete the `~/.pdqtest/cache` directory (you will likely need `sudo`) and PDQtest will recreate it next time it runs.

data/doc/development.md

@@ -0,0 +1,15 @@
+# Development
+
+PRs welcome :)  Please ensure suitable tests cover any new functionality and that all tests are passing before and after your development work.
+
+## Support
+Interested in commercial support of PDQTest?  Please email sales@declarativesystems.com to discuss your needs.
+
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/declarativesystems/pdqtest.
+
+### Running tests
+* PDQTest includes a comprehensive tests for core library functions.  Please ensure tests pass before and after any PRs
+* Run all tests `bundle exec rake spec`
+* Run specific test file `bundle exec rspec ./spec/SPEC/FILE/TO/RUN.rb`
+* Run specific test case `bundle exec rspec ./spec/SPEC/FILE/TO/RUN.rb:99` (where 99 is the line number of the test)

data/doc/enabling_testing.md

@@ -0,0 +1,11 @@
+# Enabling testing
+To add PDQTest to a new or existing puppet module, run the commands:
+
+```shell
+pdqtest init
+bundle install
+```
+
+From the top level directory of your puppet module. This will install PDQTest into the `Gemfile` (for bundler), and generate an example set of acceptance tests.  The `bundle install` step will need development libraries installed if you haven't already obtained them.
+
+Note:  Your puppet module *must* have a valid `metatadata.json` file.  Create one before running `pdqtest init` if you don't already have one.  If your creating a puppet module from scratch, try `puppet module generate` to create a complete module skeleton that includes a valid version of this file.

data/doc/examples.md

@@ -0,0 +1,10 @@
+# Examples
+
+Here are some projects that use PDQTest:
+* https://github.com/geoffwilliams/puppet-motd
+* https://github.com/declarativesystems/download_and_do
+* https://github.com/GeoffWilliams/puppet-filemagic
+* https://github.com/declarativesystems/ssh
+* https://github.com/declarativesystems/puppet-chown_r/tree/master/spec/acceptance
+
+Do you use PDQTest on your own projects?  If you have a good public example let me know!

data/doc/hiera.md

@@ -0,0 +1,43 @@
+# Hiera
+Under normal circumstances, only a `profile` module would be consuming Hiera data directly using the `hiera()` function, and its suggested by many that these too fall back to automatic data binding parameters rather then use the `hiera()` function directly.  In this case it makes more sense to use the excellent [Onceover](https://github.com/dylanratcliffe/onceover) tool to perform end-to-end testing of your Hiera data, puppet control repository and roles/profile modules.
+
+That said, there may be occasions where you need to mock hiera data:
+* You have implemented Roles and Profiles as a namespace inside a team module (for multi-tennanting)
+* You have a module that performs `hiera()` lookups directly
+* You intend to drive your module by adding data to hiera and including a class to make something happen
+* Your class fails to compile due to missing hiera data
+* You have a separate git repository for your `profile` module and want to be able to test it
+
+## Alternative method
+In some cases where it may be easiest to directly inject strings in lieu of setting up a fake hiera:
+
+### RSpec Tests
+```ruby
+let :params do
+  {
+    :data_from_hiera => "faked by",
+    :more_data       => "hardcoding inline",
+  }
+end
+```
+
+### Acceptance tests
+```puppet
+class { "foo":
+  data_from_hiera => "faked by",
+  more_data       => "hardcoding inline",
+}
+```
+
+Note that you would need to duplicate your hard-coded mock data between the rspec tests and any acceptance tests.
+
+In the more complex cases it may instead be desireable to mock the hiera data in order to enable Puppet's regular lookup systems to work.
+
+## Mocking hiera
+PDQTest supports full mocking of Hiera for both RSpec and acceptance tests and support for this is enabled automatically when `pdqtest init` is run by versions of PDQTest >= 0.5.0.
+
+A basic one-level hierachy is created for you:
+* Hiera configuration file at `spec/fixtures/hiera.yaml`
+* Single hiera data file at `spec/fixtures/hieradata/test.yaml`
+
+Any required hiera data can be added to `test.yaml` and will immediately show up when lookups are made.

data/doc/installation.md

@@ -0,0 +1,15 @@
+# Installation
+PDQTest only runs on Linux/MAC systems.  If you are using Windows, the easiest way for you to run PDQTest is to install virtualisation software and then use [Vagrant](http://vagrantup.com/) to create a VM that shares a filesystem with your main Windows desktop.  This will allow you to edit your puppet code as you please and have it instantly show up inside of a Linux VM where you can run PDQTest and Docker.
+
+1. Install Ruby - you will need a fairly new version of Ruby as Puppet requires this.  [RVM](https://rvm.io/) or [RBENV](https://github.com/rbenv/rbenv) are easy ways of obtaining an up-to-date version.  Ruby 2.3 works prefectly.  You may need development libraries, eg `yum groupinstall 'Development Tools'` with these systems.  Once you have obtained a modern Ruby, follow any additional setup steps to activate the environment and then check it really worked by running `ruby --version` before proceeding.  Note that `pdqtest` should not be run as `root`.
+2. Make sure `git` is installed - `yum install git`
+3. Install the gem version of puppet - `gem install puppet`
+4. Install PDQTest - `gem install pdqtest`
+5. Install bundler (the only sane way to manage Ruby dependencies) - `gem install bundler`
+6. Install [Docker CE](www.docker.com)
+7. Start the `docker` daemon and make sure the user your running as is in the `docker` group.  You will need to log out and back in again after doing this
+8. Install the [PDQTest Docker image](https://hub.docker.com/r/geoffwilliams/pdqtest-centos/) by typing `pdqtest setup`
+
+You have now installed PDQTest.  Steps 6-8 are only required if running acceptance testing but are highly recommended.
+
+Note:  Do *NOT* run PDQTest on a managed Puppet node, you may damage the agent.

data/doc/puppet_facts.md

@@ -0,0 +1,10 @@
+# Puppet facts
+PDQTest includes built-in [factsets](https://github.com/declarativesystems/puppet_factset) covering many common operating systems, however, sometimes additional facts are needed throughout a module to mock an external fact or custom fact from a different module that is expected to be some known value.  In this case, creating the directory:
+
+```
+spec/merge_facts
+```
+
+Inside the module being tested will result in all JSON files contained being merged into all OS specific factsets used for testing as generated by `pdqtest generate_rspec`.
+
+To put it simply, drop `.json` file(s) in this directory to add them to every factset.  These facts will be made automatically avaialable to facter when running acceptance testing

data/doc/puppet_module_dependencies.md

@@ -0,0 +1,26 @@
+# Puppet module dependencies
+To test your puppet code, PDQTest needs to configured to obtain any modules the code being tested depends on.
+
+## Specifying dependencies
+
+### Public modules (PuppetForge)
+Dependencies on public forge modules must be specified in your module's `metadata.json` file.
+
+### Private modules (from git)
+If you need to download modules from git, then you must populate the `fixtures` section of `fixtures.yml`, eg:
+
+```
+repositories:
+  corporatestuff:
+    repo: 'https://nonpublicgit.megacorp.com/corporatestuff.git'
+    ref: 'mybranch'
+```
+
+
+## .fixtures.yml
+There is no need to maintain a `.fixtures.yml` file and the presence of this file when using `pdqtest` is an error.
+
+## Notes:
+* The filename is for private modules is `fixtures.yml` NOT `.fixtures.yml`.  The leading dot had to be removed to avoid `puppetlabs_spec_helper` also detecting the file and trying to use it.
+* The file format of `.fixtures.yml` and `fixtures.yml` for specifing git repositories is identical
+* Only the repositories section of the file will be processed as we do not use `puppetlabs_spec_helper` to do this for us.

data/doc/running_tests.md

@@ -0,0 +1,38 @@
+# Running tests
+If you just want to run all tests:
+
+```shell
+make
+```
+
+Alternatively, you can choose to run individul test phases directly:
+
+## All tests (excludes documentation)
+
+```shell
+bundle exec pdqtest all
+```
+
+### Syntax
+
+```shell
+bundle exec pdqtest syntax
+```
+
+### Lint
+
+```shell
+bundle exec pdqtest lint
+```
+
+### RSpec
+
+```shell
+bundle exec pdqtest rspec
+```
+
+### Acceptance
+
+```shell
+bundle exec pdqtest acceptance
+```

data/doc/test_generation.md

@@ -0,0 +1,34 @@
+# Test Generation
+Creating a bunch of files manually is an error prone and tedious operation so PDQTest can generate files and boilerplate code for you so that your up and running in the quickest time possible.
+
+
+## RSpec tests
+The skeleton tests created by `pdqtest init` only cover the `init.pp` file which is useful but your likely going to need to support more classes as your modules grow.  PDQTest can generate basic RSpec testcases for each new puppet **class** that exists in the manifests directory for you:
+
+```shell
+bundle exec pdqtest generate_rspec
+```
+
+* For every `.pp` file containing a puppet class under `/manifests`, RSpec will be generated to:
+  * Check the catalogue compiles
+  * Check the catalogue contains an instance of the class
+
+This gives developers an easy place to start writing additional RSpec tests for specific behaviour
+
+Its safe to run this command whenever you add a new class, it won't overwrite any existing RSpec testcases
+
+## Acceptance tests
+
+Generate boilerplate files for each example found (including those without a magic marker):
+
+```shell
+pdqtest generate_acceptance
+```
+
+Generate boilerplate files for one specific example:
+
+```shell
+pdqtest generate_acceptance examples/mynewthing.pp
+```
+
+Note:  This will also create examples/mynewthing.pp if you haven't created it yet

data/doc/tips_and_tricks.md

@@ -0,0 +1,13 @@
+# Tips and tricks
+* You can put any puppet code you like (including an empty file...) in each of the files under `/examples` and it will executed with `puppet apply`
+* If you need to test multiple different things (eg different parameters for a new type and provider), you need to create a different (acceptance) testcase for each distinct thing to test
+* PDQTest will only execute the BATS tests and setup scripts that are present, you can delete some or all of these files if some steps aren't required.
+* If no files are present under `spec/acceptance` for a given example, then PDQTest will just check that puppet runs idempotently for your example
+* To disable tests temporarily for a specific example, remove the magic marker `#@PDQTest` from the desired example
+* Nested examples (subdirectories) are not supported at this time
+* Since the all of the `*__setup.sh` scripts are run in the container as root before executing tests, they can be used to mock _almost anything_ in the test system:
+  * Replace system binaries to fake network operations
+  * Add system binaries to simulate other operating systems such as AIX, Solaris, etc
+  * Create/copy files, directories, etc.
+  * Install OS packages
+  * Install python scripts to mock database servers using SQLite... :wink:

data/doc/troubleshooting.md

@@ -0,0 +1,8 @@
+# Troubleshooting
+* If you can't find the `pdqtest` command and your using `rbenv` be sure to run `rbenv rehash` after installing the gem to create the necessary symlinks
+* Don't forget to run `pdqtest setup` before your first `pdqtest` run to download/update the Docker image
+* If you need to access private git repositories, make sure to use `fixtures.yml` not `.fixtures.yml`
+* If you need a private key to access private repositories, set this up for your regular git command/ssh and `pdqtest` will reuse the settings
+* Be sure to annotate the examples you wish to acceptance test with the magic marker comment `#@PDQTest`
+* Sometimes you might get an error: `Could not resolve the dependencies.` when executing tests.  This message is from librarian puppet and usually indicates a conflict between the `metadata.json` files somewhere in the set of modules you are attempting to use or the presence of a `Puppetfile` in a directory above the module your testing.  Running the command `librarian-puppet install --path spec/fixtures/ --destructive --verbose` should give you enough information to resolve the error
+* Be sure to run `make` or `bundle exec pdqtest all` to download dependencies when running acceptance tests.  Previous versions (re)downloaded modules as required from inside docker but this step has been replaced with a simple symlink to reduce the amount of downloading so the modules must already be present.

data/doc/upgrading.md

@@ -0,0 +1,28 @@
+# Upgrading
+To upgrade the current version of PDQTest on your system:
+
+```
+gem update pdqtest
+```
+
+Each project you want to use the newer version of PDQTest on should then have it's `Gemfile` updated to reference the latest version.  Don't worry, this is easy:
+
+```shell
+cd /my/cool/project/to/upgrade
+pdqtest upgrade
+bundle install
+```
+
+Note that since we're using bundler, you only have to upgrade the modules you want to upgrade.  Existing modules can continue to run any previous version via `make` just fine.
+
+## Docker image
+The docker image will be updated as and when required.  Run:
+
+```shell
+pdqtest setup
+```
+
+To obtain the latest version.
+
+## `/cut`
+Previous versions of PDQTest mounted code at `/cut` (Code Under Test), this will still work for a few versions but the preferred mountpoint is now the more obvious `/testcase`

data/exe/pdqtest

@@ -1,4 +1,13 @@
 #!/usr/bin/env ruby
+require 'rubygems'
+ruby_have = Gem::Version.new(RUBY_VERSION)
+ruby_need = Gem::Version.new('2.2.0')
+
+if (ruby_have <=> ruby_need) == -1
+  raise "Please upgrade Ruby to at least #{ruby_need.version}"
+end
+
+
 require 'pdqtest'
 require 'pdqtest/emoji'
 require 'pdqtest/instance'
@@ -8,6 +17,7 @@ require 'pdqtest/skeleton'
 require 'pdqtest/lint'
 require 'pdqtest/syntax'
 require 'pdqtest/core'
+require 'pdqtest/upgrade'
 require 'escort'
 
 # display help if nothing specified
@@ -163,4 +173,12 @@ Escort::App.create do |app|
     end
   end
 
+
+  app.command :upgrade do |command|
+    command.summary "Upgrade"
+    command.description "Upgrade the current module to use this version of PDQTest"
+    command.action do |options, arguments|
+      PDQTest::Upgrade.upgrade
+    end
+  end
 end

data/lib/pdqtest/skeleton.rb

@@ -3,6 +3,7 @@ require 'digest'
 require 'pdqtest/puppet'
 require 'pdqtest/version'
 require 'pdqtest/util'
+require 'pdqtest/upgrade'
 
 module PDQTest
   module Skeleton
@@ -14,7 +15,6 @@ module PDQTest
     SKELETON_DIR    = 'skeleton'
     EXAMPLES_DIR    = 'examples'
     GEMFILE         = 'Gemfile'
-    GEMFILE_LINE    = "gem 'pdqtest', '#{PDQTest::VERSION}'"
     HIERA_DIR       =  File.join(SPEC_DIR, 'fixtures', 'hieradata')
     HIERA_YAML      = 'hiera.yaml'
     HIERA_TEST      = 'test.yaml'
@@ -54,20 +54,10 @@ module PDQTest
     end
 
     def self.install_gemfile
-      insert_gem = false
-      if File.exists?(GEMFILE)
-        if ! File.readlines(GEMFILE).grep(/pdqtest/).any?
-          insert_gem = true
-        end
-      else
-        install_skeleton(GEMFILE, GEMFILE)
-        insert_gem = true
-      end
-      if insert_gem
-        open(GEMFILE, 'a') { |f|
-          f.puts GEMFILE_LINE
-        }
-      end
+      install_skeleton(GEMFILE, GEMFILE)
+
+      # upgrade the gemfile to *this* version of pdqtest + puppet-strings
+      Upgrade.upgrade()
     end
 
     def self.init
@@ -81,6 +71,7 @@ module PDQTest
       FileUtils.mkdir_p(ACCEPTANCE_DIR)
       FileUtils.mkdir_p(CLASSES_DIR)
       FileUtils.mkdir_p(EXAMPLES_DIR)
+      FileUtils.mkdir_p(HIERA_DIR)
 
 
       # skeleton files if required

data/lib/pdqtest/syntax.rb

@@ -1,4 +1,11 @@
-require 'puppet-syntax/tasks/puppet-syntax'
+# Ask user to install puppet gem if missing.  It's not in the bundle to avoid
+# the issue of accidentally installing the puppet gem on a managed node.
+# Fixes #21
+begin
+  require 'puppet-syntax/tasks/puppet-syntax'
+rescue LoadError
+  raise "Please install the puppet gem: `gem install puppet`"
+end
 require 'pdqtest'
 require 'pdqtest/emoji'
 module PDQTest

data/lib/pdqtest/upgrade.rb

@@ -0,0 +1,63 @@
+module PDQTest
+  module Upgrade
+    GEMFILE             = 'Gemfile'
+    GEM_REGEXP          = /gem ('|")([-\w]+)('|").*$/
+    GEM_ATTRIB_REGEXP   = /^\s*:\w+/
+
+    GEMS = {
+      'pdqtest'         => {
+        'line'  => "gem 'pdqtest', '#{PDQTest::VERSION}'",
+        'added' => false,
+      },
+      'puppet-strings'  => {
+        'line'  => "gem 'puppet-strings', :git => 'https://github.com/puppetlabs/puppet-strings'",
+        'added' => false,
+      },
+    }
+
+
+    # upgrade a module to the latest version of PDQTest
+    def self.upgrade()
+      t_file = File.open("#{GEMFILE}.tmp","w")
+      updating_gem = false
+      File.open(GEMFILE, 'r') do |f|
+        f.each_line{ |line|
+          if line =~ GEM_REGEXP
+            # a gem stanza
+            processing_gem = $2
+            if GEMS.keys.include?(processing_gem)
+              # fixup one of our monitored gems as needed, mark
+              # this as being a gem that is being updated so
+              # that we can kill any multi-line attributes
+              t_file.puts GEMS[processing_gem]['line']
+              updating_gem = true
+              GEMS[processing_gem]['added'] = true
+            else
+              # a gem we don't care about - write it out as-is
+              t_file.puts line
+              updating_gem = false
+            end
+          elsif updating_gem and line =~ GEM_ATTRIB_REGEXP
+            # do nothing - remove the multi-line attributes
+          else
+            # anything else... (esp comments)
+            t_file.puts line
+          end
+        }
+      end
+
+      # the code above will only UPGRADE existing gem lines, but if this is our
+      # first run, there will be nothing to upgrade, so loop through the GEMS
+      # for any that are not already added and append them
+      GEMS.each { |name, opts|
+        if ! opts['added']
+          t_file.puts opts['line']
+        end
+      }
+
+      t_file.close
+      FileUtils.mv(t_file.path, GEMFILE)
+    end
+
+  end
+end

data/lib/pdqtest/version.rb

@@ -1,3 +1,3 @@
 module PDQTest
-  VERSION = "0.6.0"
+  VERSION = "0.7.1"
 end

data/pdqtest.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", ">= 1.14.3"
   spec.add_development_dependency "rake", "12.0.0"
   spec.add_development_dependency "rspec", "3.5.0"
-  spec.add_development_dependency "simplecov", "0.12.0"
+  spec.add_development_dependency "coveralls"
   spec.add_development_dependency "fakefs", "0.10.2"
   spec.add_development_dependency "puppet", "4.8.2"
 

data/res/skeleton/Gemfile

@@ -7,7 +7,3 @@ gem 'puppet', '4.9.0'
 gem 'facter', '2.4.6'
 gem 'rubocop', '0.47.1'
 gem 'rspec-puppet-facts', '1.7.0'
-
-# Workaround for PDOC-160 (until gem published)
-gem 'puppet-strings',
-  :git => 'https://github.com/puppetlabs/puppet-strings',

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pdqtest
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Geoff Williams
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-06-29 00:00:00.000000000 Z
+date: 2017-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,19 +53,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 3.5.0
 - !ruby/object:Gem::Dependency
-  name: simplecov
+  name: coveralls
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: fakefs
   requirement: !ruby/object:Gem::Requirement
@@ -223,6 +223,20 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- doc/acceptance_tests.md
+- doc/caching.md
+- doc/development.md
+- doc/enabling_testing.md
+- doc/examples.md
+- doc/hiera.md
+- doc/installation.md
+- doc/puppet_facts.md
+- doc/puppet_module_dependencies.md
+- doc/running_tests.md
+- doc/test_generation.md
+- doc/tips_and_tricks.md
+- doc/troubleshooting.md
+- doc/upgrading.md
 - docker_images/centos/Dockerfile
 - docker_images/centos/Makefile
 - exe/pdqtest
@@ -236,6 +250,7 @@ files:
 - lib/pdqtest/rspec.rb
 - lib/pdqtest/skeleton.rb
 - lib/pdqtest/syntax.rb
+- lib/pdqtest/upgrade.rb
 - lib/pdqtest/util.rb
 - lib/pdqtest/version.rb
 - pdqtest.gemspec