Address Issue OctopusDeploy#177, Hyper-V networking (OctopusDeploy#197)

* Hyper-v changes in response to OctopusDeploy#177. Extra documentation
* couple of typos
* Move setting of OctopusDSCVMSwitch env var into common code (should fix issue OctopusDeploy#176)
* Should probably include the commit to build-hyperv.ps1 as well
* Address PR feeedback
* debug output to troubleshoot intermittent scenario_08 problem
* Upgrade vagrant-dsc to 2.0.2

Author: stopthatastronaut

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # How to Contribute
 Thank you for going to the effort of contributing some code.
 
-If you've found a bug or something isn't working, please quickly check the issues in 
+If you've found a bug or something isn't working, please quickly check the issues in
 our [main issue repository](https://github.com/OctopusDeploy/Issues).
 
 If your change is small or you have already made the change, please go ahead and submit a pull request.
@@ -10,4 +10,6 @@ For other changes, please raise an issue first to check that the change aligns w
 
 If your pull request or proposed change is for a bug that is causing problems for you, please also [contact support](http://octopusdeploy.com/support) referencing your pull request to make sure it gets prioritized properly. They may also be able to find a work around in the meantime.
 
-If you have an idea or a feature request, please post it to [our UserVoice site](http://octopusdeploy.uservoice.com) so others can vote for it. 
+If you have an idea or a feature request, please post it to [our UserVoice site](http://octopusdeploy.uservoice.com) so others can vote for it.
+
+If you're a keen contributor, a regular OctopusDSC user or just curious, please feel free to join us in the `#octopusdsc` channel at our [Community Slack](https://join.slack.com/t/octopususergroup/shared_invite/enQtNDcyNjM3OTczNzAxLTU0MjI3YmIyMDc1MzdmYjk3OTYzZGY4ZTI2NTcwMzY3OGJkZTExYTVkNThjYjM1MWE2YjlmNWQyMmQwNzRmMjk)

README.md

@@ -59,6 +59,7 @@ To run just the scenarios locally, follow these steps:
 5. If you want to test locally using Hyper-V
     - Run `vagrant plugin install vagrant-dsc`
     - Run `vagrant plugin install vagrant-winrm-syncedfolders`
+    - Optionally set the environment variable `OctopusDSCVMSwitch`, to use a specific Hyper-V switch by name. For example, for older Hyper-V systems, you may wish to set this to 'External Connection'
     - Run `build-hyperv.ps1`. This will run all the scenarios under the [Tests](Tests) folder.
 6. If you want to test using AWS
     - Run `vagrant plugin install vagrant-aws`
@@ -78,6 +79,19 @@ To run just the scenarios locally, follow these steps:
     - Run `build-azure.ps1`. This will run all the scenarios under the [Tests](Tests) folder.
 8. Run `vagrant destroy -f` or the appropriate `cleanup-*.ps1` once you have finished to kill the virtual machine.
 
-Tests are written in [ServerSpec](serverspec.org), which is an infrastructure oriented layer over [RSpec](rspec.info).
+Each of the `build-*` scripts can take parameters at the command prompt.
+
+These are generally designed to tighten the feedback loop during development, since the VM-based integration test phase can be quite time consuming.
+
+| Parameter                     | Type      | Default Value    | Description |
+| ----------------------------- | --------- | ---------------- | -------------------------------------------- |
+| `-SkipPester`                 | Switch    | False            | Skips the Pester and PSScriptAnalyzer unit tests, going straight to the slower, VM-based integration tests.            |
+| `-ServerOnly`                 | Switch    | False            | Runs only the Server-related integration scenarios. |
+| `-TentacleOnly`               | Switch    | False            | Runs Server scenarios 14 and 15 to install and configure an Octopus Deploy server instance, then moves on to Tentacle-related tests (which require a server to be present). |
+| `-OctopusVersion`             | String    | `vLatest`        | Allows you to run tests against a specific version of Octopus Deploy. Does not apply to 'Scenario_07', which installs an older version in order to test upgrading. |
+| `-RetainOnDestroy`            | Switch    | False            | Retains the virtual machine after the tests finish, so you can examine the state of the VM. |
+| `-debug`                      | Switch    | False            | Adds the `--debug` flag to the vagrant invocation, allowing you to step through the process and examine machine state before moving on. |
+
+Tests are written in [ServerSpec](serverspec.org), which is an infrastructure oriented layer over [RSpec](rspec.info) and use our [octopus-serverspec-extensions](https://github.com/OctopusDeploy/octopus-serverspec-extensions) project for octopus-specific tests.
 
 When creating a PR, please ensure that all existing tests run succesfully against VirtualBox, and please include a new scenario where possible. Before you start, please raise an issue to discuss your plans so we can make sure it fits with the goals of the project.

Tests/Scenarios/Server_Scenario_08_Upgrade.ps1

@@ -8,7 +8,10 @@ Configuration Server_Scenario_08_Upgrade
     $pass = ConvertTo-SecureString "SuperS3cretPassw0rd!" -AsPlainText -Force
     $cred = New-Object System.Management.Automation.PSCredential ("OctoAdmin", $pass)
 
+    Write-Output "Using ApiKey $($ENV:OctopusApiKey)" # debugging an intermittent issue in Scenario_08 throwing exception 'Cannot bind argument to parameter 'String' because it is null'
+
     $pass = ConvertTo-SecureString $ENV:OctopusApiKey -AsPlainText -Force
+
     $apiCred = New-Object System.Management.Automation.PSCredential ("ignored", $pass)
 
     Node "localhost"

Tests/powershell-helpers.ps1

@@ -55,8 +55,8 @@ function Test-CustomVersionOfVagrantDscPluginIsInstalled() {  # does not deal we
 
   write-host "It doesn't appear that you've got the custom Octopus version of the vagrant-dsc plugin installed" -foregroundcolor red
   write-host "Please download it from github:"
-  write-host "  irm https://github.com/OctopusDeploy/vagrant-dsc/releases/download/v2.0.1/vagrant-dsc-2.0.1.gem -outfile vagrant-dsc-2.0.1.gem"
-  write-host "  vagrant plugin install vagrant-dsc-2.0.1.gem"
+  write-host "  irm https://github.com/OctopusDeploy/vagrant-dsc/releases/download/v2.0.1/vagrant-dsc-2.0.2.gem -outfile vagrant-dsc-2.0.2.gem"
+  write-host "  vagrant plugin install vagrant-dsc-2.0.2.gem"
   exit 1
 }
 
@@ -115,6 +115,11 @@ Function Set-OctopusDSCEnvVars {
     [string]$OctopusVersion
   )
 
+  if(-not $env:OctopusDSCVMSwitch)
+  {
+    $env:OctopusDSCVMSwitch = 'Default Switch' # Override this variable to use a different switch in hyper-v
+  }
+
   # Clear the OctopusDSCTestMode Env Var
   if(Test-Path env:\OctopusDSCTestMode)  {
     get-item env:\OctopusDSCTestMode | Remove-Item

build-hyperv.ps1

@@ -43,11 +43,11 @@ else {
 }
 Write-Output "Hyper-V installed - good."
 
-if (-not (Get-VMSwitch -SwitchType External -Name 'External Connection' -ErrorAction SilentlyContinue)) {
-    Write-Output "Please create an external virtual switch named 'External Connection'."
+if (-not (Get-VMSwitch -Name $env:OctopusDSCVMSwitch -ErrorAction SilentlyContinue)) {
+    Write-Output "Could not find a Hyper-V switch called $($env:OctopusDSCVMSwitch)"
     exit 1
 }
-Write-Output "External virtual switch detected - good."
+Write-Output (@("Hyper-V virtual switch '", $env:OctopusDSCVMSwitch, "' detected - good.") -join "")
 
 Test-CustomVersionOfVagrantDscPluginIsInstalled
 Test-PluginInstalled "vagrant-winrm-syncedfolders"

vagrantfile

@@ -80,7 +80,7 @@ Vagrant.configure(VAGRANT_FILE_API_VERSION) do |config|
     config.vm.provider "hyperv" do |v, override|
       override.vm.box = "OctopusDeploy/dsc-test-server-windows-server-1803"
       override.vm.box_url = "https://s3-ap-southeast-2.amazonaws.com/octopus-vagrant-boxes/vagrant/json/OctopusDeploy/hyperv/dsc-test-server-windows-server-1803.json"
-      config.vm.network "public_network", bridge: "External Connection"
+      config.vm.network "public_network", bridge: ENV['OctopusDSCVMSwitch']
       v.memory = 4096
       v.maxmemory = 4096
       v.cpus = 2