puppet-unit-tests 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65355d1254f33d3c4a19d2407ca278b7c3e29e7b1240f9a2e5489e62eb90eeb7
-  data.tar.gz: 9823aac83e42222e742682ab4f95316f62e2ba4d9651ef3c7bbbeba1564e828a
+  metadata.gz: 9ac6abaec554f872d858b6cdbea38ca53c746127f2106d2707556552f5cd4e8d
+  data.tar.gz: a2e17acfd871c41c208de48b941132ff585b5912a1e3e51e75f532e9e15c2392
 SHA512:
-  metadata.gz: fe22c553caef295c6ce078abd9bd19329671db34cfa525041868dabe3a0dfb6f785f45792f548d6fba24aa67e40add6095a68905b065d7b4e23e15d38a532197
-  data.tar.gz: 807ed15b9a99e640ad4fe77f8c619806c11d7a27eed56defef1078a3c52517d7dcd88498df9d6d392612a42e4b37b5219fa2f4430a2f76ce79656038209b6f98
+  metadata.gz: cff991850a20eef0483e309a21cd146138fc5f78c28ea8629c65f1b999d8bd3321a9888a9971cfca1125fcfd46518efe106aadf53011b02fd821cdeeee5750a0
+  data.tar.gz: 25322cbc2df1351fc9b489494492407a4cdb83c9db1108ef21b970ce6036853e8aef4ca95f37cb2e1b5037f1048664a40bad5a034d69c81b36b41ed5eb761504

data/CHANGELOG.md

@@ -1,5 +1,34 @@
+# Changelog
+
 ## [Unreleased]
 
+## [0.4.0] - 2025-09-11
+
+### Added
+
+- Allow empty usecases for class
+- Document minimal class usecase
+- Implement testing of defined types
+- Allow testing of functions
+
+### Fixed
+
+- Handle case where use wants to check that an error occurs but none do
+
+## [0.3.1] - 2025-09-11
+
+- Use changelog
+
+## [0.3.0] - 2025-09-11
+
+- Display errors in red
+
+## [0.2.0] - 2025-09-11
+
+- Document rake task in README
+- Fix loading of custom Ruby functions from Puppet environment
+- Run tests in temporary directory
+
 ## [0.1.0] - 2025-09-11
 
 - Initial release

data/README.md

@@ -18,9 +18,17 @@ Install this gem on your development and CI/CD hosts:
 
 Create a "test" directory under your module root. Create subdir "class" for
 classes, "define" for defined types. Create YAML files inside this directories
-with usecases and expected results.
+with usecases and expected results. Files must be named exactly as the Puppet
+object they should test. For example, usecases for a class "foo::bar" should be
+stored in file "tests/class/foo::bar.yaml".
 
-TODO: write a minimal example here and create an "examples" directory.
+A minimal file for a class:
+
+```yaml
+---
+usecases:
+  'it compiles':
+```
 
 Add these lines to your Rakefile:
 

data/assets/test-env/lib/puppet/functions/test_data.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
-Puppet::Functions.create_function(:'test_data') do
+Puppet::Functions.create_function(:test_data) do
   dispatch :test_data do
-    param 'Struct[{uri=>String[1]}]', :options
-    param 'Puppet::LookupContext', :context
+    param "Struct[{uri=>String[1]}]", :options
+    param "Puppet::LookupContext", :context
   end
 
   argument_mismatch :missing_uri do
-    param 'Hash', :options
-    param 'Puppet::LookupContext', :context
+    param "Hash", :options
+    param "Puppet::LookupContext", :context
   end
 
   def test_data(options, _context)
-    uri = options['uri']
+    uri = options["uri"]
     hiera_data = Thread.current[:hiera_data]
     return {} unless hiera_data
 
@@ -21,6 +21,6 @@ Puppet::Functions.create_function(:'test_data') do
 
   def missing_uri(_options, _context)
     "one of 'uri' or 'uris' must be declared in hiera.yaml " \
-      'when using this data_hash function.'
+      "when using this data_hash function."
   end
 end

data/lib/puppet_unit_tests/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module PuppetUnitTests
+  class Error < StandardError; end
+
+  # Error found in user data files before starting to run tests.
+  class UserDataError < Error
+    attr_accessor :path
+  end
+end

data/lib/puppet_unit_tests/rake_task.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require 'rake'
-require 'rake/tasklib'
+require "rake"
+require "rake/tasklib"
 
-require_relative 'runner'
+require_relative "runner"
 
 module PuppetUnitTests
   # Simple rake task to execute tests.
@@ -12,14 +12,20 @@ module PuppetUnitTests
       super()
       @name = name
 
-      desc 'Run Puppet unit tests' unless ::Rake.application.last_description
+      desc "Run Puppet unit tests" unless ::Rake.application.last_description
       task(name, *args) do |_, task_args|
         yield(*[self, task_args].slice(0, task_block.arity)) if task_block
         runner = Runner.new
-        errors = runner.run
-        unless errors.empty?
-          runner.format_errors(errors)
-          abort("Puppet unit tests failed!")
+        begin
+          errors = runner.run
+          unless errors.empty?
+            runner.format_errors(errors)
+            abort("Puppet unit tests failed!")
+          end
+        rescue UserDataError => e
+          warn("In file #{e.path}:")
+          warn("    #{e.message}")
+          abort("Error in YAML test files")
         end
       end
     end

data/lib/puppet_unit_tests/runner.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'rainbow'
+require "rainbow"
 
 require_relative "test_environment"
 require_relative "test_data"
@@ -11,7 +11,7 @@ module PuppetUnitTests
     def initialize(assets_dir = nil)
       @env = nil
       @assets_dir = assets_dir || File.realpath(
-        File.join(__dir__, '..', '..', 'assets')
+        File.join(__dir__, "..", "..", "assets")
       )
       @env_dir = nil
     end
@@ -20,7 +20,7 @@ module PuppetUnitTests
       setup
       all_errors = {}
 
-      Dir.glob("tests/class/*.yaml") do |yaml_test_file|
+      Dir.glob("tests/{class,define,function}/*.yaml") do |yaml_test_file|
         test_data = TestData.parse(yaml_test_file)
         test_data.trusted_facts["certname"] ||= @env.nodename
         errors = test_data.check(@env)
@@ -28,7 +28,6 @@ module PuppetUnitTests
 
         all_errors[test_data.name] = errors
       end
-      # TODO: test defines
       # TODO: test functions
       # TODO: test plans
 
@@ -52,13 +51,13 @@ module PuppetUnitTests
     private
 
     def setup
-      @env_dir = Dir.mktmpdir('puppet-test-env')
-      FileUtils.mkdir(File.join(@env_dir, 'modules'))
+      @env_dir = Dir.mktmpdir("puppet-test-env")
+      FileUtils.mkdir(File.join(@env_dir, "modules"))
       FileUtils.copy_entry(
-        File.join(@assets_dir, 'test-env'),
+        File.join(@assets_dir, "test-env"),
         @env_dir
       )
-      FileUtils.ln_s(Dir.pwd, File.join(@env_dir, 'modules'))
+      FileUtils.ln_s(Dir.pwd, File.join(@env_dir, "modules"))
       @env = TestEnvironment.new do |e|
         e.environmentpath = @env_dir
         e.hiera_config = File.join(@env_dir, "hiera.yaml")

data/lib/puppet_unit_tests/test_data.rb

@@ -32,7 +32,9 @@ module PuppetUnitTests
         type = File.basename(dir)
         name = File.basename(path, ".yaml")
         data = YAML.load_file(path)
-        usecases = data["usecases"].map { |dn, du| TestUsecase.parse(dn, du) }
+        usecases = data["usecases"].map do |dn, du|
+          parse_usecase(dn, du, type)
+        end
         td = new(type, name, usecases)
         td.facts = data["facts"] || {}
         td.server_facts = data["server_facts"] || {}
@@ -42,6 +44,21 @@ module PuppetUnitTests
         td.stubs = data["stubs"] || []
 
         td
+      rescue UserDataError => e
+        e.path = path
+        raise e
+      end
+
+      private
+
+      def parse_usecase(name, data, type)
+        case type
+        when "class" then ClassUsecase.parse(name, data)
+        when "define" then DefineUsecase.parse(name, data)
+        when "function" then FunctionUsecase.parse(name, data)
+        else
+          raise Error, "usecase type #{type} not implemented"
+        end
       end
     end
 
@@ -65,20 +82,36 @@ module PuppetUnitTests
     private
 
     def check_usecase(env, uc)
+      errors = []
       if uc.error
-        catalog_error(env, uc, Regexp.new(uc.error))
+        errors += with_catalog_error(env, uc, Regexp.new(uc.error))
       else
-        catalog = catalog(env, uc)
-        errors = []
-        errors += uc.present.map { |rs| check_present(catalog, rs) }
-        errors += uc.absent.map { |rs| check_absent(catalog, rs) }
-
-        errors.flatten.compact
+        case uc
+        when ClassUsecase, DefineUsecase
+          with_compiler(env, uc) do |comp|
+            errors += uc.present.map { |rs| check_present(comp.catalog, rs) }
+            errors += uc.absent.map { |rs| check_absent(comp.catalog, rs) }
+          end
+        when FunctionUsecase
+          with_compiler(env, uc) do |comp|
+            errors += check_function_result(comp, uc.parameters, uc.result)
+          end
+        end
       end
+
+      errors.flatten.compact
     rescue Puppet::PreformattedError => e
       [e.arguments[:detail]]
     end
 
+    def check_function_result(compiler, parameters, expected)
+      scope = compiler.context_overrides[:global_scope]
+      actual = scope.call_function(@name, parameters)
+      return [] if actual == expected
+
+      ["expected result #{expected.inspect}, got #{actual.inspect}"]
+    end
+
     def check_present(catalog, rs)
       res_disp = "#{rs.type}[#{rs.title}]"
       res = catalog.resource(rs.type, rs.title)
@@ -98,28 +131,37 @@ module PuppetUnitTests
     def check_absent(catalog, rs)
       res_disp = "#{rs.type}[#{rs.title}]"
       res = catalog.resource(rs.type, rs.title)
-      return [nil] unless res
-      return [nil] if rs.parameters.all? { |k, v| res[k] == v }
+      return [] unless res
+      return [] unless rs.parameters.all? { |k, v| res[k] == v }
 
       ["#{res_disp} should be absent"]
     end
 
-    def catalog(env, usecase)
-      env.compile(
+    def with_compiler(env, usecase, &)
+      env.with_compiler(
         code(usecase),
         facts: @facts.merge(usecase.facts),
         server_facts: @server_facts.merge(usecase.server_facts),
-        trusted_facts: @trusted_facts.merge(usecase.trusted_facts)
+        trusted_facts: @trusted_facts.merge(usecase.trusted_facts),
+        &
       )
     end
 
-    def catalog_error(env, usecase, regexp)
-      catalog(env, usecase)
+    def with_catalog_error(env, usecase, regexp)
+      with_compiler(env, usecase)
+
+      [
+        "expected to see error matching #{regexp.source.inspect} " \
+        "but got no error"
+      ]
     rescue Puppet::ParseError => e
       if regexp.match?(e.message)
         []
       else
-        [e.message]
+        [
+          "expected to see error matching #{regexp.source.inspect} " \
+          "but got: #{e.message}"
+        ]
       end
     end
 
@@ -133,6 +175,11 @@ module PuppetUnitTests
             #{parameters.join(",\n  ")}
           }
         EOPP
+      when "function"
+        parameters = uc.parameters.map(&:inspect)
+        <<~EOPP
+          $_test_result = #{@name}(#{parameters.join(", ")})
+        EOPP
       else raise "#{@type} not implemented"
       end
     end

data/lib/puppet_unit_tests/test_environment.rb

@@ -53,15 +53,17 @@ module PuppetUnitTests
       @settings[:environmentpath] = Pathname.new(path).realpath
     end
 
-    def compile(code, facts:, server_facts:, trusted_facts:, stubs: [])
+    def clear_compiler
+      Puppet.runtime[:facter].clear
+      Puppet.pop_context
+      Puppet.pop_context
+    end
+
+    def with_compiler(code, facts:, server_facts:, trusted_facts:, stubs: [])
       # TODO: Puppet.features.add(:posix) { true } if facts match UNIX
 
-      code = stubs.map do |st|
-        stub_path = @stubsdir.join("#{st}.pp")
-        File.read(stub_path)
-      end.join($RS) + code
+      code = format_stubs(stubs) + $RS + code
 
-      Puppet.runtime[:facter].clear
       name = trusted_facts["certname"]
       node_facts = Puppet::Node::Facts.new(name, facts)
       node = Puppet::Node.new(name, parameters: {}, facts: node_facts)
@@ -76,19 +78,35 @@ module PuppetUnitTests
       node.add_server_facts(server_facts)
 
       Puppet[:code] = code
-      catalog = Puppet::Resource::Catalog.indirection.find(
-        node.name, use_node: node
+      compiler = Puppet::Parser::Compiler.new(node)
+      compiler.compile
+      loaders = Puppet::Pops::Loaders.new(@puppet_env)
+      Puppet.push_context(
+        {
+          loaders: loaders,
+          global_scope: compiler.context_overrides[:global_scope]
+        },
+        "set globals"
       )
+
       Puppet::Pops::Evaluator::DeferredResolver.resolve_and_replace(
-        node.facts, catalog
+        node.facts, compiler.catalog
       )
-      Puppet.pop_context
 
-      catalog
+      yield compiler
+    ensure
+      Puppet.runtime[:facter].clear
     end
 
     private
 
+    def format_stubs(stubs)
+      stubs.map do |st|
+        stub_path = @stubsdir.join("#{st}.pp")
+        File.read(stub_path)
+      end.join($RS)
+    end
+
     def global_setup(settings)
       Puppet.runtime[:facter] = FakeFacter.new
       Puppet.settings.initialize_app_defaults(settings)

data/lib/puppet_unit_tests/test_usecase.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "error"
 require_relative "resource_spec"
 
 module PuppetUnitTests
@@ -19,6 +20,13 @@ module PuppetUnitTests
 
     def initialize(name)
       @name = name
+
+      @facts = {}
+      @server_facts = {}
+      @trusted_facts = {}
+      @hiera = {}
+      @settings = {}
+
       @present = []
       @absent = []
       @error = nil
@@ -27,6 +35,8 @@ module PuppetUnitTests
     class << self
       def parse(name, data_usecase)
         uc = new(name)
+        return uc unless data_usecase
+
         uc.facts = data_usecase["facts"] || {}
         uc.server_facts = data_usecase["server_facts"] || {}
         uc.trusted_facts = data_usecase["trusted_facts"] || {}
@@ -40,7 +50,7 @@ module PuppetUnitTests
           end
         end
         if data_usecase.key?("absent")
-          uc.present = data_usecase["absent"].map do |rs|
+          uc.absent = data_usecase["absent"].map do |rs|
             ResourceSpec.parse(rs)
           end
         end
@@ -49,4 +59,60 @@ module PuppetUnitTests
       end
     end
   end
+
+  # A test usecase for a Puppet class.
+  class ClassUsecase < TestUsecase
+  end
+
+  # A test usecase for a Puppet defined type.
+  class DefineUsecase < TestUsecase
+    attr_accessor :title
+    attr_accessor :parameters
+
+    def initialize(name)
+      super
+
+      @title = nil
+      @parameters = {}
+    end
+
+    class << self
+      def parse(name, data)
+        uc = super
+
+        if data.nil? || !data.key?("title")
+          raise UserDataError, "Missing title for defined type #{@name}"
+        end
+
+        uc.title = data["title"]
+        uc.parameters = data["parameters"] || {}
+
+        uc
+      end
+    end
+  end
+
+  # A test usecase for a Puppet function.
+  class FunctionUsecase < TestUsecase
+    attr_accessor :parameters
+    attr_accessor :result
+
+    def initialize(name)
+      super
+      @parameters = []
+      @result = nil
+    end
+
+    class << self
+      def parse(name, data)
+        uc = super
+        return uc if data.nil?
+
+        uc.parameters = data["parameters"] || []
+        uc.result = data["result"]
+
+        uc
+      end
+    end
+  end
 end

data/lib/puppet_unit_tests/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PuppetUnitTests
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/puppet_unit_tests.rb

@@ -1,8 +1,4 @@
 # frozen_string_literal: true
 
 require_relative "puppet_unit_tests/version"
-
-module PuppetUnitTests
-  class Error < StandardError; end
-  # Your code goes here...
-end
+require_relative "puppet_unit_tests/runner"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puppet-unit-tests
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Arlo le Rouge
@@ -54,6 +54,7 @@ files:
 - assets/test-env/hiera.yaml
 - assets/test-env/lib/puppet/functions/test_data.rb
 - lib/puppet_unit_tests.rb
+- lib/puppet_unit_tests/error.rb
 - lib/puppet_unit_tests/fake_facter.rb
 - lib/puppet_unit_tests/rake_task.rb
 - lib/puppet_unit_tests/resource_spec.rb