puppet 4.0.0 → 4.9.1

data/spec/unit/file_system_spec.rb

@@ -5,6 +5,125 @@ require 'puppet/util/platform'
 describe "Puppet::FileSystem" do
   include PuppetSpec::Files
 
+  # different UTF-8 widths
+  # 1-byte A
+  # 2-byte ۿ - http://www.fileformat.info/info/unicode/char/06ff/index.htm - 0xDB 0xBF / 219 191
+  # 3-byte ᚠ - http://www.fileformat.info/info/unicode/char/16A0/index.htm - 0xE1 0x9A 0xA0 / 225 154 160
+  # 4-byte 𠜎 - http://www.fileformat.info/info/unicode/char/2070E/index.htm - 0xF0 0xA0 0x9C 0x8E / 240 160 156 142
+  let (:mixed_utf8) { "A\u06FF\u16A0\u{2070E}" } # Aۿᚠ𠜎
+
+  def with_file_content(content)
+    path = tmpfile('file-system')
+    file = File.new(path, 'wb')
+    file.sync = true
+    file.print content
+
+    yield path
+
+  ensure
+    file.close
+  end
+
+  SYSTEM_SID_BYTES = [1, 1, 0, 0, 0, 0, 0, 5, 18, 0, 0, 0]
+
+  def is_current_user_system?
+    SYSTEM_SID_BYTES == Puppet::Util::Windows::ADSI::User.current_user_sid.sid_bytes
+  end
+
+  context "#open" do
+    it "uses the same default mode as File.open, when specifying a nil mode (umask used on non-Windows)" do
+      file = tmpfile('file_to_update')
+      expect(Puppet::FileSystem.exist?(file)).to be_falsey
+
+      Puppet::FileSystem.open(file, nil, 'a') { |fh| fh.write('') }
+
+      expected_perms = Puppet::Util::Platform.windows? ?
+        # default Windows mode based on temp file storage for SYSTEM user or regular user
+        # for Jenkins or other services running as SYSTEM writing to c:\windows\temp
+        # the permissions will typically be SYSTEM(F) / Administrators(F) which is 770
+        # but sometimes there are extra users like IIS_IUSRS granted rights which adds the "extra ace" 2
+        # for local Administrators writing to their own temp folders under c:\users\USER
+        # they will have (F) for themselves, and Users will not have a permission, hence 700
+        (is_current_user_system? ? ['770', '2000770'] : '2000700') :
+        # or for *nix determine expected mode via bitwise AND complement of umask
+        (0100000 | 0666 & ~File.umask).to_s(8)
+      expect([expected_perms].flatten).to include(Puppet::FileSystem.stat(file).mode.to_s(8))
+
+      default_file = tmpfile('file_to_update2')
+      expect(Puppet::FileSystem.exist?(default_file)).to be_falsey
+
+      File.open(default_file, 'a') { |fh| fh.write('') }
+
+      # which matches the behavior of File.open
+      expect(Puppet::FileSystem.stat(file).mode).to eq(Puppet::FileSystem.stat(default_file).mode)
+    end
+
+    it "can accept an octal mode integer" do
+      file = tmpfile('file_to_update')
+      # NOTE: 777 here returns 755, but due to Ruby?
+      Puppet::FileSystem.open(file, 0444, 'a') { |fh| fh.write('') }
+
+      # Behavior may change in the future on Windows, to *actually* change perms
+      # but for now, setting a mode doesn't touch them
+      expected_perms = Puppet::Util::Platform.windows? ?
+        (is_current_user_system? ? ['770', '2000770'] : '2000700') :
+        '100444'
+      expect([expected_perms].flatten).to include(Puppet::FileSystem.stat(file).mode.to_s(8))
+
+      expected_ruby_mode = Puppet::Util::Platform.windows? ?
+        # The Windows behavior has been changed to ignore the mode specified by open
+        # given it's unlikely a caller expects Windows file attributes to be set
+        # therefore mode is explicitly not managed (until PUP-6959 is fixed)
+        #
+        # In default Ruby on Windows a mode controls file attribute setting
+        # (like archive, read-only, etc)
+        # The GetFileInformationByHandle API returns an attributes value that is
+        # a bitmask of Windows File Attribute Constants at
+        # https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117(v=vs.85).aspx
+        '100644' :
+        # On other platforms, the mode should be what was set by octal 0444
+        '100444'
+
+      expect(File.stat(file).mode.to_s(8)).to eq(expected_ruby_mode)
+    end
+
+    it "cannot accept a mode string" do
+      file = tmpfile('file_to_update')
+      expect {
+        Puppet::FileSystem.open(file, "444", 'a') { |fh| fh.write('') }
+      }.to raise_error(TypeError)
+    end
+
+    it "opens, creates ands allows updating of a new file, using by default, the external system encoding" do
+      begin
+        original_encoding = Encoding.default_external
+
+        # this must be set through Ruby API and cannot be mocked - it sets internal state used by File.open
+        # pick a bizarre encoding unlikely to be used in any real tests
+        Encoding.default_external = Encoding::CP737
+
+        file = tmpfile('file_to_update')
+
+        # test writing a UTF-8 string when Default external encoding is something different
+        Puppet::FileSystem.open(file, 0660, 'w') do |fh|
+          # note Ruby behavior which has no external_encoding, but implicitly uses Encoding.default_external
+          expect(fh.external_encoding).to be_nil
+          # write a UTF-8 string to this file
+          fh.write(mixed_utf8)
+        end
+
+        # prove that Ruby implicitly converts read strings back to Encoding.default_external
+        # and that it did that in the previous write
+        written = Puppet::FileSystem.read(file)
+        expect(written.encoding).to eq(Encoding.default_external)
+        expect(written).to eq(mixed_utf8.force_encoding(Encoding.default_external))
+      ensure
+        # carefully roll back to the previous
+        Encoding.default_external = original_encoding
+      end
+    end
+  end
+
   context "#exclusive_open" do
     it "opens ands allows updating of an existing file" do
       file = file_containing("file_to_update", "the contents")
@@ -19,14 +138,33 @@ describe "Puppet::FileSystem" do
       expect(Puppet::FileSystem.read(file)).to eq("updated the contents")
     end
 
-    it "opens, creates ands allows updating of a new file" do
-      file = tmpfile("file_to_update")
+    it "opens, creates ands allows updating of a new file, using by default, the external system encoding" do
+      begin
+        original_encoding = Encoding.default_external
 
-      Puppet::FileSystem.exclusive_open(file, 0660, 'w') do |fh|
-        fh.write("updated new file")
-      end
+        # this must be set through Ruby API and cannot be mocked - it sets internal state used by File.open
+        # pick a bizarre encoding unlikely to be used in any real tests
+        Encoding.default_external = Encoding::CP737
+
+        file = tmpfile('file_to_update')
+
+        # test writing a UTF-8 string when Default external encoding is something different
+        Puppet::FileSystem.exclusive_open(file, 0660, 'w') do |fh|
+          # note Ruby behavior which has no external_encoding, but implicitly uses Encoding.default_external
+          expect(fh.external_encoding).to be_nil
+          # write a UTF-8 string to this file
+          fh.write(mixed_utf8)
+        end
 
-      expect(Puppet::FileSystem.read(file)).to eq("updated new file")
+        # prove that Ruby implicitly converts read strings back to Encoding.default_external
+        # and that it did that in the previous write
+        written = Puppet::FileSystem.read(file)
+        expect(written.encoding).to eq(Encoding.default_external)
+        expect(written).to eq(mixed_utf8.force_encoding(Encoding.default_external))
+      ensure
+        # carefully roll back to the previous
+        Encoding.default_external = original_encoding
+      end
     end
 
     it "excludes other processes from updating at the same time", :unless => Puppet::Util::Platform.windows? do
@@ -96,6 +234,69 @@ describe "Puppet::FileSystem" do
     end
   end
 
+  context "read_preserve_line_endings" do
+    it "should read a file with line feed" do
+      with_file_content("file content \n") do |file|
+        expect(Puppet::FileSystem.read_preserve_line_endings(file)).to eq("file content \n")
+      end
+    end
+
+    it "should read a file with carriage return line feed" do
+      with_file_content("file content \r\n") do |file|
+        expect(Puppet::FileSystem.read_preserve_line_endings(file)).to eq("file content \r\n")
+      end
+    end
+
+    it "should read a mixed file using only the first line newline when lf" do
+      with_file_content("file content \nsecond line \r\n") do |file|
+        expect(Puppet::FileSystem.read_preserve_line_endings(file)).to eq("file content \nsecond line \r\n")
+      end
+    end
+
+    it "should read a mixed file using only the first line newline when crlf" do
+      with_file_content("file content \r\nsecond line \n") do |file|
+        expect(Puppet::FileSystem.read_preserve_line_endings(file)).to eq("file content \r\nsecond line \n")
+      end
+    end
+  end
+
+  context "read without an encoding specified" do
+    it "returns strings as Encoding.default_external" do
+      temp_file = file_containing('test.txt', 'hello world')
+
+      contents = Puppet::FileSystem.read(temp_file)
+
+      expect(contents.encoding).to eq(Encoding.default_external)
+      expect(contents).to eq('hello world')
+    end
+  end
+
+  context "read should allow an encoding to be specified" do
+    # First line of Rune version of Rune poem at http://www.columbia.edu/~fdc/utf8/
+    # characters chosen since they will not parse on Windows with codepage 437 or 1252
+    # Section 3.2.1.3 of Ruby spec guarantees that \u strings are encoded as UTF-8
+    let (:rune_utf8) { "\u16A0\u16C7\u16BB" } # 'ᚠᛇᚻ'
+
+    it "and should read a UTF8 file properly" do
+      temp_file = file_containing('utf8.txt', rune_utf8)
+
+      contents = Puppet::FileSystem.read(temp_file, :encoding => 'utf-8')
+
+      expect(contents.encoding).to eq(Encoding::UTF_8)
+      expect(contents).to eq(rune_utf8)
+    end
+
+    it "does not strip the UTF8 BOM (Byte Order Mark) if present in a file" do
+      bom = "\uFEFF"
+
+      temp_file = file_containing('utf8bom.txt', "#{bom}#{rune_utf8}")
+      contents = Puppet::FileSystem.read(temp_file, :encoding => 'utf-8')
+
+      expect(contents.encoding).to eq(Encoding::UTF_8)
+      expect(contents).to eq("#{bom}#{rune_utf8}")
+    end
+  end
+
   describe "symlink",
     :if => ! Puppet.features.manages_symlinks? &&
     Puppet.features.microsoft_windows? do
@@ -179,6 +380,67 @@ describe "Puppet::FileSystem" do
       end
     end
 
+    it "should return false for exist? when resolving a cyclic symlink chain" do
+      # point symlink -> file
+      symlink = tmpfile("somefile_link")
+      Puppet::FileSystem.symlink(file, symlink)
+
+      # point symlink2 -> symlink
+      symlink2 = tmpfile("somefile_link2")
+      Puppet::FileSystem.symlink(symlink, symlink2)
+
+      # point symlink3 -> symlink2
+      symlink3 = tmpfile("somefile_link3")
+      Puppet::FileSystem.symlink(symlink2, symlink3)
+
+      # yank file, temporarily dangle
+      ::File.delete(file)
+
+      # and trash it so that we can recreate it OK on windows
+      Puppet::FileSystem.unlink(symlink)
+
+      # point symlink -> symlink3 to create a cycle
+      Puppet::FileSystem.symlink(symlink3, symlink)
+
+      expect(Puppet::FileSystem.exist?(symlink3)).to be_falsey
+    end
+
+    it "should return true for exist? when resolving a symlink chain pointing to a file" do
+      # point symlink -> file
+      symlink = tmpfile("somefile_link")
+      Puppet::FileSystem.symlink(file, symlink)
+
+      # point symlink2 -> symlink
+      symlink2 = tmpfile("somefile_link2")
+      Puppet::FileSystem.symlink(symlink, symlink2)
+
+      # point symlink3 -> symlink2
+      symlink3 = tmpfile("somefile_link3")
+      Puppet::FileSystem.symlink(symlink2, symlink3)
+
+      expect(Puppet::FileSystem.exist?(symlink3)).to be_truthy
+    end
+
+    it "should return false for exist? when resolving a symlink chain that dangles" do
+      # point symlink -> file
+      symlink = tmpfile("somefile_link")
+      Puppet::FileSystem.symlink(file, symlink)
+
+      # point symlink2 -> symlink
+      symlink2 = tmpfile("somefile_link2")
+      Puppet::FileSystem.symlink(symlink, symlink2)
+
+      # point symlink3 -> symlink2
+      symlink3 = tmpfile("somefile_link3")
+      Puppet::FileSystem.symlink(symlink2, symlink3)
+
+      # yank file, and make symlink dangle
+      ::File.delete(file)
+
+      # symlink3 is now indirectly dangled
+      expect(Puppet::FileSystem.exist?(symlink3)).to be_falsey
+    end
+
     it "should not create a symlink when the :noop option is specified" do
       [file, dir].each do |target|
         symlink = tmpfile("#{Puppet::FileSystem.basename(target)}_link")
@@ -408,6 +670,26 @@ describe "Puppet::FileSystem" do
       expect(Puppet::FileSystem.readlink(symlink)).to eq(missing_file.to_s)
     end
 
+    it "should be able to unlink a dangling symlink pointed at a file" do
+      symlink = tmpfile("somefile_link")
+      Puppet::FileSystem.symlink(file, symlink)
+      ::File.delete(file)
+      Puppet::FileSystem.unlink(symlink)
+
+      expect(Puppet::FileSystem).to_not be_exist(file)
+      expect(Puppet::FileSystem).to_not be_exist(symlink)
+    end
+
+    it "should be able to unlink a dangling symlink pointed at a directory" do
+      symlink = tmpfile("somedir_link")
+      Puppet::FileSystem.symlink(dir, symlink)
+      Dir.rmdir(dir)
+      Puppet::FileSystem.unlink(symlink)
+
+      expect(Puppet::FileSystem).to_not be_exist(dir)
+      expect(Puppet::FileSystem).to_not be_exist(symlink)
+    end
+
     it "should delete only the symlink and not the target when calling unlink instance method" do
       [file, dir].each do |target|
         symlink = tmpfile("#{Puppet::FileSystem.basename(target)}_link")
@@ -504,5 +786,90 @@ describe "Puppet::FileSystem" do
         end.to raise_error(Errno::EEXIST)
       end
     end
+
+    describe 'expand_path' do
+      it 'should raise an error when given nil, like Ruby File.expand_path' do
+        expect { File.expand_path(nil) }.to raise_error(TypeError)
+
+        # match Ruby behavior
+        expect { Puppet::FileSystem.expand_path(nil) }.to raise_error(TypeError)
+      end
+
+      it 'with an expanded path passed to Dir.glob, the same expanded path will be returned' do
+        # this exists specifically for Puppet::Pops::Loader::ModuleLoaders::FileBased#add_to_index
+        # which should receive an expanded path value from it's parent Environment
+        # and will later compare values generated by Dir.glob
+        tmp_long_file = tmpfile('foo.bar', tmpdir('super-long-thing-that-Windows-shortens'))
+        Puppet::FileSystem.touch(tmp_long_file)
+        expanded_path = Puppet::FileSystem.expand_path(tmp_long_file)
+
+        expect(expanded_path).to eq(Dir.glob(expanded_path).first)
+      end
+
+      describe 'on non-Windows', :unless => Puppet::Util::Platform.windows? do
+        it 'should produce the same results as the Ruby File.expand_path' do
+          # on Windows this may be 8.3 style, but not so on other platforms
+          # only done since ::File.expects(:expand_path).with(path).at_least_once
+          # cannot be used since it will cause a stack overflow
+          path = tmpdir('foobar')
+
+          expect(Puppet::FileSystem.expand_path(path)).to eq(File.expand_path(path))
+        end
+      end
+
+      describe 'on Windows', :if => Puppet::Util::Platform.windows? do
+        let(:nonexist_file) { 'C:\\file~1.ext' }
+        let(:nonexist_path) { 'C:\\progra~1\\missing\\path\\file.ext' }
+
+        ['/', '\\'].each do |slash|
+          it "should return the absolute path including system drive letter when given #{slash}, like Ruby File.expand_path" do
+
+            # regardless of slash direction, return value is drive letter
+            expanded = Puppet::FileSystem.expand_path(slash)
+            expect(expanded).to eq(ENV['SystemDrive'] + File::SEPARATOR)
+            expect(expanded).to eq(File.expand_path(slash))
+          end
+        end
+
+        it 'should behave like Rubys File.expand_path for a file that doesnt exist' do
+          expect(Puppet::FileSystem.exist?(nonexist_file)).to be_falsey
+          # this will change c:\\file~1.ext to c:/file~1.ext (existing Ruby behavior), but not expand any ~
+          ruby_expanded = File.expand_path(nonexist_file)
+          expect(ruby_expanded).to match(/~/)
+          expect(Puppet::FileSystem.expand_path(nonexist_file)).to eq(ruby_expanded)
+        end
+
+        it 'should behave like Rubys File.expand_path for a file with a parent path that doesnt exist' do
+          expect(Puppet::FileSystem.exist?(nonexist_path)).to be_falsey
+          # this will change c:\\progra~1 to c:/progra~1 (existing Ruby behavior), but not expand any ~
+          ruby_expanded = File.expand_path(nonexist_path)
+          expect(ruby_expanded).to match(/~/)
+          expect(Puppet::FileSystem.expand_path(nonexist_path)).to eq(ruby_expanded)
+        end
+
+        it 'should expand a shortened path completely, unlike Ruby File.expand_path' do
+          tmp_long_dir = tmpdir('super-long-thing-that-Windows-shortens')
+          short_path = Puppet::Util::Windows::File.get_short_pathname(tmp_long_dir)
+
+          # a shortened path to the temp dir will have a least 2 ~
+          # for instance, C:\\Users\\Administrator\\AppData\\Local\\Temp\\rspecrun2016####-####-#######\\super-long-thing-that-Windows-shortens\
+          # or C:\\Windows\\Temp\\rspecrun2016####-####-#######\\super-long-thing-that-Windows-shortens\
+          # will shorten to Temp\\rspecr~#\\super-~1
+          expect(short_path).to match(/~.*~/)
+
+          # expand with Ruby, noting not all ~ have been expanded
+          # which is the primary reason that a Puppet helper exists
+          ruby_expanded = File.expand_path(short_path)
+          expect(ruby_expanded).to match(/~/)
+
+          # Puppet expansion uses the Windows API and has no ~ remaining
+          puppet_expanded = Puppet::FileSystem.expand_path(short_path)
+          expect(puppet_expanded).to_not match(/~/)
+
+          # and the directories are one and the same
+          expect(File.identical?(short_path, puppet_expanded)).to be_truthy
+        end
+      end
+    end
   end
 end

data/spec/unit/functions/assert_type_spec.rb

@@ -1,8 +1,11 @@
 require 'spec_helper'
 require 'puppet/pops'
 require 'puppet/loaders'
+require 'puppet_spec/compiler'
 
 describe 'the assert_type function' do
+  include PuppetSpec::Compiler
+
   after(:all) { Puppet::Pops::Loaders.clear }
 
   let(:loaders) { Puppet::Pops::Loaders.new(Puppet::Node::Environment.create(:testing, [])) }
@@ -19,19 +22,17 @@ describe 'the assert_type function' do
   it 'asserts non compliant type by raising an error' do
     expect do
       func.call({}, type(Integer), 'hello world')
-    end.to raise_error(Puppet::Pops::Types::TypeAssertionError, /does not match actual/)
+    end.to raise_error(Puppet::Pops::Types::TypeAssertionError, /expects an Integer value, got String/)
   end
 
   it 'checks that first argument is a type' do
     expect do
       func.call({}, 10, 10)
-    end.to raise_error(ArgumentError, Regexp.new(Regexp.escape(
-"function 'assert_type' called with mis-matched arguments
-expected one of:
-  assert_type(Type type, Any value, Callable[Type, Type] block {0,1}) - arg count {2,3}
-  assert_type(String type_string, Any value, Callable[Type, Type] block {0,1}) - arg count {2,3}
-actual:
-  assert_type(Integer, Integer) - arg count {2}")))
+    end.to raise_error(ArgumentError, "'assert_type' expects one of:
+  (Type type, Any value, Callable[Type, Type] block?)
+    rejected: parameter 'type' expects a Type value, got Integer
+  (String type_string, Any value, Callable[Type, Type] block?)
+    rejected: parameter 'type_string' expects a String value, got Integer")
   end
 
   it 'allows the second arg to be undef/nil)' do
@@ -54,4 +55,43 @@ actual:
   def type(type_ref)
     Puppet::Pops::Types::TypeFactory.type_of(type_ref)
   end
+
+  it 'can validate a resource type' do
+    expect(eval_and_collect_notices("assert_type(Type[Resource], File['/tmp/test']) notice('ok')")).to eq(['ok'])
+  end
+
+  it 'can validate a type alias' do
+    code = <<-CODE
+      type UnprivilegedPort = Integer[1024,65537]
+      assert_type(UnprivilegedPort, 5432)
+      notice('ok')
+    CODE
+    expect(eval_and_collect_notices(code)).to eq(['ok'])
+  end
+
+  it 'can validate a type alias passed as a String' do
+    code = <<-CODE
+      type UnprivilegedPort = Integer[1024,65537]
+      assert_type('UnprivilegedPort', 5432)
+      notice('ok')
+    CODE
+    expect(eval_and_collect_notices(code)).to eq(['ok'])
+  end
+
+  it 'can validate and fail using a type alias' do
+    code = <<-CODE
+      type UnprivilegedPort = Integer[1024,65537]
+      assert_type(UnprivilegedPort, 345)
+      notice('ok')
+    CODE
+    expect { eval_and_collect_notices(code) }.to raise_error(Puppet::Error, /expects an UnprivilegedPort = Integer\[1024, 65537\] value, got Integer\[345, 345\]/)
+  end
+
+  it 'will use infer_set to report detailed information about complex mismatches' do
+    code = <<-CODE
+      assert_type(Struct[{a=>Integer,b=>Boolean}], {a=>hej,x=>s})
+    CODE
+    expect { eval_and_collect_notices(code) }.to raise_error(Puppet::Error,
+      /entry 'a' expects an Integer value, got String.*expects a value for key 'b'.*unrecognized key 'x'/m)
+  end
 end

data/spec/unit/functions/binary_file_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+require 'puppet_spec/compiler'
+require 'matchers/resource'
+require 'puppet_spec/files'
+
+describe 'the binary_file function' do
+  include PuppetSpec::Compiler
+  include Matchers::Resource
+  include PuppetSpec::Files
+
+  def with_file_content(content)
+    path = tmpfile('find-file-function')
+    file = File.new(path, 'wb')
+    file.sync = true
+    file.print content
+    yield path
+  end
+
+  it 'reads an existing absolute file' do
+    with_file_content('one') do |one|
+      # Note that Binary to String produced Base64 encoded version of 'one' which is 'b23l'
+      expect(compile_to_catalog("notify { String(binary_file('#{one}')):}")).to have_resource("Notify[b25l]")
+    end
+  end
+
+  it 'errors on non existing files' do
+    expect do
+      with_file_content('one') do |one|
+        compile_to_catalog("notify { binary_file('#{one}/nope'):}")
+      end
+    end.to raise_error(/The given file '.+\/nope' does not exist/)
+  end
+
+  it 'reads an existing file in a module' do
+    with_file_content('binary_data') do |name|
+      mod = mock 'module'
+      mod.stubs(:file).with('myfile').returns(name)
+      Puppet[:code] = "notify { String(binary_file('mymod/myfile')):}"
+      node = Puppet::Node.new('localhost')
+      compiler = Puppet::Parser::Compiler.new(node)
+      compiler.environment.stubs(:module).with('mymod').returns(mod)
+      # Note that the Binary to string produces Base64 encoded version of 'binary_data' which is 'YmluYXJ5X2RhdGE='
+      expect(compiler.compile().filter { |r| r.virtual? }).to have_resource("Notify[YmluYXJ5X2RhdGE=]")
+    end
+  end
+end

data/spec/unit/functions/break_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+require 'puppet_spec/compiler'
+require 'matchers/resource'
+
+describe 'the break function' do
+  include PuppetSpec::Compiler
+  include Matchers::Resource
+
+  context  do
+    it 'breaks iteration as if at end of input' do
+      expect(compile_to_catalog(<<-CODE)).to have_resource('Notify[[1, 2]]')
+          function please_break() {
+            [1,2,3].map |$x| { if $x == 3 { break() } $x }
+          }
+          notify { String(please_break()): }
+        CODE
+    end
+  end
+
+  it 'does not provide early exit from a class' do
+    # A break would semantically mean that the class should not be included - as if the
+    # iteration over class names should stop. That is too magic and should
+    # be done differently by the user.
+    #
+    expect do
+      compile_to_catalog(<<-CODE)
+        class does_break {
+          notice 'a'
+          if 1 == 1 { break() } # avoid making next line statically unreachable
+          notice 'b'
+        }
+        include(does_break)
+      CODE
+    end.to raise_error(/break\(\) from context where this is illegal at unknown:3 on node.*/)
+  end
+
+    it 'does not provide early exit from a define' do
+      # A break would semantically mean that the resource should not be created - as if the
+      # iteration over resource titles should stop. That is too magic and should
+      # be done differently by the user.
+      #
+      expect do
+        compile_to_catalog(<<-CODE)
+          define does_break {
+            notice 'a'
+            if 1 == 1 { break() } # avoid making next line statically unreachable
+            notice 'b'
+          }
+            does_break { 'no_you_cannot': }
+        CODE
+      end.to raise_error(/break\(\) from context where this is illegal at unknown:3 on node.*/)
+    end
+
+  it 'can be called when nested in a function to make that function behave as a break' do
+    # This allows functions like break_when(...) to be implemented by calling break() conditionally
+    #
+    expect(eval_and_collect_notices(<<-CODE)).to eql(['[100]'])
+      function nested_break($x) {
+        if $x == 2 { break() } else { $x * 100 }
+      }
+      function example() {
+        [1,2,3].map |$x| { nested_break($x)  }
+      }
+      notice example()
+      CODE
+  end
+
+  it 'can not be called nested from top scope' do
+    expect do
+      compile_to_catalog(<<-CODE)
+        # line 1
+        # line 2
+        $result = with(1) |$x| { with($x) |$x| {break() }}
+        notice $result
+      CODE
+    end.to raise_error(/break\(\) from context where this is illegal at unknown:3 on node.*/)
+  end
+
+  it 'can not be called from top scope' do
+    expect do
+      compile_to_catalog(<<-CODE)
+        # line 1
+        # line 2
+        break()
+      CODE
+    end.to raise_error(/break\(\) from context where this is illegal at unknown:3 on node.*/)
+  end
+end