beaker_puppet_helpers 1.0.0

data/beaker_puppet_helpers.gemspec

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |s|
+  s.name        = 'beaker_puppet_helpers'
+  s.version     = '1.0.0'
+  s.authors     = ['Vox Pupuli']
+  s.email       = ['voxpupuli@groups.io']
+  s.homepage    = 'https://github.com/voxpupuli/beaker_puppet_helpers'
+  s.summary     = "Beaker's Puppet DSL Extension Helpers"
+  s.description = 'For use for the Beaker acceptance testing tool'
+  s.license     = 'Apache-2.0'
+
+  s.required_ruby_version = '>= 2.7', '< 4'
+
+  s.files         = `git ls-files`.split("\n")
+  s.require_paths = ['lib']
+
+  # Run time dependencies
+  s.add_runtime_dependency 'beaker', '>= 4', '< 6'
+  s.add_runtime_dependency 'puppet-modulebuilder', '~> 0.3', '< 2'
+end

data/lib/beaker_puppet_helpers/dsl.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module BeakerPuppetHelpers
+  # The DSL methods for beaker. These are included in Beaker.
+  module DSL
+    # @!macro [new] common_opts
+    #   @param [Hash{Symbol=>String}] opts Options to alter execution.
+    #   @option opts [Boolean] :silent (false) Do not produce log output
+    #   @option opts [Array<Fixnum>] :acceptable_exit_codes ([0]) An array
+    #     (or range) of integer exit codes that should be considered
+    #     acceptable.  An error will be thrown if the exit code does not
+    #     match one of the values in this list.
+    #   @option opts [Boolean] :accept_all_exit_codes (false) Consider all
+    #     exit codes as passing.
+    #   @option opts [Boolean] :dry_run (false) Do not actually execute any
+    #     commands on the SUT
+    #   @option opts [String] :stdin (nil) Input to be provided during command
+    #     execution on the SUT.
+    #   @option opts [Boolean] :pty (false) Execute this command in a pseudoterminal.
+    #   @option opts [Boolean] :expect_connection_failure (false) Expect this command
+    #     to result in a connection failure, reconnect and continue execution.
+    #   @option opts [Hash{String=>String}] :environment ({}) These will be
+    #     treated as extra environment variables that should be set before
+    #     running the command.
+    #
+
+    # Runs 'puppet apply' on a remote host, piping manifest through stdin
+    #
+    # @param [Beaker::Host] hosts
+    #   The host that this command should be run on
+    #
+    # @param [String] manifest The puppet manifest to apply
+    #
+    # @!macro common_opts
+    # @option opts [Boolean]  :parseonly (false) If this key is true, the
+    #                          "--parseonly" command line parameter will
+    #                          be passed to the 'puppet apply' command.
+    #
+    # @option opts [Boolean]  :trace (false) If this key exists in the Hash,
+    #                         the "--trace" command line parameter will be
+    #                         passed to the 'puppet apply' command.
+    #
+    # @option opts [Array<Integer>] :acceptable_exit_codes ([0]) The list of exit
+    #                          codes that will NOT raise an error when found upon
+    #                          command completion.  If provided, these values will
+    #                          be combined with those used in :catch_failures and
+    #                          :expect_failures to create the full list of
+    #                          passing exit codes.
+    #
+    # @option opts [Hash]     :environment Additional environment variables to be
+    #                         passed to the 'puppet apply' command
+    #
+    # @option opts [Boolean]  :catch_failures (false) By default `puppet
+    #                         --apply` will exit with 0, which does not count
+    #                         as a test failure, even if there were errors or
+    #                         changes when applying the manifest. This option
+    #                         enables detailed exit codes and causes a test
+    #                         failure if `puppet --apply` indicates there was
+    #                         a failure during its execution.
+    #
+    # @option opts [Boolean]  :catch_changes (false) This option enables
+    #                         detailed exit codes and causes a test failure
+    #                         if `puppet --apply` indicates that there were
+    #                         changes or failures during its execution.
+    #
+    # @option opts [Boolean]  :expect_changes (false) This option enables
+    #                         detailed exit codes and causes a test failure
+    #                         if `puppet --apply` indicates that there were
+    #                         no resource changes during its execution.
+    #
+    # @option opts [Boolean]  :expect_failures (false) This option enables
+    #                         detailed exit codes and causes a test failure
+    #                         if `puppet --apply` indicates there were no
+    #                         failure during its execution.
+    #
+    # @option opts [Boolean]  :future_parser (false) This option enables
+    #                         the future parser option that is available
+    #                         from Puppet verion 3.2
+    #                         By default it will use the 'current' parser.
+    #
+    # @option opts [Boolean]  :noop (false) If this option exists, the
+    #                         the "--noop" command line parameter will be
+    #                         passed to the 'puppet apply' command.
+    #
+    # @option opts [String]   :modulepath The search path for modules, as
+    #                         a list of directories separated by the system
+    #                         path separator character. (The POSIX path separator
+    #                         is ‘:’, and the Windows path separator is ‘;’.)
+    #
+    # @option opts [String]   :hiera_config The path of the hiera.yaml configuration.
+    #
+    # @option opts [String]   :debug (false) If this option exists,
+    #                         the "--debug" command line parameter
+    #                         will be passed to the 'puppet apply' command.
+    # @option opts [Boolean] :run_in_parallel Whether to run on each host in parallel.
+    #
+    # @param [Block] block This method will yield to a block of code passed
+    #                      by the caller; this can be used for additional
+    #                      validation, etc.
+    #
+    # @return [Array<Result>, Result, nil] An array of results, a result
+    #   object, or nil. Check {Beaker::Shared::HostManager#run_block_on} for
+    #   more details on this.
+    def apply_manifest_on(hosts, manifest, opts = {}, &block)
+      block_on hosts, opts do |host|
+        on_options = {}
+        on_options[:acceptable_exit_codes] = Array(opts[:acceptable_exit_codes])
+
+        puppet_apply_opts = {}
+        if opts[:debug]
+          puppet_apply_opts[:debug] = nil
+        else
+          puppet_apply_opts[:verbose] = nil
+        end
+        puppet_apply_opts[:parseonly] = nil if opts[:parseonly]
+        puppet_apply_opts[:trace] = nil if opts[:trace]
+        puppet_apply_opts[:parser] = 'future' if opts[:future_parser]
+        puppet_apply_opts[:modulepath] = opts[:modulepath] if opts[:modulepath]
+        puppet_apply_opts[:hiera_config] = opts[:hiera_config] if opts[:hiera_config]
+        puppet_apply_opts[:noop] = nil if opts[:noop]
+
+        # From puppet help:
+        # "... an exit code of '2' means there were changes, an exit code of
+        # '4' means there were failures during the transaction, and an exit
+        # code of '6' means there were both changes and failures."
+        if [opts[:catch_changes], opts[:catch_failures], opts[:expect_failures], opts[:expect_changes]].compact.length > 1
+          raise(ArgumentError,
+                'Cannot specify more than one of `catch_failures`, ' \
+                '`catch_changes`, `expect_failures`, or `expect_changes` ' \
+                'for a single manifest')
+        end
+
+        if opts[:catch_changes]
+          puppet_apply_opts['detailed-exitcodes'] = nil
+
+          # We're after idempotency so allow exit code 0 only.
+          on_options[:acceptable_exit_codes] |= [0]
+        elsif opts[:catch_failures]
+          puppet_apply_opts['detailed-exitcodes'] = nil
+
+          # We're after only complete success so allow exit codes 0 and 2 only.
+          on_options[:acceptable_exit_codes] |= [0, 2]
+        elsif opts[:expect_failures]
+          puppet_apply_opts['detailed-exitcodes'] = nil
+
+          # We're after failures specifically so allow exit codes 1, 4, and 6 only.
+          on_options[:acceptable_exit_codes] |= [1, 4, 6]
+        elsif opts[:expect_changes]
+          puppet_apply_opts['detailed-exitcodes'] = nil
+
+          # We're after changes specifically so allow exit code 2 only.
+          on_options[:acceptable_exit_codes] |= [2]
+        else
+          # Either use the provided acceptable_exit_codes or default to [0]
+          on_options[:acceptable_exit_codes] |= [0]
+        end
+
+        # Not really thrilled with this implementation, might want to improve it
+        # later. Basically, there is a magic trick in the constructor of
+        # PuppetCommand which allows you to pass in a Hash for the last value in
+        # the *args Array; if you do so, it will be treated specially. So, here
+        # we check to see if our caller passed us a hash of environment variables
+        # that they want to set for the puppet command. If so, we set the final
+        # value of *args to a new hash with just one entry (the value of which
+        # is our environment variables hash)
+        puppet_apply_opts['ENV'] = opts[:environment] if opts.key?(:environment)
+
+        puppet_apply_opts = host[:default_apply_opts].merge(puppet_apply_opts) if host[:default_apply_opts].respond_to? :merge
+
+        file_path = host.tmpfile(%(apply_manifest_#{Time.now.strftime('%H%M%S%L')}.pp))
+        begin
+          create_remote_file(host, file_path, "#{manifest}\n")
+
+          on(host, Beaker::PuppetCommand.new('apply', file_path, puppet_apply_opts), **on_options, &block)
+        ensure
+          host.rm_rf(file_path)
+        end
+      end
+    end
+
+    # Runs 'puppet apply' on default host
+    # @see #apply_manifest_on
+    # @return [Array<Result>, Result, nil] An array of results, a result
+    #   object, or nil. Check {Beaker::Shared::HostManager#run_block_on} for
+    #   more details on this.
+    def apply_manifest(manifest, opts = {}, &block)
+      apply_manifest_on(default, manifest, opts, &block)
+    end
+
+    # Get a facter fact from a provided host
+    #
+    # @param [Beaker::Host, Array<Beaker::Host>, String, Symbol] host
+    #   One or more hosts to act upon, or a role (String or Symbol) that
+    #   identifies one or more hosts.
+    # @param [String] name The name of the fact to query for
+    # @!macro common_opts
+    # @return String The value of the fact 'name' on the provided host
+    # @raise  [FailTest] Raises an exception if call to facter fails
+    def fact_on(host, name, opts = {})
+      raise(ArgumentError, "fact_on's `name` option must be a String. You provided a #{name.class}: '#{name}'") unless name.is_a?(String)
+
+      if opts.is_a?(Hash)
+        opts['json'] = nil
+      else
+        opts << ' --json'
+      end
+
+      result = on host, Beaker::Command.new('facter', [name], opts)
+      if result.is_a?(Array)
+        result.map { |res| JSON.parse(res.stdout)[name] }
+      else
+        JSON.parse(result.stdout)[name]
+      end
+    end
+
+    # Get a facter fact from the default host
+    # @see #fact_on
+    def fact(name, opts = {})
+      fact_on(default, name, opts)
+    end
+  end
+end

data/lib/beaker_puppet_helpers/install_utils.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'beaker/command'
+
+module BeakerPuppetHelpers
+  # Methods to install Puppet
+  class InstallUtils
+    # @api private
+    REPOS = {
+      release: {
+        apt: 'https://apt.puppet.com',
+        yum: 'https://yum.puppet.com',
+      },
+      nightly: {
+        apt: 'https://nightlies.puppet.com/apt',
+        yum: 'https://nightlies.puppet.com/yum',
+      },
+    }.freeze
+
+    # Install official Puppet release repository configuration on host(s).
+    #
+    # @example Install Puppet 7
+    #   install_puppet_release_repo_on(hosts, 'puppet7')
+    #
+    # @param [Beaker::Host] host
+    #   A host to act upon.
+    # @param [String] collection
+    #   The collection to install. The default (puppet) is the latest
+    #   available version.
+    # @param [Boolean] nightly
+    #   Whether to install nightly or release packages
+    #
+    # @note This method only works on redhat-like and debian-like hosts. There
+    #   are no official Puppet releases for other platforms.
+    #
+    def self.install_puppet_release_repo_on(host, collection = 'puppet', nightly: false)
+      repos = REPOS[nightly ? :nightly : :release]
+
+      variant, version, _arch = host['packaging_platform'].split('-', 3)
+
+      case variant
+      when 'el', 'fedora', 'sles', 'cisco-wrlinux'
+        # sles 11 and later do not handle gpg keys well. We can't
+        # automatically import the keys because of sad things, so we
+        # have to manually import it once we install the release
+        # package. We'll have to remember to update this block when
+        # we update the signing keys
+        if variant == 'sles' && version >= '11'
+          %w[puppet puppet-20250406].each do |gpg_key|
+            wget_on(host, "https://yum.puppet.com/RPM-GPG-KEY-#{gpg_key}") do |filename|
+              host.exec(Beaker::Command.new("rpm --import '#{filename}'"))
+            end
+          end
+        end
+
+        url = "#{repos[:yum]}/#{collection}-release-#{variant}-#{version}.noarch.rpm"
+        host.install_package(url)
+      when 'debian', 'ubuntu'
+        url = "#{repos[:apt]}/#{collection}-release-#{host['platform'].codename}.deb"
+        wget_on(host, url) do |filename|
+          host.install_package(filename)
+        end
+        host.exec(Beaker::Command.new('apt-get update'))
+
+        # On Debian we can't count on /etc/profile.d
+        host.add_env_var('PATH', '/opt/puppetlabs/bin')
+      else
+        raise "No repository installation step for #{variant} yet..."
+      end
+    end
+
+    # Determine the Puppet package name
+    #
+    # @param [Beaker::Host] host
+    #   The host to act on
+    # @param [Boolean] prefer_aio
+    #   Whether to prefer AIO packages or OS packages
+    # @return [String] The Puppet package name
+    def self.puppet_package_name(host, prefer_aio: true)
+      case host['packaging_platform'].split('-', 3).first
+      when /el-|fedora|sles|cisco_|debian|ubuntu/
+        prefer_aio ? 'puppet-agent' : 'puppet'
+      when /freebsd/
+        'sysutils/puppet'
+      else
+        'puppet'
+      end
+    end
+
+    # @param [Beaker::Host] host
+    #   The host to act on
+    # @api private
+    def self.wget_on(host, url)
+      extension = File.extname(url)
+      name = File.basename(url, extension)
+      # Can't use host.tmpfile since we need to set an extension
+      target = host.exec(Beaker::Command.new("mktemp -t '#{name}-XXXXXX#{extension}'")).stdout.strip
+      begin
+        host.exec(Beaker::Command.new("wget -O '#{target}' '#{url}'"))
+        yield target
+      ensure
+        host.rm_rf(target)
+      end
+    end
+  end
+end

data/lib/beaker_puppet_helpers/module_utils.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'beaker/command'
+require 'puppet/modulebuilder'
+
+module BeakerPuppetHelpers
+  # Methods to help install puppet modules
+  module ModuleUtils
+    # Install the desired module with the PMT on a given host
+    #
+    # @param [Beaker::Host, Array<Beaker::Host>, String, Symbol] hosts
+    #   One or more hosts to act upon, or a role (String or Symbol) that
+    #   identifies one or more hosts.
+    # @param [String] module_name
+    #   The short name of the module to be installed
+    # @param [String] version
+    #   The version of the module to be installed
+    # @param [String] module_repository
+    #   An optional module repository to install from
+    def install_puppet_module_via_pmt_on(hosts, module_name, version = nil, module_repository = nil)
+      block_on hosts do |host|
+        puppet_opts = {}
+        puppet_opts.merge!(host[:default_module_install_opts]) if host[:default_module_install_opts]
+        puppet_opts[:version] = version if version
+        puppet_opts[:module_repository] = module_repository if module_repository
+
+        on host, Beaker::PuppetCommand.new('module', ['install', module_name], puppet_opts)
+      end
+    end
+
+    # Install local module for acceptance testing
+    #
+    # This uses puppet-modulebuilder to build the module located at source
+    # and then copies it to the hosts. There it runs puppet module install.
+    #
+    # @param [Beaker::Host, Array<Beaker::Host>, String, Symbol] hosts
+    #   One or more hosts to act upon, or a role (String or Symbol) that
+    #   identifies one or more hosts.
+    # @param [String] source
+    #   The directory where the module sits
+    def install_local_module_on(hosts, source = '.')
+      builder = Puppet::Modulebuilder::Builder.new(File.realpath(source))
+      source_path = builder.build
+      begin
+        block_on hosts do |host|
+          target_file = host.tmpfile('puppet_module')
+          begin
+            host.do_scp_to(source_path, target_file, {})
+            install_puppet_module_via_pmt_on(host, target_file)
+          ensure
+            host.rm_rf(target_file)
+          end
+        end
+      ensure
+        File.unlink(source_path) if source_path
+      end
+    end
+  end
+end

data/lib/beaker_puppet_helpers.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# A collection of helpers to make Puppet usage easier with Beaker
+module BeakerPuppetHelpers
+  autoload :DSL, File.join(__dir__, 'beaker_puppet_helpers', 'dsl.rb')
+  autoload :InstallUtils, File.join(__dir__, 'beaker_puppet_helpers', 'install_utils.rb')
+  autoload :ModuleUtils, File.join(__dir__, 'beaker_puppet_helpers', 'module_utils.rb')
+end
+
+require 'beaker'
+Beaker::DSL.register(BeakerPuppetHelpers::DSL)
+Beaker::DSL.register(BeakerPuppetHelpers::ModuleUtils)

data/spec/beaker_puppet_helpers/dsl_spec.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+class ClassMixedWithDSLHelpers
+  include Beaker::DSL::Patterns
+  include BeakerPuppetHelpers::DSL
+
+  def logger
+    @logger ||= RSpec::Mocks::Double.new('Beaker::Logger').as_null_object
+  end
+end
+
+describe BeakerPuppetHelpers::DSL do
+  subject(:dsl) { ClassMixedWithDSLHelpers.new }
+
+  let(:master) { instance_double(Beaker::Host) }
+  let(:agent)  { instance_double(Beaker::Host) }
+  let(:hosts)  { [master, agent] }
+
+  describe '#apply_manifest_on' do
+    before do
+      hosts.each do |host|
+        allow(host).to receive(:tmpfile).and_return('temp')
+        allow(host).to receive(:rm_rf).with('temp')
+        allow(host).to receive(:[]).with(:default_apply_opts)
+      end
+    end
+
+    it 'calls puppet' do
+      expect(dsl).to receive(:create_remote_file).and_return(true)
+      expect(Beaker::PuppetCommand).to receive(:new).and_return('puppet_command')
+      expect(dsl).to receive(:on).with(agent, 'puppet_command', acceptable_exit_codes: [0])
+
+      dsl.apply_manifest_on(agent, 'class { "boo": }')
+    end
+
+    it 'operates on an array of hosts' do
+      the_hosts = [master, agent]
+
+      expect(dsl).to receive(:create_remote_file).twice.and_return(true)
+      the_hosts.each do |host|
+        expect(Beaker::PuppetCommand).to receive(:new).and_return('puppet_command')
+        expect(dsl).to receive(:on).with(host, 'puppet_command', acceptable_exit_codes: [0])
+      end
+
+      result = dsl.apply_manifest_on(the_hosts, 'include foobar')
+      expect(result).to be_an(Array)
+    end
+
+    it 'operates on an array of hosts in parallel' do
+      InParallel::InParallelExecutor.logger = dsl.logger
+      # This will only get hit if forking processes is supported and at least 2 items are being submitted to run in parallel
+      # expect( InParallel::InParallelExecutor ).to receive(:_execute_in_parallel).with(any_args).and_call_original.exactly(2).times
+      the_hosts = [master, agent]
+
+      allow(dsl).to receive(:create_remote_file).and_return(true)
+      allow(Beaker::PuppetCommand).to receive(:new).and_return('puppet_command')
+      the_hosts.each do |host|
+        allow(dsl).to receive(:on).with(host, 'puppet_command', acceptable_exit_codes: [0])
+      end
+
+      result = dsl.apply_manifest_on(the_hosts, 'include foobar')
+      expect(result).to be_an(Array)
+    end
+
+    it 'runs block_on in parallel if set' do
+      InParallel::InParallelExecutor.logger = dsl.logger
+      the_hosts = [master, agent]
+
+      allow(dsl).to receive(:create_remote_file).and_return(true)
+      allow(Beaker::PuppetCommand).to receive(:new).and_return('puppet_command')
+      the_hosts.each do |host|
+        allow(dsl).to receive(:on).with(host, 'puppet_command', acceptable_exit_codes: [0])
+      end
+      expect(dsl).to receive(:block_on).with(anything, { run_in_parallel: true })
+
+      dsl.apply_manifest_on(the_hosts, 'include foobar', run_in_parallel: true)
+    end
+
+    it 'adds acceptable exit codes with :catch_failures' do
+      expect(dsl).to receive(:create_remote_file).and_return(true)
+      expect(Beaker::PuppetCommand).to receive(:new).and_return('puppet_command')
+      expect(dsl).to receive(:on).with(agent, 'puppet_command', acceptable_exit_codes: [0, 2])
+
+      dsl.apply_manifest_on(agent, 'class { "boo": }', catch_failures: true)
+    end
+
+    it 'allows acceptable exit codes through :catch_failures' do
+      expect(dsl).to receive(:create_remote_file).and_return(true)
+      expect(Beaker::PuppetCommand).to receive(:new).and_return('puppet_command')
+      expect(dsl).to receive(:on).with(agent, 'puppet_command', acceptable_exit_codes: [4, 0, 2])
+
+      dsl.apply_manifest_on(agent, 'class { "boo": }', acceptable_exit_codes: [4], catch_failures: true)
+    end
+
+    it 'enforces a 0 exit code through :catch_changes' do
+      expect(dsl).to receive(:create_remote_file).and_return(true)
+      expect(Beaker::PuppetCommand).to receive(:new).and_return('puppet_command')
+      expect(dsl).to receive(:on).with(agent, 'puppet_command', acceptable_exit_codes: [0])
+
+      dsl.apply_manifest_on(agent, 'class { "boo": }', catch_changes: true)
+    end
+
+    it 'enforces a 2 exit code through :expect_changes' do
+      expect(dsl).to receive(:create_remote_file).and_return(true)
+      expect(Beaker::PuppetCommand).to receive(:new).and_return('puppet_command')
+      expect(dsl).to receive(:on).with(agent, 'puppet_command', acceptable_exit_codes: [2])
+
+      dsl.apply_manifest_on(
+        agent,
+        'class { "boo": }',
+        expect_changes: true,
+      )
+    end
+
+    it 'enforces exit codes through :expect_failures' do
+      expect(dsl).to receive(:create_remote_file).and_return(true)
+      expect(Beaker::PuppetCommand).to receive(:new).and_return('puppet_command')
+      expect(dsl).to receive(:on).with(agent, 'puppet_command', acceptable_exit_codes: [1, 4, 6])
+
+      dsl.apply_manifest_on(agent, 'class { "boo": }', expect_failures: true)
+    end
+
+    it 'enforces exit codes through :expect_failures and catch_failures' do
+      expect do
+        dsl.apply_manifest_on(agent, 'class { "boo": }', expect_failures: true, catch_failures: true)
+      end.to raise_error(ArgumentError, /catch_failures.+expect_failures/)
+    end
+
+    it 'enforces merges exit codes from :expect_failures and acceptable_exit_codes' do
+      expect(dsl).to receive(:create_remote_file).and_return(true)
+      expect(Beaker::PuppetCommand).to receive(:new).and_return('puppet_command')
+
+      expect(dsl).to receive(:on).with(agent, 'puppet_command', acceptable_exit_codes: [1, 2, 3, 4, 5, 6])
+
+      dsl.apply_manifest_on(agent, 'class { "boo": }', acceptable_exit_codes: (1..5), expect_failures: true)
+    end
+
+    it 'can set the --parser future flag' do
+      expect(dsl).to receive(:create_remote_file).and_return(true)
+
+      expect(Beaker::PuppetCommand).to receive(:new).with('apply', anything, include(parser: 'future')).and_return('puppet_command')
+
+      expect(dsl).to receive(:on).with(agent, 'puppet_command', acceptable_exit_codes: [0])
+
+      dsl.apply_manifest_on(agent, 'class { "boo": }', future_parser: true)
+    end
+
+    it 'can set the --noops flag' do
+      expect(dsl).to receive(:create_remote_file).and_return(true)
+      expect(Beaker::PuppetCommand).to receive(:new).with('apply', anything, include(noop: nil)).and_return('puppet_command')
+      expect(dsl).to receive(:on).with(agent, 'puppet_command', acceptable_exit_codes: [0])
+
+      dsl.apply_manifest_on(agent, 'class { "boo": }', noop: true)
+    end
+
+    it 'can set the --debug flag' do
+      allow(dsl).to receive(:hosts).and_return(hosts)
+      allow(dsl).to receive(:create_remote_file).and_return(true)
+      allow(dsl).to receive(:on).with(agent, 'puppet_command', acceptable_exit_codes: [0])
+
+      expect(Beaker::PuppetCommand).to receive(:new).with(
+        'apply', anything, include(debug: nil)
+      ).and_return('puppet_command')
+
+      dsl.apply_manifest_on(agent, 'class { "boo": }', debug: true)
+    end
+  end
+
+  describe '#apply_manifest' do
+    it 'delegates to #apply_manifest_on with the default host' do
+      expect(dsl).to receive(:default).and_return(agent)
+      expect(dsl).to receive(:apply_manifest_on).with(agent, 'manifest', { opt: 'value' }).once
+
+      dsl.apply_manifest('manifest', { opt: 'value' })
+    end
+  end
+
+  describe '#fact_on' do
+    it 'retrieves a fact on a single host' do
+      result = instance_double(Beaker::Result, stdout: '{"osfamily": "family"}')
+      expect(dsl).to receive(:on).and_return(result)
+
+      expect(dsl.fact_on('host', 'osfamily')).to eq('family')
+    end
+
+    it 'converts each element to a structured fact when it receives an array of results from #on' do
+      times = hosts.length
+
+      result = instance_double(Beaker::Result, stdout: '{"os": {"name":"name", "family": "family"}}')
+      allow(dsl).to receive(:on).and_return([result] * times)
+
+      expect(dsl.fact_on(hosts, 'os')).to eq([{ 'name' => 'name', 'family' => 'family' }] * times)
+    end
+
+    it 'returns a single result for single host' do
+      result = instance_double(Beaker::Result, stdout: '{"osfamily": "family"}')
+      allow(dsl).to receive(:on).and_return(result)
+
+      expect(dsl.fact_on('host', 'osfamily')).to eq('family')
+    end
+
+    it 'preserves data types' do
+      result = instance_double(Beaker::Result, stdout: '{"identity": { "uid": 0, "user": "root", "privileged": true }}')
+      allow(dsl).to receive(:on).and_return(result)
+
+      structured_fact = dsl.fact_on('host', 'identity')
+
+      expect(structured_fact['uid'].class).to be(Integer)
+      expect(structured_fact['user'].class).to be(String)
+      expect(structured_fact['privileged'].class).to be(TrueClass)
+    end
+
+    it 'raises an error when it receives a symbol for a fact' do
+      expect { dsl.fact_on('host', :osfamily) }
+        .to raise_error(ArgumentError, /fact_on's `name` option must be a String. You provided a Symbol: 'osfamily'/)
+    end
+  end
+
+  describe '#fact' do
+    it 'delegates to #fact_on with the default host' do
+      expect(dsl).to receive(:fact_on).with(anything, 'osfamily', {}).once
+      expect(dsl).to receive(:default)
+
+      dsl.fact('osfamily')
+    end
+  end
+end