add runtime deprecation warnings to Puppet::Util ENV wrappers

lib/puppet/util.rb

@@ -44,35 +44,40 @@ def create_erb(content)
   # @deprecated Use ENV instead
   # @api private
   def get_env(name, mode = default_env)
+    Puppet.deprecation_warning(_("Puppet::Util.get_env is deprecated and will be removed in a future version. Use ENV[] directly instead."))
     ENV.fetch(name, nil)
   end
   module_function :get_env
 
   # @deprecated Use ENV instead
   # @api private
   def get_environment(mode = default_env)
+    Puppet.deprecation_warning(_("Puppet::Util.get_environment is deprecated and will be removed in a future version. Use ENV.to_hash directly instead."))
     ENV.to_hash
   end
   module_function :get_environment
 
   # @deprecated Use ENV instead
   # @api private
   def clear_environment(mode = default_env)
+    Puppet.deprecation_warning(_("Puppet::Util.clear_environment is deprecated and will be removed in a future version. Use ENV.clear directly instead."))
     ENV.clear
   end
   module_function :clear_environment
 
   # @deprecated Use ENV instead
   # @api private
   def set_env(name, value = nil, mode = default_env)
+    Puppet.deprecation_warning(_("Puppet::Util.set_env is deprecated and will be removed in a future version. Use ENV[]= directly instead."))
     ENV[name] = value
   end
   module_function :set_env
 
   # @deprecated Use ENV instead
   # @api private
   def merge_environment(env_hash, mode = default_env)
-    ENV.merge!(hash.transform_keys(&:to_s))
+    Puppet.deprecation_warning(_("Puppet::Util.merge_environment is deprecated and will be removed in a future version. Use ENV.merge! directly instead."))
+    ENV.merge!(env_hash.transform_keys(&:to_s))
   end
   module_function :merge_environment
 

spec/unit/util_spec.rb

@@ -215,6 +215,55 @@ def withenv_utf8(&block)
     end
   end
 
+  describe "deprecated ENV wrapper methods" do
+    it "#get_env emits a deprecation warning and returns the env var" do
+      ENV["PUPPET_UTIL_TEST_VAR"] = "testval"
+      expect(Puppet).to receive(:deprecation_warning).with(/get_env is deprecated/)
+      expect(Puppet::Util.get_env("PUPPET_UTIL_TEST_VAR")).to eq("testval")
+    ensure
+      ENV.delete("PUPPET_UTIL_TEST_VAR")
+    end
+
+    it "#get_environment emits a deprecation warning and returns ENV as a hash" do
+      expect(Puppet).to receive(:deprecation_warning).with(/get_environment is deprecated/)
+      result = Puppet::Util.get_environment
+      expect(result).to be_a(Hash)
+    end
+
+    it "#clear_environment emits a deprecation warning and clears ENV" do
+      saved = ENV.to_hash
+      expect(Puppet).to receive(:deprecation_warning).with(/clear_environment is deprecated/)
+      Puppet::Util.clear_environment
+      expect(ENV.to_hash).to be_empty
+    ensure
+      ENV.replace(saved)
+    end
+
+    it "#set_env emits a deprecation warning and sets the env var" do
+      expect(Puppet).to receive(:deprecation_warning).with(/set_env is deprecated/)
+      Puppet::Util.set_env("PUPPET_UTIL_TEST_VAR", "setval")
+      expect(ENV["PUPPET_UTIL_TEST_VAR"]).to eq("setval")
+    ensure
+      ENV.delete("PUPPET_UTIL_TEST_VAR")
+    end
+
+    it "#merge_environment emits a deprecation warning and merges the hash into ENV" do
+      expect(Puppet).to receive(:deprecation_warning).with(/merge_environment is deprecated/)
+      Puppet::Util.merge_environment("PUPPET_UTIL_TEST_MERGE" => "merged")
+      expect(ENV["PUPPET_UTIL_TEST_MERGE"]).to eq("merged")
+    ensure
+      ENV.delete("PUPPET_UTIL_TEST_MERGE")
+    end
+
+    it "#merge_environment coerces symbol keys to strings" do
+      expect(Puppet).to receive(:deprecation_warning).with(/merge_environment is deprecated/)
+      Puppet::Util.merge_environment(PUPPET_UTIL_TEST_SYM: "symval")
+      expect(ENV["PUPPET_UTIL_TEST_SYM"]).to eq("symval")
+    ensure
+      ENV.delete("PUPPET_UTIL_TEST_SYM")
+    end
+  end
+
   describe "#absolute_path?" do
     describe "on posix systems", :if => Puppet.features.posix? do
       it "should default to the platform of the local system" do