Rewrite the test suite and fix seven driver bugs

[tas50]

What this does

Replaces the unit test suite from the ground up and fixes the bugs that writing it uncovered.

The previous suite was one Minitest file with a single assertion (api_version == 2), and it could not run at all — the test bundle group pulled in Berkshelf, Vagrant, Dokken and Inspec, so bundle install failed to resolve before a single assertion ran.

• RSpec: 103 examples, replacing the Minitest/mocha/minitest-stub-const stack
• Pester 5: 35 tests, ported from Pester 3 syntax and extended
• 7 bug fixes, each with a regression test
• YARD on the public API — 100% documented, no warnings
• Heavy plugins moved to an integration bundle group so unit work installs fast

How the specs are built

The driver's job is turning configuration into PowerShell and running it in the right order. So the specs fake only the outer boundary — the Train connection — and let everything above it run for real. Each command travels the genuine run_ps → wrap_command → encode_command path, and the fake decodes the -encodedcommand payload back to readable PowerShell:

driver.create(state)

expect(connection.scripts_matching(/New-KitchenVM/).first)
  .to include(%{SwitchName = "Default Switch"})

Stubbing run_ps instead would assert that the driver called a mock, not that it generated the right PowerShell.

Bugs fixed

#	Bug	Impact
1	powershell.rb used Base64.strict_encode64 without requiring base64	Worked only because Train requires it first. base64 is a bundled gem from Ruby 3.4 on, so this was one dependency change away from breaking every run_ps call. Now required and declared in the gemspec.
2	update_state did @vm["Id"] on nil	Get-VmDetail returning nothing surfaced as undefined method '[]' for nil instead of anything actionable.
3	Additional disks ignored remote_vm_path	On a remote host they were created under the local kitchen root, where the Hyper-V server cannot see them — unlike the differencing disk.
4	destroy left a stale state[:id]	Returning early when the VM was already gone kept the id in the state file permanently.
5	Support script uploaded on the local backend	The local backend reads the in-gem copy via base_script_path and never looks at the uploaded one.
6	between? on raw config values	A number quoted in kitchen.yml raised comparison of String with 1 failed rather than the intended validation message. Both memory and VLAN bounds now coerce first.
7	local_script_path kept its .. segments; differencing_disk_exists returned nil	Cosmetic, but the unnormalized path showed up in every debug log.

The Pester port is semantic, not cosmetic

Pester 5 changed three things that each silently produce tests which pass no matter what the code does. Ported literally, the old tests would have asserted nothing:

• Discovery is separate from execution. The old tests call New-KitchenVM in the Describe/Context body, which runs during discovery — before any Mock is active.
• Should -Invoke defaults to -Scope It and counts only invocations from the same It block. Calls made in a BeforeAll are not counted.
• -Times N means "at least N" since Pester 4, so -Times 0 can never fail. Roughly half the original assertions are "should not have been called" — all now use -Exactly.

spec/powershell/TestHelper.ps1 supplies mockable cmdlet shims: Pester builds CommandMetadata for a mocked command, which forces resolution of every parameter type, and the stub module's signatures name types like [Microsoft.HyperV.PowerShell.VirtualMachine] that only exist on a real Hyper-V host.

Verification

Both suites were run locally, and mutation-tested to confirm they can actually fail:

Mutation	Result
Drop the $VlanId -ne $null guard	3 Pester tests fail
Drop the iso_path guard	1 RSpec example fails
Revert the stale-state[:id] fix	1 RSpec example fails

rspec   103 examples, 0 failures
pester  35 passed, 0 failed        (pwsh 7.5.4 / Pester 6.1.0)
yard    100.00% documented, no warnings
rubocop 12 files inspected, no offenses
rake    exit 0

Both suites run on any platform — neither needs Hyper-V, Windows, or an elevated shell.

Rake tasks

rake yard, rake yard:stats, rake yard:server, and rake pester are added. None are prerequisites of rake default, so documentation coverage and PowerShell availability cannot fail a build. rake test and rake unit remain as aliases for rake spec, so the shared CI workflow is unaffected.

Notes for review

• The Pester files moved from spec/support/ to spec/powershell/. spec/support/ is now RSpec's auto-loaded Ruby helper directory, so the two could not share it.
• .rubocop.yml no longer excludes spec/**/* — the specs lint clean.
• CONTRIBUTING.md had a stale claim that bundle exec rake changelog exists. It never did, and github_changelog_generator is not in the Gemfile; release-please handles the changelog.
• CI workflows are untouched. support/ci/windows_ci.bat did need updating — it ran invoke-pester ./spec directly and installed Pester unversioned.
• Labelled feat: so release-please cuts a minor bump — the seven fixes change runtime behavior and should not ship silently.

🤖 Generated with Claude Code