feat: add finally lifecycle hook to always run regardless of failure (#…

…1917)

docs/content/docs/reference/lifecycle-hooks.md

@@ -6,7 +6,7 @@ menu:
     weight: 30
 ---
 
-The life cycle hooks system allows running commands before or after any phase of Test Kitchen (`create`, `converge`, `verify`, or `destroy`). Commands can be run either locally on your workstation (the default) or remotely on the test instance.
+The life cycle hooks system allows running commands before, after, or always after any phase of Test Kitchen (`create`, `converge`, `verify`, or `destroy`). Commands can be run either locally on your workstation (the default) or remotely on the test instance.
 
 These hooks are configured under a new `lifecycle:` section in `kitchen.yml`:
 
@@ -17,6 +17,8 @@ lifecycle:
   - echo after
   - local: echo also after
   - remote: echo after but in the instance
+  finally_create:
+  - echo run regardless of failure in create
 ```
 
 You can also configure hooks on a single platform or suite:

lib/kitchen/lifecycle_hooks.rb

@@ -43,9 +43,13 @@ def initialize(config, state_file)
     # @param block [Proc] Block of code implementing the lifecycle phase.
     # @return [void]
     def run_with_hooks(phase, state_file, &block)
-      run(phase, :pre)
-      yield
-      run(phase, :post)
+      begin
+        run(phase, :pre)
+        yield
+        run(phase, :post)
+      ensure
+        run(phase, :finally)
+      end
     end
 
     # @return [Kitchen::StateFile]
@@ -56,7 +60,7 @@ def run_with_hooks(phase, state_file, &block)
     # Execute a specific lifecycle hook.
     #
     # @param phase [String] Lifecycle phase which is being executed.
-    # @param hook_timing [Symbol] `:pre` or `:post` to indicate which hook to run.
+    # @param hook_timing [Symbol] `:pre`, `:post`, or `:finally` to indicate which hook to run.
     # @return [void]
     def run(phase, hook_timing)
       # Yes this has to be a symbol because of how data munger works.

spec/kitchen/instance_spec.rb

@@ -502,6 +502,7 @@ def platform(name = "platform")
         it "calls lifecycle hooks" do
           lifecycle_hooks.expects(:run).with(:create, :pre)
           lifecycle_hooks.expects(:run).with(:create, :post)
+          lifecycle_hooks.expects(:run).with(:create, :finally)
 
           instance.create
         end
@@ -559,8 +560,10 @@ def platform(name = "platform")
         it "calls lifecycle hooks" do
           lifecycle_hooks.expects(:run).with(:create, :pre)
           lifecycle_hooks.expects(:run).with(:create, :post)
+          lifecycle_hooks.expects(:run).with(:create, :finally)
           lifecycle_hooks.expects(:run).with(:converge, :pre)
           lifecycle_hooks.expects(:run).with(:converge, :post)
+          lifecycle_hooks.expects(:run).with(:converge, :finally)
 
           instance.converge
         end
@@ -585,6 +588,7 @@ def platform(name = "platform")
         it "calls lifecycle hooks" do
           lifecycle_hooks.expects(:run).with(:converge, :pre)
           lifecycle_hooks.expects(:run).with(:converge, :post)
+          lifecycle_hooks.expects(:run).with(:converge, :finally)
 
           instance.converge
         end

spec/kitchen/lifecycle_hooks_spec.rb

@@ -108,6 +108,18 @@ def expect_remote_hook_generated_and_run(phase, hook)
     run_lifecycle_hooks
   end
 
+  it "runs finally even if stage fails" do
+    local_command = "echo foo"
+    config.update(finally_create: [local_command])
+    hook = expect_local_hook_generated_and_run(:finally, { local: local_command })
+    begin
+      lifecycle_hooks.run_with_hooks(:create, state_file) {
+        raise Error
+      }
+    rescue
+    end
+  end
+
   it "runs a local command with a user option" do
     hook = { local: "echo foo", user: "bar" }
     config.update(post_create: [hook])