feat: report live instance status to Test Kitchen 4 (#167)

Test Kitchen 4 added a `status(state)` hook on Kitchen::Driver::Base for
`kitchen list --live` and the `kitchen status` alias. Drivers that do not
implement it inherit "unknown", which is what this one reported.

Ask GCE instead. The state file records only what the last action did, and
that goes stale in both directions: a preemptible instance GCE has
reclaimed still reads as "Created", and an instance deleted outside Test
Kitchen leaves behind a server name that no longer resolves. Both now show
up immediately, which matters here because the README recommends
preemptible instances to keep costs down.

Reports GCE's own state -- running, terminated, provisioning, suspended --
plus "not created" when the state file names no server and "not found"
when it names one that is gone, with a message saying so.

Earlier Test Kitchen versions never call the method, so this is safe
across the supported >= 3.0 range; the suite passes against 3.0.0 as well.
Declares the `time` gem, which is no longer a default gem on Ruby 4.0 and
which Test Kitchen requires without declaring.

Confirmed against a real project through all four states: not created,
running, terminated after a stop, and not found after an out-of-band
delete.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: tas50

README.md

@@ -133,6 +133,29 @@ cinc kitchen verify    # run your tests
 cinc kitchen destroy   # delete the instance
 ```
 
+### Checking whether an instance is still there
+
+`kitchen list` reports what the last action did, which is not the same as what
+GCE currently holds. On Test Kitchen 4 or later, `--live` asks GCE directly:
+
+```sh
+cinc kitchen list --live
+```
+
+```text
+Instance              Driver                ...  Last Action  Live Status
+baseline-ubuntu-2204  Google Compute (GCE)  ...  Created      terminated
+```
+
+The reported state is GCE's own — `running`, `terminated`, `provisioning`,
+`suspended` and so on — plus `not created` when nothing has been launched and
+`not found` when the state file names an instance that no longer exists.
+
+This is worth knowing about if you use `preemptible: true`, since GCE can
+reclaim the instance at any time and Test Kitchen's own record will still say
+`Created`. `kitchen list --live --json` includes the instance name and the time
+of the check.
+
 ## Configuration
 
 All options below are set under the `driver:` key in `kitchen.yml`.

kitchen-google.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
   s.add_dependency "date", ">= 3.2"
   s.add_dependency "json", ">= 2.5"
   s.add_dependency "securerandom", ">= 0.1"
+  s.add_dependency "time", ">= 0.1"
   s.add_dependency "timeout", ">= 0.2"
 
   s.required_ruby_version = ">= 3.1"

lib/kitchen/driver/gce.rb

@@ -21,6 +21,7 @@
 require_relative "gce_version"
 require_relative "gce/windows_password"
 require "securerandom" unless defined?(SecureRandom)
+require "time" unless defined?(Time.iso8601)
 require "timeout" unless defined?(Timeout)
 
 module Kitchen
@@ -259,6 +260,64 @@ def destroy(state)
         state.delete(:zone)
       end
 
+      # Reports whether the instance recorded in the state file is actually
+      # running, by asking GCE rather than trusting the state file.
+      #
+      # Test Kitchen 4 calls this for `kitchen list --live` and the `kitchen
+      # status` alias. Earlier versions never call it, so implementing it is
+      # safe across the whole supported range.
+      #
+      # The state file records only what the last action did, which goes stale
+      # in both directions: a preemptible instance GCE has reclaimed still
+      # reads as "Created", and an instance deleted outside Test Kitchen leaves
+      # a server name behind that no longer resolves.
+      #
+      # @param state [Hash] the Test Kitchen state hash
+      # @return [Hash] the status, in the shape `Kitchen::Instance` expects
+      def status(state)
+        @state      = state
+        server_name = state[:server_name]
+
+        return status_report(live: false, state_name: "not created") if server_name.nil?
+
+        gce_status = server_instance(server_name).status.to_s.downcase
+
+        status_report(
+          live: gce_status == "running",
+          state_name: gce_status,
+          resource_id: server_name
+        )
+      rescue Google::Apis::ClientError => e
+        debug("API error: #{e.message}")
+
+        status_report(
+          live: false,
+          state_name: "not found",
+          resource_id: server_name,
+          message: "Instance #{server_name} is recorded in the state file but no longer exists " \
+                   "in project #{project}, zone #{zone}."
+        )
+      end
+
+      # Builds a status hash in the shape `Kitchen::Instance` expects.
+      #
+      # @param live [Boolean] whether the instance is up and usable
+      # @param state_name [String] the state to display
+      # @param resource_id [String, nil] the GCE instance name
+      # @param message [String, nil] anything the user should know
+      # @return [Hash] the status
+      # @api private
+      def status_report(live:, state_name:, resource_id: nil, message: nil)
+        {
+          live: live,
+          state: state_name,
+          source: "driver",
+          resource_id: resource_id,
+          message: message,
+          checked_at: Time.now.utc.iso8601,
+        }.compact
+      end
+
       # Whether the deprecated single-boot-disk options are configured.
       #
       # @return [Boolean] true if any of `autodelete_disk`, `disk_size` or

spec/kitchen/driver/gce/lifecycle_spec.rb

@@ -266,6 +266,81 @@
     end
   end
 
+  # Test Kitchen 4 asks the driver whether the instance is actually alive, for
+  # `kitchen list --live` and the `kitchen status` alias. Drivers that do not
+  # answer inherit "unknown" from Kitchen::Driver::Base.
+  describe "#status" do
+    # Kitchen::Instance#driver_status checks the arity before calling, and
+    # silently reports "unknown" for a status method that takes no state. A
+    # correct-looking implementation with the wrong signature is never called.
+    it "accepts the Kitchen state hash" do
+      expect(driver.method(:status).arity).to eq(1)
+    end
+
+    it "reports nothing created when the state file records no server" do
+      expect(compute).not_to receive(:get_instance)
+
+      expect(driver.status({})).to include(live: false, state: "not created")
+    end
+
+    context "with a running instance" do
+      before do
+        allow(compute).to receive(:get_instance).and_return(ComputeApi.instance(status: "RUNNING"))
+      end
+
+      it "reports it as live" do
+        expect(driver.status(server_name: "tk-test-1", zone: "test-zone-1a"))
+          .to include(live: true, state: "running")
+      end
+
+      it "identifies the instance it asked about" do
+        expect(driver.status(server_name: "tk-test-1", zone: "test-zone-1a"))
+          .to include(resource_id: "tk-test-1")
+      end
+
+      it "records when it checked, as an RFC 3339 timestamp" do
+        checked_at = driver.status(server_name: "tk-test-1", zone: "test-zone-1a")[:checked_at]
+
+        expect { Time.iso8601(checked_at) }.not_to raise_error
+      end
+
+      it "asks the zone recorded in the state file, not the configured one" do
+        expect(compute).to receive(:get_instance)
+          .with("test-project", "recorded-zone", "tk-test-1")
+          .and_return(ComputeApi.instance)
+
+        driver.status(server_name: "tk-test-1", zone: "recorded-zone")
+      end
+    end
+
+    # A preemptible instance GCE has reclaimed still exists, and the state file
+    # still says "Created". Reporting its real state is the point of the hook.
+    context "with an instance that exists but is not running" do
+      before do
+        allow(compute).to receive(:get_instance).and_return(ComputeApi.instance(status: "TERMINATED"))
+      end
+
+      it "reports GCE's own state and does not call it live" do
+        expect(driver.status(server_name: "tk-test-1", zone: "test-zone-1a"))
+          .to include(live: false, state: "terminated")
+      end
+    end
+
+    context "with a server recorded that no longer exists" do
+      before { allow(compute).to receive(:get_instance).and_raise(ComputeApi.client_error) }
+
+      it "reports it as gone rather than raising" do
+        expect(driver.status(server_name: "tk-gone", zone: "test-zone-1a"))
+          .to include(live: false, state: "not found")
+      end
+
+      it "says the state file is out of date" do
+        expect(driver.status(server_name: "tk-gone", zone: "test-zone-1a")[:message])
+          .to match(/tk-gone/)
+      end
+    end
+  end
+
   describe "#generate_server_name" do
     it "derives a name from the Test Kitchen instance name" do
       expect(driver.generate_server_name).to match(/\Atk-default-ubuntu-2204-[0-9a-f]{6}\z/)