Add a beginner guide to Beaker acceptance testing

[miharp]

What

Expands the DevKit "Acceptance Testing with Beaker" page from an 8-line stub (which only linked to voxpupuli-acceptance) into a full beginner-friendly guide.

Closes #304.

Contents

• Prerequisites — a hypervisor (Docker by default), a current Ruby (via a version manager such as rbenv/rvm/mise), and the system_tests Bundler group, plus a macOS/Apple Silicon local-run note. The common newcomer traps are called out explicitly.
• Setting up the framework — the three pieces that wire voxpupuli-acceptance into a module (the system_tests Gemfile group, spec_helper_acceptance.rb, and the Rakefile).
• Anatomy of a test — the apply_manifest two-run idempotency idiom (with idempotency defined plainly), a worked chrony example that mirrors the real puppet-chrony acceptance test, and the shared-example shortcuts.
• Choosing a platform (setfiles), running the suite, a BEAKER_* environment-variable reference, debugging a failure, running in CI (including a pointer to the shared gha-puppet reusable workflow that most Vox Pupuli modules use, with a note on the modulesync-managed ci.yml), and customizing nodes.
• Beginner-facing terms (catalog, gem, hypervisor, rake, fixtures, apply_manifest, setfile, the package resource type) are linked or glossed on first use.

Validation

Every command in the guide was validated end to end:

1. In CI — wired voxpupuli-acceptance into a real module and ran rake beaker in GitHub Actions (Docker, almalinux9-64, openvox8), green.
2. Locally — ran the full flow against the upstream voxpupuli/puppet-chrony module on macOS + Docker: bundle install, puppet-metadata setfiles, and bundle exec rake beaker.

The worked example was run as written against real OpenVox containers on both almalinux9-64 and debian12-64 → 4 examples, 0 failures each. Local testing also pinned down two adjustments the worked example needs: chrony won't apply cleanly inside a Docker container without options => '-F 0 -x' (which disable clock-stepping and the seccomp filter), and the service is named chronyd on RHEL-family vs chrony on Debian-family, so the example selects it from os.family.

That validation is also where the guide's details were pinned down: the openvox8 collection name (vs. upstream puppet8), the puppet-metadata setfiles command (the older setfiles is now a deprecated alias), and the macOS/Apple Silicon and Ruby-version prerequisites.

Notes

The page lives in _ecosystem_8x and is surfaced via the existing _latest symlink. The nav entry is renamed from "Acceptance Testing" to "Acceptance Testing with Beaker" to match the page title.

[binford2k]

This is fine the way it is, but I do have a few suggestions to make the whole set feel more cohesive.

[binford2k]

maybe worth calling out that macOS has deprecated system ruby, even though they've not actually removed it yet.

[binford2k]

actually, this comment makes me realize that the setup page should talk more about ruby versions. Filed #382

[binford2k]

Could we maybe put these into a <details> disclosure widget or something? It's not super clear on first read which parts are the "two extra wrinkles".

Either that, or move it to the end of the prereqs section.

[binford2k]

I think the with/without discussion should be moved to setup.md and this section should only say something like

You'll need the system_tests bundler group, but you can omit development and release if you want to keep things lean.

filed #383

[binford2k]

Is it worth mentioning the modules which require two runs to reach idempotency? (the ones that install something used to generate a fact that is then used on the next run to specify state)

Or is that a "by the time you have to do this, you'll know enough to figure it out" thing?