pdqtest 1.4.1 → 1.9.9beta2

data/doc/pdk.md

@@ -0,0 +1,334 @@
+# PDK Integration
+
+First off, what is PDK? PDK is Puppet's development kit. The bits we are 
+interested in right now are:
+* Validation `pdk validate...`
+* Testing `pdk test...`
+* Packaging `pdk build...`
+
+There's a lot more to PDK then just running simple tests though, PDK includes
+its own version of ruby and various other tools.
+
+On Linux PDK behaves (or at least appears to behave...) like a thin wrapper 
+around ruby, in the same vein as RBENV/RVM. On Windows, things are more involved
+since it needs to install specific system libraries and reference them at
+runtime somehow. This is why running `bundle install` on PDK project in windows
+can cause strange and interesting blow-ups (don't do that!).
+
+## What's the point of PDQTest if we have PDK?
+PDQTest provides an easy way to run acceptance tests using light-weight
+Docker containers which we abuse to the point of treating them _almost_ like 
+VMs in order to extract maximum speed. It offers a different approach to 
+[Beaker](https://github.com/puppetlabs/beaker):
+* Minimal to no project configuration required, just `metadata.json` and a few 
+  other files we setup for you
+* Simple acceptance tests written in BASH or PowerShell
+* Provide _good enough_ (but not perfect) testing:
+    * Generic Ubuntu, Centos, Windows test environments 
+    * Capable of mocking large/slow/networked systems by replacing or installing
+      binaries inside the container at the OS level, eg:
+      * Fake installation of Database server's by mocking the installer your
+        puppet `exec` would call with a simple python script
+      * Network tools such as `realmd` with a simple mock `realm` command
+        written in Python
+      * Complex OS commands that need to report different state between puppet
+        runs can be mocked with Python and a small SQLite database or simple
+        text files (eg the `sysctl` command)
+      * Fake different Unix-like Operating Systems like AIX by subverting the 
+        commands that your puppet code would executes. This is particularly 
+        useful in this case since there are no AIX desktop virtualisation 
+        solutions right now and there probably never will be
+      * See [examples](examples.md) for real-world modules using these
+        techniques
+
+Of course, this will only ever give you an approximation of a real-world system
+but in many cases this is all that's needed. The complexity of setting up a
+100% accurate test environment is a daunting task and one that may never provide
+ROI on the effort spent configuring and maintaining it.
+
+If perfect accuracy is indeed required, then PDQTest is not what you are looking
+for and you should look towards solutions like Beaker or 
+[Kitchen CI](https://kitchen.ci/).
+
+## How does PDQTest work with PDK? Do I have to choose?
+
+No you don't have to choose! PDQTest integrates with PDK by making the minimal
+amount of invasive changes:
+
+### New projects
+New projects should be created using PDK: `pdk new module`. 
+
+This will give you all the PDK versioned files you would ever need. When you run
+`pdqtest init` on a new project created with PDK, we only copy in our own 
+integration files and do not not touch the PDK generated files at all (the ones
+marked 🛠 below), 
+
+### Existing PDQTest projects
+To make upgrading to PDQTest 2.0 + PDK easy for our existing users, we automate
+the workflow normally carried out by `pdk convert`:
+
+We do not include the entire set of files that would have been generated by
+`pdk convert` or `pdk new module`. If you want the full set, you should run 
+one of these commands yourself before `pdqtest init` and they will be left alone
+unless PDK starts writing new files that we are already using.
+
+**metadata.json**
+
+* Enable PDK by adding the fields:
+    * `pdk-version`
+    * `template-url`
+    * `template-ref`
+  The values for these fields are obtained automatically from PDK itself and are
+  consistent with the system installed PDK.
+
+**Gemfile.project**
+
+* Add a reference to the `pdqtest` gem
+
+**Miscellaneous skeletons**
+
+When `pdqtest init` is run, we install a small set of skeleton files in the root
+of your project. This is a one-off operation to get you started. After your 
+module has been marked as PDK compatible, we no longer attempt to update these
+files and you must only manage them using PDK from then-on.
+
+Skeletons are generated on the fly using PDK itself, so they are always 
+up-to-date according to the PDK you have installed on your system.
+
+### Existing non-PDQTest projects
+If you have an existing Puppet project that does not use PDQTest or PDK (eg 
+created by hand or with the old `puppet module generate` command), then the 
+recommended way to enable PDQTest is to first enable PDK by running 
+`pdk convert` and following the wizard.
+
+You may then enable `PDQTest` by running `pdqtest init`.
+
+Depending on the state of your project, you may be able to bypass the 
+`pdk convert` process by just running `pdqtest init` but this isn't recommended
+or supported.
+
+
+### PDQTest directory structure
+These are the files installed, files marked 🛠 are generated by PDK:
+
+```
+├── bitbucket-pipelines.yml
+├── Gemfile 🛠
+├── Gemfile.local
+├── Gemfile.project
+├── .gitignore 🛠
+├── Makefile
+├── make.ps1
+├── .pdkignore 🛠
+├── .puppet-lint.rc
+├── Rakefile 🛠
+├── spec
+│   ├── default_facts.yml 🛠
+│   ├── fixtures
+│   │   ├── hieradata
+│   │   │   └── test.yaml
+│   │   └── hiera.yaml
+│   └── spec_helper.rb 🛠
+└── .travis.yml
+```
+
+The remaining files are specific to PDQTest - notably:
+* `.travis.yml` - Complete test suite for Linux modules
+* `bitbucket-pipelines.yaml` - RSpec testing only 
+* `.puppet-lint.rc` - Make lint errors test failures, ignore double quotes, etc
+* `Makefile` - Essential launch script for Linux
+* `make.ps1` - Essential launch script for Windows
+* `spec/fixtures/hiera.yaml` - Mock system-wide `hiera.yaml` file
+* `spec/fixtures/hieradata/test.yaml` - Mock system-wide hieradata
+* `Gemfile.project` - Used to enable the PDQTest gem (and any others you need)
+* `Gemfile.local` - Transient file created at runtime by `Makefile` or
+  `make.ps1` to enable the PDQTest gem at runtime. This is a vital integration
+  point, see details below
+* `.gitignore` - PDK has a massive list of files to ignore for new projects so
+  these are imported
+
+
+## Why are the launch scripts essential/How does the PDQTest gem load itself?
+PDK provides its own `Gemfile` to select the gems available at runtime. There
+are hooks in this file to load additional configuration from two locations:
+* `~/.gemfile`
+* `YOUR_PROJECT/Gemfile.local`
+
+We support side-by-side installation of all versions of PDQTest so that users
+are not forced to upgrade when they are not ready to, so we need a per-project
+way to load our gem into the bundle. `Gemfile.local` is perfect for this but we
+are not supposed to store permanent data in there according to PDK's generated
+`.gitignore`.
+
+The simplest way to workaround this issue is for us to create a symlink from 
+`Gemfile.project` to `Gemfile.local` at runtime and we _must_ use our launch
+scripts to do this since we are unable to use any Ruby code to do this trick
+since we are not yet in the bundle.
+
+For this reason, you **must** launch PDQTest using the provided `Makefile` or
+`make.ps1` scripts, at least initially.
+
+For further background see: 
+* [PDK-1177](https://tickets.puppetlabs.com/browse/PDK-1177) and 
+* [#50](https://github.com/declarativesystems/pdqtest/issues/50) 
+
+## When developing PDQTest, your version number **must** match a released version
+_This should only affects PDQTest developers - for posterity..._
+
+Due to some strange hackery between `pdk bundle` and `bundle exec` you have one
+more gotcha when it comes to using developing PDQTest and thats that the version
+number of the gem you build *MUST* match a released version of the gem on 
+rubygems.org otherwise `bundle exec` will barf with errors like this:
+
+```shell
+$ bundle exec pdqtest
+Could not find hiera-3.4.5 in any of the sources
+Run `bundle install` to install missing gems.
+```
+
+There seems no other way to fix this other than building the development gem 
+with a version matching an existing release. The gem then needs to be installed
+using `gem install ...` and it will then magically start working. Using other
+gem tricks like setting `:path` will appear to work but fail when `bundle exec`
+is called. The other approach of trying to run everything with 
+`pdk bundle exec pdqtest` fails with various errors depending what platform your
+on, presumably because `pdqtest` runs `pdk` command as part of its tests.
+
+The final final caveat of this approach is that the PDQTest gem dependencies are
+pinned at whatever the _real_ release uses, so if any were changed or added they
+need to be temporarily added to `Gemfile.project`
+
+The above works on Linux... For windows there is also the situation where:
+* PDK vendors its own gems that magically appear
+* PDK can only use "published" gems(specs?) it downloads - or appears to
+* when you go to `bundle install` without using PDK you blow up the lock 
+  file
+* When you `bundle exec pdqtest` you get the above error because _something_
+  uses the old one `gemspec`
+* The answer seems to be:
+    1. use `gem 'pdqtest', :path=>'c:/vagrant/pdqtest'` in `Gemfile.local`
+    2. `pdk bundle install`
+    3. `bundle update pdqtest` - yes even though your not supposed to...
+    4. `bundle exec pdqtest` - now it should work... why is beyond me
+* If you still have errors:
+    1. `bundle install`
+    2. `rm Gemfile.lock`
+    3. `pdk bundle install` - working?
+
+Somtimes you just have to upload the whole gem file as a pre-release object:
+* Version set to x.x.xWHATEVER
+* `gem push pdqtest-x.x.xWHATEVER.gem`
+* `gem install pdqtest --pre`
+
+
+If your just want to use PDQTest, you will hopefully never have to worry about
+this... On the other hand, if this all sounds confusing... That's because it is!
+
+## What happens when I upgrade PDQTest?
+When a new version of PDQTest is released, upgrade by running:
+
+```shell
+gem install pdqtest
+cd /your/project
+pdqtest upgrade
+pdk bundle install
+```
+
+This updates:
+* Project gems in `Gemfile.project` (currently `pdqtest` and `puppet-strings`)
+* Our CI and CLI integrations:
+    * `Makefile`
+    * `make.ps1`
+    * `.travis.yml`
+    * `bitbucket-pipelines.yml`
+    
+The final `pdk bundle install` command upgrades PDK's bundle to the include our
+update and is critical to making the whole process work.
+
+## What happens when I upgrade PDK?
+PDK operates independently from PDQTest and maintains its own files. Your free
+to run `pdk update` to upgrade the your files to the latest PDK templated ones
+at any time.
+
+To protect PDQTest files from alteration (notably `.travis.yml` and
+`bitbucket-pipelines.yml`) we merge them with any existing `.sync.yml` to
+prevent churn.
+
+If you have further customisations to PDK controlled files your options are:
+* Use git to revert any change by PDK
+* Use `.sync.yml` to influence file (re)generation
+  [blog](https://puppet.com/blog/guide-converting-module-pdk)
+  [reference](https://github.com/puppetlabs/pdk-templates) 
+  [example](https://github.com/puppetlabs/puppetlabs-apt/blob/master/.sync.yml) 
+
+## How do I use PDK with PDQTest installed? What can and can't I do?
+You can run any `pdk` command as described in the PDK documentation. PDQTest
+does not stop you running anything. If you find this not to be the case please
+open a [ticket](https://github.com/declarativesystems/pdqtest/issues)
+
+## How do PDQTest lifecycle tests relate to PDK?
+
+| PDQTest   | PDK                            |
+| ---       | ---                            |
+| `syntax`  | `pdk validate metadata,puppet` |
+| `rspec`   | `pdk test unit`                |
+| `build`   | `pdk build --force`            |    
+
+* Previous `lint` subcommand was removed in PDQTest 2.0 as its now covered by 
+  `syntax`
+
+## What actually happens when I run PDQTest?
+
+`bundle exec pdqtest all` is the default target executed by `make` and 
+`.\make.ps1`. There are a few other targets that let you skip parts of the build
+or run individual parts. The complete run looks like this: 
+
+1. `pdk validate 'metadata,puppet'`
+2. Install modules listed in the `metadata.json` file using R10K against a 
+   temporary `Puppetfile` at `Puppetfile.pdqtest`
+3. Generate a `.fixtures.yml` file based on `metadata.json` 
+   Currently impacted by 
+   [#47](https://github.com/declarativesystems/pdqtest/issues/47)
+4. `pdk test unit`
+5. Run all acceptance tests
+6. `puppet strings generate --format=markdown` to generate `REFERENCE.md`
+7. `pdk build --force` to generate your forge package
+
+At each stage of the process, we output emoji's to keep you informed of
+progress. Any failure prevents running the next phase of testing and lint errors
+are considered failures.
+ 
+### Technical details (code)
+If anyone knows a better way to do this, I'd love to hear about it:
+[PDQTest lifecycle](https://github.com/declarativesystems/pdqtest/blob/master/exe/pdqtest)
+[PDK Wrapper](https://github.com/declarativesystems/pdqtest/blob/master/lib/pdqtest/pdk.rb)
+
+## PDQTest is pretty slow!
+This is a side effect of having to shell out to run PDK via system calls. 
+There's really no other way to do this while maintaining full PDK compatiblity 
+(if you know different, please enlighten me).
+
+That said you might just want to run syntax and lint tests and acceptance tests
+as quick as possible, in which case run:
+
+**Linux**
+```
+make fast
+```
+
+**Windows**
+```json
+.\make.ps1 fast
+```
+
+This runs the syntax and lint tests using the original `puppet-syntax` and
+`puppet-lint` libraries. We can't guarantee PDK identical behaviour or 
+compatibility when used this way but hey... its faster.
+
+## How do I automatically fix up my lint errors?
+
+With PDK!:
+
+```shell
+pdk validate -a
+```

data/doc/puppet_facts.md

@@ -1,10 +1,52 @@
 # 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:
+PDQTest uses PDK's `spec/default_facts.yml` to add facts to acceptance tests as
+external facts.
+
+During test setup, PDQTest will installing the file at one of:
+* `/etc/puppetlabs/facter/facts.d/default_facts.yaml`
+* `C:\ProgramData\PuppetLabs\facter\facts.d`
+
+PDK uses the file as part of the `pdk test unit` command. This way you have a 
+consistent set of facts for both RSpec and acceptance testing, in the file that
+PDK expects them to be in.
+
+## 🐉 Differences from PDK 🐉
+The above behaviour is not how PDK intends this file to be used as some other 
+mechanism is supposed to be used for acceptance tests (see PDK manual).
+
+It's pretty rare to actually need `spec/default_facts.yml` unless your doing
+unit testing since you can insert custom facts as part of your test setup.
+
+Be aware that PDK sets a few facts to specific values that we will pick up and
+use in your acceptance tests:
+
+```yaml
+concat_basedir: "/tmp"
+ipaddress: "172.16.254.254"
+is_pe: false
+macaddress: "AA:AA:AA:AA:AA:AA"
+```
+
+You would need to use a forked version of the PDK templates to fix these
+properly, but your using the structured facts anyway so it makes no difference,
+right...?
+
+## Older versions
+PDQTest < 2.0 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`.
+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
+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

@@ -1,29 +1,47 @@
 # Puppet module dependencies
-To test your puppet code, PDQTest needs to configured to obtain any modules the code being tested depends on.
+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.
+Dependencies on public forge modules must be specified in your module's 
+`metadata.json` file. When tests are run, we will use this to generate a 
+temporary `Puppetfile` at `Puppetfile.pdqtest` which we will then install into
+`spec/fixtures/modules` using R10K.
+
+When RSpec tests are run using PDQtest a `.fixtures.yml` file will be generated
+for you based on the module metadata (with PDK standalone you must update this
+file manually). We will then execute `pdk test unit` on your behalf which will
+install any additional modules from git that can't be specified in 
+`metadata.json`.
+
+This means you get a complete set of modules in `/spec/fixtures/modules` by the
+time you come to run acceptance tests.
 
 ### Private modules (from git)
-If you need to download modules from git, then you must populate the `fixtures` section of `fixtures.yml`, eg:
+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:
+  repositories:
+    camera_shy:
+      repo: "git://git.megacorp.com/puppet/camera_shy"
+      ref: "2.6.0"
 ```
 
-
-## .fixtures.yml
-There is no need to maintain a `.fixtures.yml` file and the presence of this file when using `pdqtest` is an error (note the leading period)
+It is an error to define the same module in both `metadata.json` and 
+`.fixtures.yml` and the results of doing this are undefined:
+* Always use `metadata.json` for public forge modules and we will update 
+  `.fixtures.yml` based on it
+* Modules from git should _only_ be defined in `.fixtures.yml`
 
 ## 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.
-* We convert the dependencies from `metadata.json` to a temporary puppetfile store at `.Puppetfile.pdqtest` which is then installed using r10k
-* Previous versions of pdqtest configured the r10k cache via `.r10k.yaml` which caused #44. To fix this, we now use the default r10k cache dir at ~/.r10k/cache and don't write
-  `.r10k.yaml` any more. You should remove any `.r10k.yaml` files from your project unless you need it for something specific.
+* The file format of `.fixtures.yml` and `fixtures.yml` for specifing git 
+  repositories is identical
+* Previous versions of pdqtest configured the r10k cache via `.r10k.yaml` which
+  caused [#44](https://github.com/declarativesystems/pdqtest/issues/44). To fix
+  this, we now use the default r10k cache dir at `~/.r10k/cache` and don't write
+  `.r10k.yaml` any more. You should remove any `.r10k.yaml` files from your 
+  project unless you need it for something specific.

data/doc/running_tests.md

@@ -1,38 +1,58 @@
 # Running tests
+
+## Important
+You **must** use the provided launch scripts `Makefile` or `make.ps1` to run
+PDQTest, at least for the first time. See [PDK integration](pdk.md) for more
+information.
+
+## Quickstart
 If you just want to run all tests:
 
+**Linux**
 ```shell
 make
 ```
 
-Alternatively, you can choose to run individul test phases directly:
-
-## All tests (excludes documentation)
-
+**Windows**
 ```shell
-bundle exec pdqtest all
+.\make.ps1
 ```
 
-### Syntax
+Alternatively, you can choose to run different groups of tests by supplying a
+target from this table:
 
-```shell
-bundle exec pdqtest syntax
-```
+| Target        | Description                                                            | PDK compatible? |
+| ---           | ---                                                                    | ---             |
+| all           | lint, syntax, rspec, acceptance, strings, build                        | yes             |
+| fast          | lint, syntax, acceptance, strings, build                               | no              |
+| shell         | run acceptance tests and print command to get a shell in the container | yes             |
+| shellnopuppet | open a shell in the test container                                     | yes             |
+| logical       | syntax, lint                                                           | yes             |
+
+* PDK compatible means we run the `pdk` command for this part of the lifecycle
 
-### Lint
 
+**Example**
+
+**Linux**
 ```shell
-bundle exec pdqtest lint
+make fast
 ```
 
-### RSpec
+**Windows**
+```shell
+.\make.ps1 fast
+```
 
+## Only run acceptance tests
 ```shell
-bundle exec pdqtest rspec
+bundle exec pdqtest acceptance
 ```
 
-### Acceptance
 
+## See also
+
+PDQTest help:
 ```shell
-bundle exec pdqtest acceptance
+bundle exec pdqtest --help
 ```

data/doc/test_generation.md

@@ -1,25 +1,12 @@
 # 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
+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.
 
 ## Acceptance tests
 
-Generate boilerplate files for each example found (including those without a magic marker):
+Generate boilerplate files for each example found (including those without a 
+magic marker):
 
 ```shell
 pdqtest generate_acceptance
@@ -31,4 +18,9 @@ Generate boilerplate files for one specific example:
 pdqtest generate_acceptance examples/mynewthing.pp
 ```
 
-Note:  This will also create examples/mynewthing.pp if you haven't created it yet
+This will also create examples/mynewthing.pp if you haven't created it yet.
+
+
+## RSpec tests
+PDQTest < 2.0 includes rspec test generation. This functionality is replaced by
+PDK in later versions.

data/doc/tips_and_tricks.md

@@ -1,13 +1,22 @@
 # 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
+* 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` or `#@PDQTestWin` from the 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:
+* 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
+  * 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:
+  * Install python scripts to mock database servers using SQLite... 😉

data/doc/troubleshooting.md

@@ -1,9 +1,20 @@
 # 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
-* If your `pdqtest` command changes version randomly depending which directory your in and you are using `rvm` its probably because `rvm` overrides `cd` and does strange things. You can probably turn this off. Alternatively, use `rbenv`
-* 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.
+* 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
+* If your `pdqtest` command changes version randomly depending which directory
+  your in and you are using `rvm` its probably because `rvm` overrides `cd` and
+  does strange things. You can probably turn this off. Alternatively, use 
+  `rbenv`
+* 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` (changed in 2.0.0)
+* 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` or `#@PDQTestWin`
+* 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.