How voxpupuli/onceover works
MAIN COMPONENTS
• CLI Interface – Represented by the files inside the “bin” folder (e.g., bin/onceover) and the CLI-related Ruby modules in lib/onceover/cli (e.g., init.rb, run.rb, show.rb, update.rb). This component is the entry point for users invoking onceover commands.
• Core Engine / Control Repository Manager – This is implemented in files such as lib/onceover/controlrepo.rb and related classes in lib/onceover (like testconfig.rb, group.rb, and runner.rb). It reads configuration (onceover.yaml), parses the Puppet control repository structure, and determines what tests to generate.
• Factset Processor – Notice the “factsets” directory containing many JSON files of various operating systems. This module converts factset files into the data needed for compiling catalogs and for generating RSpec tests.
• Test Generation & Runner – The system auto-generates rspec-puppet tests and integrates with Beaker for acceptance testing. Components that support these tests reside in lib/onceover/rspec, features (with Cucumber tests), and the spec directory.
• R10k and Puppetfile Integration – The system uses r10k to clone modules referenced in the Puppetfile. This is indirectly triggered via the control repo and via specific rake tasks (generate_fixtures, generate_vendor_cache) and files like Puppetfile and environment.conf.
• Plugin System – Onceover auto-activates plugins (gems starting with “onceover-”), so include a plugin manager piece that loads these external components.
• Configuration Layer – There is extensive configuration via onceover.yaml (and other manifest/config files) and also support for hiera configuration (hiera.yaml and data directories). This defines which nodes, classes, and groups get tested.
• The CLI interface (user entry point) accepts commands (init, run, show, update) and passes them to the Control Repo Manager.
• The Control Repo Manager parses the onceover.yaml and Puppetfile, gathers factsets from the “factsets” directory, and discovers additional test specifications (from directories “features”, “spec”, “templates” and “pre_conditions”).
• During test execution, there is communication with the underlying Puppet compilation engine (via rspec-puppet), and optionally, modules may be auto-vendored using r10k integration.
• Plugins extend or modify the behavior of various stages (from test generation, to post-test analysis by tools like onceover-codequality or onceover-octocatalog-diff).
Architectural Patterns & Design Principles
• Modular design: Each directory (lib/onceover/cli, lib/onceover/controlrepo, lib/onceover/test, etc.) encapsulates a distinct responsibility.
• Separation of concerns: The CLI layer, the configuration parser, factset management, test generation, and external module management (via r10k) are kept in separate, well-defined modules.
• Extensibility via plugin architecture: The system automatically loads any gem starting with “onceover-“ which enables extension of the core functionalities without modifying the main codebase.
Relevant Technologies, Frameworks, & Libraries
• Ruby (Gemfile, Rakefile, .gemspec)
• rspec-puppet & Beaker – for testing Puppet code
• r10k – for managing and cloning Puppet modules from the Puppetfile
• Cucumber – seen in the “features” directory for acceptance testing scenarios
• YAML & JSON processing – for configuration (onceover.yaml) and factset files
• GitHub Actions and other CI/CD workflows (under .github/workflows) indicate continuous integration support
Additional Details
• That the “spec” and “features” folders represent the test suites – one for traditional unit tests and one for acceptance tests.
• That the “templates” folder feeds into the dynamic generation of configuration and helper files inside a temporary directory (e.g., .onceover)