kitchen-vra 3.4.0 → 3.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3ad4a4ab887a646b1856e8329bfa319f85c85adf5ab1d55785ed443e31ea623
-  data.tar.gz: b178306e4e6e20e88f27d1274913a6bf7c2be4ba9871fda69b8373938550783f
+  metadata.gz: 3077884f3c8f5e434889905e6c4d47e06ecf308fe810948c79d644e5f13086bd
+  data.tar.gz: addc3a87013a8834a75392625e026b5efdf1cfaff8009e0eaa8e690236b0be84
 SHA512:
-  metadata.gz: 4e2cbf243619ad72b38384a2520e7ccc68646e16c472e1356e088f00058ebf707e86aa558470dd75fb17b13a0742448ea1c822b73e1e38482340e1296b9a0686
-  data.tar.gz: 1a85f3b0bb3cbd9fa872a057225e0ab9494940830bbb68833b81968fc197b2e883bf32163022dbe83cb8eba5abce8212ba9467e8e5dd62c8462185a4236d92b6
+  metadata.gz: 2d6521702e1cc486f91d1aa2c0d1c17fdd1feaece55a8b634aaea65950282bde3b327e4bb79e7c256a6683ba8128b36ef5b59852b2c1f0de763d64dc4aa359a2
+  data.tar.gz: 190fa3d7bbfc3fd0db0220934390545f9b28cd4565126648d0503459de10035962f795b69275599409671aa15d2f5d31a018074f7b59d4a092f83437b027d8cd

data/.gitignore

@@ -2,7 +2,6 @@
 /.yardoc
 /Gemfile.lock
 /_yardoc/
-/coverage/
 /doc/
 /pkg/
 /spec/reports/

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.4.0"
+  ".": "3.4.1"
 }

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--color

data/.rubocop.yml

@@ -6,4 +6,3 @@ AllCops:
   TargetRubyVersion: 3.1
   Exclude:
     - "vendor/**/*"
-    - "spec/**/*"

data/.yardopts

@@ -8,4 +8,4 @@ lib/**/*.rb
 -
 CHANGELOG.md
 CONTRIBUTING.md
-LICENSE.txt
+LICENSE

data/CHANGELOG.md

@@ -10,6 +10,13 @@
 * Docs: rewrite README for new users and split contributor docs ([#80](https://github.com/test-kitchen/kitchen-vra/pull/80)) ([d9ebc45](https://github.com/test-kitchen/kitchen-vra/commit/d9ebc45))
 * Standardize renovate config and remove dependabot ([#81](https://github.com/test-kitchen/kitchen-vra/pull/81)) ([be552bd](https://github.com/test-kitchen/kitchen-vra/commit/be552bd))
 
+## [3.4.1](https://github.com/test-kitchen/kitchen-vra/compare/v3.4.0...v3.4.1) (2026-08-30)
+
+
+### Bug Fixes
+
+* stop prompting for credentials on every run with cache_credentials ([#91](https://github.com/test-kitchen/kitchen-vra/issues/91)) ([e1c185f](https://github.com/test-kitchen/kitchen-vra/commit/e1c185f8b38700abd98824cae67f01a33d36b710))
+
 ## [3.4.0](https://github.com/test-kitchen/kitchen-vra/compare/v3.3.4...v3.4.0) (2026-08-24)
 
 

data/lib/kitchen/driver/vra.rb

@@ -383,8 +383,10 @@ module Kitchen
         wait_for_request(destroy_request)
         info("Destroy request complete.")
 
-        File.delete(".kitchen/cached_vra") if File.exist?(".kitchen/cached_vra")
-        info("Removed cached file")
+        return unless File.exist?(CREDENTIALS_CACHE_FILE)
+
+        File.delete(CREDENTIALS_CACHE_FILE)
+        info("Removed the cached credentials in #{CREDENTIALS_CACHE_FILE}.")
       end
 
       # Builds the vRA catalog request for the configured blueprint.
@@ -431,21 +433,43 @@ module Kitchen
 
       # The vRA API client, built from the resolved credentials.
       #
-      # On any failure the credentials are re-prompted, on the assumption that
-      # what failed was authentication.
+      # Credentials are resolved once, when the client is first built. A
+      # failure to build it is assumed to be an authentication problem, so the
+      # credentials are asked for again and the client built a second time. A
+      # second failure is raised rather than swallowed.
       #
       # @return [Vra::Client]
+      # @raise [ArgumentError] if the credentials are still not usable after
+      #   re-prompting
       def vra_client
-        check_config config[:cache_credentials]
-        @client ||= ::Vra::Client.new(
-          base_url:   config[:base_url],
-          username:   config[:username],
-          password:   config[:password],
-          domain:     config[:domain],
-          verify_ssl: config[:verify_ssl]
-        )
-      rescue => _e
-        check_config true
+        @client ||= build_client
+      end
+
+      # Resolves the credentials and builds the client, asking for the
+      # credentials a second time if the first attempt fails.
+      #
+      # @return [Vra::Client]
+      # @raise [ArgumentError] if the second attempt fails as well
+      # @api private
+      def build_client
+        retried = false
+
+        begin
+          check_config(retried)
+          ::Vra::Client.new(
+            base_url:   config[:base_url],
+            username:   config[:username],
+            password:   config[:password],
+            domain:     config[:domain],
+            verify_ssl: config[:verify_ssl]
+          )
+        rescue => e
+          raise if retried
+
+          warn("Unable to build a vRA client: #{e.message}")
+          retried = true
+          retry
+        end
       end
 
       # Polls a vRA request until it completes or times out.
@@ -457,8 +481,6 @@ module Kitchen
       # @return [void]
       # @raise [Timeout::Error] if the request does not complete in time
       def wait_for_request(request)
-        # config = check_config config
-
         last_status = ""
         wait_time   = config[:request_timeout]
         sleep_time  = config[:request_refresh_rate]

data/lib/kitchen/driver/vra_version.rb

@@ -23,6 +23,6 @@ module Kitchen
   # Test Kitchen's driver plugins.
   module Driver
     # The version of the kitchen-vra gem.
-    VRA_VERSION = "3.4.0"
+    VRA_VERSION = "3.4.1"
   end
 end

data/spec/spec_helper.rb

@@ -19,13 +19,51 @@
 #
 
 require "webmock/rspec"
+require "tmpdir"
+require "fileutils"
 
+require "kitchen/driver/vra"
+require "kitchen/provisioner/dummy"
+require "kitchen/transport/dummy"
+require "kitchen/verifier/dummy"
+
+Dir[File.join(__dir__, "support", "**", "*.rb")].sort.each { |file| require file }
+
+# These specs never reach a vRA appliance. Everything the driver does is turn
+# kitchen.yml configuration into a vRA catalog request, and turn vRA's answers
+# back into Test Kitchen state, so an outbound request from a spec is a mistake
+# rather than a slow test.
 WebMock.disable_net_connect!(allow_localhost: true)
 
-if ENV["COVERAGE"]
-  require "simplecov"
-  SimpleCov.profiles.define "gem" do
-    command_name "Specs"
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
   end
-  SimpleCov.start "gem"
+
+  config.mock_with :rspec do |mocks|
+    # Fail if an example stubs a method the real object does not have. Almost
+    # every driver method is a call into the vmware-vra gem, so without this a
+    # rename there leaves the specs stubbing a method that no longer exists,
+    # passing while the driver is broken.
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+  # No `describe` on bare objects and no `should` -- the RSpec 2 DSL, kept
+  # alive only by monkey patches on Object and BasicObject.
+  config.disable_monkey_patching!
+
+  # Surface deprecations as failures rather than warnings that scroll past.
+  config.raise_errors_for_deprecations!
+
+  config.include VraApi
+
+  config.filter_run_when_matching :focus
+
+  # Run specs in random order to surface order dependencies. To debug one, fix
+  # the order by passing the seed printed after each run:
+  #     --seed 1234
+  config.order = :random
+  Kernel.srand config.seed
 end

data/spec/support/vra_api.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Stand-ins for the vmware-vra objects the driver talks to.
+#
+# The driver is a thin layer over the vmware-vra gem: nearly every method
+# either asks a Vra object something or hands it a request. A bare `double`
+# answers whatever it is told to answer, so a suite built on them keeps passing
+# after vmware-vra renames a method -- which is exactly the change most likely
+# to break the driver. Everything here is a verifying double checked against
+# the real class instead, so the specs fail when the gem moves underneath them.
+#
+# Each helper takes a hash of overrides so an example can say only what it
+# cares about:
+#
+#     vra_deployment(status: "CREATE_FAILED", failed?: true)
+module VraApi
+  # A VM inside a deployment, as returned by Vra::Deployment#resources.
+  #
+  # @param overrides [Hash] stubs to replace the defaults with
+  # @return [InstanceDouble<Vra::Resource>]
+  def vra_resource(overrides = {})
+    instance_double(
+      Vra::Resource,
+      {
+        id: "res-1",
+        deployment_id: "dep-1",
+        name: "test-server",
+        ip_address: "1.2.3.4",
+        vm?: true,
+      }.merge(overrides)
+    )
+  end
+
+  # A deployment. This is also what Vra::DeploymentRequest#submit hands back,
+  # which is why the driver waits on it and then asks it for its resources.
+  #
+  # @param overrides [Hash] stubs to replace the defaults with
+  # @return [InstanceDouble<Vra::Deployment>]
+  def vra_deployment(overrides = {})
+    instance_double(
+      Vra::Deployment,
+      {
+        id: "dep-1",
+        name: "test-instance",
+        status: "CREATE_SUCCESSFUL",
+        failed?: false,
+        completed?: true,
+        completion_details: nil,
+        refresh: nil,
+        resources: [vra_resource],
+      }.merge(overrides)
+    )
+  end
+
+  # A request against a deployment, such as the destroy action.
+  #
+  # @param overrides [Hash] stubs to replace the defaults with
+  # @return [InstanceDouble<Vra::Request>]
+  def vra_request(overrides = {})
+    instance_double(
+      Vra::Request,
+      {
+        id: "req-1",
+        status: "SUCCESSFUL",
+        completed?: true,
+        refresh: nil,
+        details: nil,
+      }.merge(overrides)
+    )
+  end
+
+  # A catalog item, as returned by Vra::Catalog#fetch_catalog_items.
+  #
+  # @param overrides [Hash] stubs to replace the defaults with
+  # @return [InstanceDouble<Vra::CatalogItem>]
+  def vra_catalog_item(overrides = {})
+    instance_double(
+      Vra::CatalogItem,
+      { id: "cat-1", name: "Ubuntu Server" }.merge(overrides)
+    )
+  end
+
+  # An unsubmitted catalog request.
+  #
+  # @param overrides [Hash] stubs to replace the defaults with
+  # @return [InstanceDouble<Vra::DeploymentRequest>]
+  def vra_deployment_request(overrides = {})
+    instance_double(
+      Vra::DeploymentRequest,
+      { submit: vra_deployment, set_parameters: nil }.merge(overrides)
+    )
+  end
+
+  # A vRA API client, wired to a catalog and a deployments collection.
+  #
+  # @param catalog [InstanceDouble<Vra::Catalog>, nil]
+  # @param deployments [InstanceDouble<Vra::Deployments>, nil]
+  # @return [InstanceDouble<Vra::Client>]
+  def vra_client(catalog: nil, deployments: nil)
+    instance_double(
+      Vra::Client,
+      catalog:     catalog || instance_double(Vra::Catalog),
+      deployments: deployments || instance_double(Vra::Deployments)
+    )
+  end
+end

data/spec/vra_spec.rb

@@ -18,43 +18,35 @@
 # limitations under the License.
 #
 
-require "spec_helper"
-require "tmpdir"
-require "fileutils"
-require "kitchen/driver/vra"
-require "kitchen/provisioner/dummy"
-require "kitchen/transport/dummy"
-require "kitchen/verifier/dummy"
-
-describe Kitchen::Driver::Vra do
+RSpec.describe Kitchen::Driver::Vra do
   let(:logged_output) { StringIO.new }
   let(:logger)        { Logger.new(logged_output) }
   let(:platform)      { Kitchen::Platform.new(name: "fake_platform") }
   let(:transport)     { Kitchen::Transport::Dummy.new }
-  let(:driver)        { Kitchen::Driver::Vra.new(config) }
+  let(:driver)        { described_class.new(config) }
 
   let(:config) do
     {
-      base_url:        "https://vra.corp.local",
-      username:        "myuser",
-      password:        "mypassword",
-      domain:          "mytenant.corp.com",
-      project_id:      "6ba69375-79d5-42c3-a099-7d32739f71a7",
-      image_mapping:   "VRA-nc-lnx-ce8.4-Docker",
-      flavor_mapping:  "Small",
-      verify_ssl:      true,
-      use_dns:         false,
+      base_url: "https://vra.corp.local",
+      username: "myuser",
+      password: "mypassword",
+      domain: "mytenant.corp.com",
+      project_id: "6ba69375-79d5-42c3-a099-7d32739f71a7",
+      image_mapping: "VRA-nc-lnx-ce8.4-Docker",
+      flavor_mapping: "Small",
+      verify_ssl: true,
+      use_dns: false,
       deployment_name: "test-instance",
-      catalog_id:      "1536b95d-68fe-3c68-9417-46ed24bee3ef",
+      catalog_id: "1536b95d-68fe-3c68-9417-46ed24bee3ef",
     }
   end
 
   let(:instance) do
     instance_double(Kitchen::Instance,
-                    logger:    logger,
-                    transport: transport,
-                    platform:  platform,
-                    to_str:    "instance_str")
+      logger:    logger,
+      transport: transport,
+      platform:  platform,
+      to_str:    "instance_str")
   end
 
   before do
@@ -71,6 +63,54 @@ describe Kitchen::Driver::Vra do
     end
   end
 
+  describe "configuration defaults" do
+    let(:config) do
+      {
+        base_url: "https://vra.corp.local",
+        domain: "mytenant.corp.com",
+        project_id: "6ba69375-79d5-42c3-a099-7d32739f71a7",
+        image_mapping: "VRA-nc-lnx-ce8.4-Docker",
+        flavor_mapping: "Small",
+      }
+    end
+
+    it "names the deployment after the platform under test" do
+      expect(driver[:deployment_name]).to eq("fake_platform")
+    end
+
+    it "connects by IP address rather than by name" do
+      expect(driver[:use_dns]).to be false
+    end
+
+    it "verifies the appliance certificate" do
+      expect(driver[:verify_ssl]).to be true
+    end
+
+    describe "the private key" do
+      let(:id_rsa) { File.expand_path("~/.ssh/id_rsa") }
+      let(:id_dsa) { File.expand_path("~/.ssh/id_dsa") }
+
+      before { allow(File).to receive(:exist?).and_return(false) }
+
+      it "prefers an RSA key" do
+        allow(File).to receive(:exist?).with(id_rsa).and_return(true)
+        allow(File).to receive(:exist?).with(id_dsa).and_return(true)
+
+        expect(driver[:private_key_path]).to eq(id_rsa)
+      end
+
+      it "falls back to a DSA key" do
+        allow(File).to receive(:exist?).with(id_dsa).and_return(true)
+
+        expect(driver[:private_key_path]).to eq(id_dsa)
+      end
+
+      it "is left unset when neither key exists" do
+        expect(driver[:private_key_path]).to be_nil
+      end
+    end
+  end
+
   describe "#create" do
     context "when the server is already created" do
       let(:state) { { deployment_id: "48959518-6a0d-46e1-8415-3749696b65f4" } }
@@ -81,14 +121,8 @@ describe Kitchen::Driver::Vra do
       end
     end
 
-    let(:state) { {} }
-    let(:resource) do
-      double("server1",
-             deployment_id: "e8706351-cf4c-4c12-acb7-c90cc683b22c",
-             name: "test-server",
-             ip_address: "1.2.3.4",
-             vm?: true)
-    end
+    let(:state)    { {} }
+    let(:resource) { vra_resource(deployment_id: "e8706351-cf4c-4c12-acb7-c90cc683b22c") }
 
     before do
       allow(driver).to receive(:request_server).and_return(resource)
@@ -115,22 +149,34 @@ describe Kitchen::Driver::Vra do
       expect(driver).to receive(:wait_for_server)
       driver.create(state)
     end
+
+    context "when a private key is configured" do
+      let(:config) { super().merge(private_key_path: "/home/me/.ssh/id_vra") }
+
+      it "tells the transport which key to connect with" do
+        driver.create(state)
+        expect(state[:ssh_key]).to eq("/home/me/.ssh/id_vra")
+      end
+    end
+
+    context "when no private key was found" do
+      let(:config) { super().merge(private_key_path: nil) }
+
+      it "leaves the transport to work out how to connect" do
+        driver.create(state)
+        expect(state).not_to have_key(:ssh_key)
+      end
+    end
   end
 
   describe "#hostname_for" do
-    let(:server) do
-      double("server",
-             deployment_id: "test_id",
-             name: "test_hostname",
-             ip_address: "1.2.3.4",
-             vm?: true)
-    end
+    let(:server) { vra_resource(deployment_id: "test_id", name: "test_hostname") }
 
     context "when use_dns is true and dns_suffix is defined" do
       let(:config) do
         {
-          use_dns:      true,
-          dns_suffix:   "my.com",
+          use_dns: true,
+          dns_suffix: "my.com",
         }
       end
 
@@ -143,20 +189,23 @@ describe Kitchen::Driver::Vra do
       let(:config) { { use_dns: true } }
 
       it "raises an exception if the server name is nil" do
-        allow(server).to receive(:name).and_return(nil)
-        expect { driver.hostname_for(server) }.to raise_error(RuntimeError)
+        expect { driver.hostname_for(vra_resource(name: nil)) }.to raise_error(RuntimeError)
       end
 
       it "returns the server name" do
         expect(driver.hostname_for(server)).to eq("test_hostname")
       end
+
+      it "does not go looking for an IP address" do
+        expect(server).not_to receive(:ip_address)
+        driver.hostname_for(server)
+      end
     end
 
     context "when use_dns is false" do
       it "falls back to the server name if no IP address exists" do
-        allow(server).to receive(:ip_address).and_return(nil)
         expect(driver).to receive(:warn)
-        expect(driver.hostname_for(server)).to eq("test_hostname")
+        expect(driver.hostname_for(vra_resource(ip_address: nil))).to eq("test-server")
       end
 
       it "returns the IP address if it exists" do
@@ -166,47 +215,32 @@ describe Kitchen::Driver::Vra do
   end
 
   describe "#request_server" do
-    let(:submitted_request) { double("submitted_request") }
-    let(:catalog_request)   { double("catalog_request") }
-    let(:resource1) do
-      double("server1",
-             id: "e8706351-cf4c-4c12-acb7-c90cc683b22c",
-             name: "server1",
-             ip_address: "1.2.3.4",
-             vm?: true)
-    end
-    let(:resource2) do
-      double("server2",
-             id: "9e2364cf-7af4-4b85-93fd-1f03ee2ac865",
-             name: "server2",
-             ip_address: "4.3.2.1",
-             vm?: true)
-    end
-    let(:resources) { [resource1] }
+    let(:deployment)      { vra_deployment(id: "74e26af9-2d2f-4889-a472-95dbcedb70b8", resources: resources) }
+    let(:catalog_request) { vra_deployment_request(submit: deployment) }
+    let(:resource1)       { vra_resource(id: "e8706351-cf4c-4c12-acb7-c90cc683b22c", name: "server1") }
+    let(:resource2)       { vra_resource(id: "9e2364cf-7af4-4b85-93fd-1f03ee2ac865", name: "server2") }
+    let(:resources)       { [resource1] }
 
     before do
       allow(driver).to receive(:catalog_request).and_return(catalog_request)
-      allow(catalog_request).to receive(:submit).and_return(submitted_request)
-      allow(submitted_request).to receive(:id).and_return("74e26af9-2d2f-4889-a472-95dbcedb70b8")
-      allow(submitted_request).to receive(:resources).and_return(resources)
-      allow(submitted_request).to receive(:failed?).and_return(false)
-      allow(driver).to receive(:wait_for_request).with(submitted_request)
+      allow(driver).to receive(:wait_for_request).with(deployment)
     end
 
     it "submits a catalog request" do
-      expect(driver.catalog_request).to receive(:submit).and_return(submitted_request)
+      expect(catalog_request).to receive(:submit).and_return(deployment)
       driver.request_server
     end
 
     it "waits for the request to complete" do
-      expect(driver).to receive(:wait_for_request).with(submitted_request)
+      expect(driver).to receive(:wait_for_request).with(deployment)
       driver.request_server
     end
 
     it "raises an exception if the request failed" do
-      allow(submitted_request).to receive(:failed?).and_return(true)
-      allow(submitted_request).to receive(:completion_details).and_return("it failed")
-      expect { driver.request_server }.to raise_error(RuntimeError)
+      allow(deployment).to receive(:failed?).and_return(true)
+      allow(deployment).to receive(:completion_details).and_return("it failed")
+
+      expect { driver.request_server }.to raise_error(RuntimeError, /it failed/)
     end
 
     describe "getting the server from the request" do
@@ -217,16 +251,26 @@ describe Kitchen::Driver::Vra do
       end
 
       context "when multiple servers are returned" do
+        let(:resources) { [resource1, resource2] }
+
         it "raises an exception" do
-          allow(submitted_request).to receive(:resources).and_return([ resource1, resource2 ])
-          expect { driver.request_server }.to raise_error(RuntimeError)
+          expect { driver.request_server }.to raise_error(RuntimeError, /more than one server/)
         end
       end
 
       context "when no servers are returned" do
+        let(:resources) { [] }
+
         it "raises an exception" do
-          allow(submitted_request).to receive(:resources).and_return([])
-          expect { driver.request_server }.to raise_error(RuntimeError)
+          expect { driver.request_server }.to raise_error(RuntimeError, /did not create any servers/)
+        end
+      end
+
+      context "when the deployment also contains things that are not VMs" do
+        let(:resources) { [vra_resource(id: "net-1", vm?: false), resource1] }
+
+        it "picks out the one VM" do
+          expect(driver.request_server).to eq(resource1)
         end
       end
     end
@@ -234,18 +278,25 @@ describe Kitchen::Driver::Vra do
     it "returns the the single server resource object" do
       expect(driver.request_server).to eq(resource1)
     end
+
+    context "when unique_name is set" do
+      let(:config) { super().merge(unique_name: true) }
+
+      it "reports the name vRA will give the deployment" do
+        allow(driver).to receive(:info)
+
+        driver.request_server
+
+        expect(driver).to have_received(:info)
+          .with("Deployment name is deployment_74e26af9-2d2f-4889-a472-95dbcedb70b8")
+      end
+    end
   end
 
   describe "#wait_for_server" do
     let(:connection) { instance.transport.connection(state) }
     let(:state)      { {} }
-    let(:resource1) do
-      double("server1",
-             id: "test_id",
-             name: "server1",
-             ip_address: "1.2.3.4",
-             vm?: true)
-    end
+    let(:resource1)  { vra_resource(id: "test_id", name: "server1") }
 
     before do
       allow(transport).to receive(:connection).and_return(connection)
@@ -331,10 +382,10 @@ describe Kitchen::Driver::Vra do
   end
 
   describe "#status" do
-    let(:deployments) { double("deployments") }
-    let(:vra_client)  { double("vra_client", deployments: deployments) }
+    let(:deployments) { instance_double(Vra::Deployments) }
+    let(:client)      { vra_client(deployments: deployments) }
 
-    before { allow(driver).to receive(:vra_client).and_return(vra_client) }
+    before { allow(driver).to receive(:vra_client).and_return(client) }
 
     it "reports an unknown status when state names no deployment" do
       expect(driver.status({})).to include(live: nil, state: "unknown")
@@ -348,8 +399,7 @@ describe Kitchen::Driver::Vra do
     end
 
     it "reports a successfully created deployment as live" do
-      allow(deployments).to receive(:by_id).with("dep-1")
-        .and_return(double(status: "CREATE_SUCCESSFUL"))
+      allow(deployments).to receive(:by_id).with("dep-1").and_return(vra_deployment)
 
       expect(driver.status(deployment_id: "dep-1")).to include(
         live: true, state: "CREATE_SUCCESSFUL", source: "driver",
@@ -358,24 +408,21 @@ describe Kitchen::Driver::Vra do
     end
 
     it "stamps when the check happened" do
-      allow(deployments).to receive(:by_id)
-        .and_return(double(status: "CREATE_SUCCESSFUL"))
+      allow(deployments).to receive(:by_id).and_return(vra_deployment)
 
       expect(driver.status(deployment_id: "dep-1")[:checked_at])
         .to match(/\A\d{4}-\d{2}-\d{2}T/)
     end
 
     it "reports a deployment still building as not live" do
-      allow(deployments).to receive(:by_id)
-        .and_return(double(status: "CREATE_INPROGRESS"))
+      allow(deployments).to receive(:by_id).and_return(vra_deployment(status: "CREATE_INPROGRESS"))
 
       expect(driver.status(deployment_id: "dep-1"))
         .to include(live: false, state: "CREATE_INPROGRESS")
     end
 
     it "names a failed deployment rather than reporting a bare false" do
-      allow(deployments).to receive(:by_id)
-        .and_return(double(status: "CREATE_FAILED"))
+      allow(deployments).to receive(:by_id).and_return(vra_deployment(status: "CREATE_FAILED", failed?: true))
 
       expect(driver.status(deployment_id: "dep-1"))
         .to include(live: false, state: "CREATE_FAILED")
@@ -389,44 +436,36 @@ describe Kitchen::Driver::Vra do
   end
 
   describe "#destroy" do
-    let(:deployment_id)     { "8c1a833a-5844-4100-b58c-9cab3543c958" }
+    let(:deployment_id)   { "8c1a833a-5844-4100-b58c-9cab3543c958" }
     let(:state)           { { deployment_id: deployment_id } }
-    let(:vra_client)      { double("vra_client") }
-    let(:deployments)       { double("resources") }
-    let(:destroy_request) { double("destroy_request") }
-    let(:resource) do
-      double("server1",
-             deployment_id: deployment_id,
-             name: "server1",
-             ip_address: "5.6.7.8",
-             vm?: true)
-    end
+    let(:deployments)     { instance_double(Vra::Deployments) }
+    let(:client)          { vra_client(deployments: deployments) }
+    let(:destroy_request) { vra_request(id: "6da65982-7c33-4e6e-b346-fdf4bcbf01ab") }
+    let(:deployment)      { vra_deployment(id: deployment_id, destroy: destroy_request) }
 
     before do
-      allow(driver).to receive(:vra_client).and_return(vra_client)
+      allow(driver).to receive(:vra_client).and_return(client)
       allow(driver).to receive(:wait_for_request).with(destroy_request)
-      allow(vra_client).to receive(:deployments).and_return(deployments)
-      allow(deployments).to receive(:by_id).and_return(resource)
-      allow(resource).to receive(:destroy).and_return(destroy_request)
-      allow(destroy_request).to receive(:id).and_return("6da65982-7c33-4e6e-b346-fdf4bcbf01ab")
+      allow(deployments).to receive(:by_id).and_return(deployment)
     end
 
     context "when the resource is not created" do
       let(:state) { {} }
+
       it "does not look up the resource if no resource ID exists" do
-        expect(vra_client.deployments).not_to receive(:by_id)
+        expect(deployments).not_to receive(:by_id)
         driver.destroy(state)
       end
     end
 
     it "looks up the resource record" do
-      expect(vra_client.deployments).to receive(:by_id).with(deployment_id).and_return(resource)
+      expect(deployments).to receive(:by_id).with(deployment_id).and_return(deployment)
       driver.destroy(state)
     end
 
     context "when the resource record cannot be found" do
       it "does not raise an exception" do
-        allow(vra_client.deployments).to receive(:by_id).with(deployment_id).and_raise(Vra::Exception::NotFound)
+        allow(deployments).to receive(:by_id).with(deployment_id).and_raise(Vra::Exception::NotFound)
         expect { driver.destroy(state) }.not_to raise_error
       end
     end
@@ -434,13 +473,13 @@ describe Kitchen::Driver::Vra do
     describe "creating the destroy request" do
       context "when the destroy method or server is not found" do
         it "does not raise an exception" do
-          allow(resource).to receive(:destroy).and_raise(Vra::Exception::NotFound)
+          allow(deployment).to receive(:destroy).and_raise(Vra::Exception::NotFound)
           expect { driver.destroy(state) }.not_to raise_error
         end
       end
 
       it "calls #destroy on the server" do
-        expect(resource).to receive(:destroy).and_return(destroy_request)
+        expect(deployment).to receive(:destroy).and_return(destroy_request)
         driver.destroy(state)
       end
     end
@@ -449,81 +488,201 @@ describe Kitchen::Driver::Vra do
       expect(driver).to receive(:wait_for_request).with(destroy_request)
       driver.destroy(state)
     end
-  end
 
-  describe "#catalog_request" do
-    let(:catalog_request) { double("catalog_request") }
-    let(:vra_client)      { double("vra_client") }
-    let(:catalog)         { double("catalog") }
-    before do
-      allow(driver).to receive(:vra_client).and_return(vra_client)
-      allow(vra_client).to receive(:catalog).and_return(catalog)
-      allow(catalog).to receive(:request).and_return(catalog_request)
-      %i{catalog_id= set_parameter}.each do |method|
-        allow(catalog_request).to receive(method)
+    describe "the cached credentials" do
+      let(:cache_dir) { Dir.mktmpdir("kitchen-vra-spec") }
+
+      around { |example| Dir.chdir(cache_dir) { example.run } }
+      after  { FileUtils.remove_entry(cache_dir) }
+
+      it "removes the cache file left behind by a previous run" do
+        FileUtils.mkdir_p(".kitchen")
+        File.write(".kitchen/cached_vra", "cached")
+
+        driver.destroy(state)
+
+        expect(File.exist?(".kitchen/cached_vra")).to be false
+      end
+
+      it "does not claim to have removed a cache file that was never written" do
+        expect(driver).not_to receive(:info).with(/Removed.*cached/i)
+
+        driver.destroy(state)
       end
     end
+  end
+
+  describe "#catalog_request" do
+    let(:deployment_request) { vra_deployment_request }
+    let(:catalog)            { instance_double(Vra::Catalog, request: deployment_request) }
+    let(:client)             { vra_client(catalog: catalog) }
+
+    before { allow(driver).to receive(:vra_client).and_return(client) }
 
     it "creates a catalog_request" do
-      expect(vra_client.catalog).to receive(:request).and_return(catalog_request)
+      expect(catalog).to receive(:request).and_return(deployment_request)
       driver.catalog_request
     end
 
-    context "when option parameters are not supplied" do
+    it "asks for the configured image, flavor, project and version" do
+      expect(catalog).to receive(:request).with(
+        "1536b95d-68fe-3c68-9417-46ed24bee3ef",
+        hash_including(
+          image_mapping:  "VRA-nc-lnx-ce8.4-Docker",
+          flavor_mapping: "Small",
+          project_id:     "6ba69375-79d5-42c3-a099-7d32739f71a7",
+          version:        nil
+        )
+      ).and_return(deployment_request)
+
+      driver.catalog_request
+    end
+
+    it "names the deployment" do
+      expect(catalog).to receive(:request)
+        .with(anything, hash_including(name: "test-instance"))
+        .and_return(deployment_request)
+
+      driver.catalog_request
+    end
+
+    context "when unique_name is set" do
+      let(:config) { super().merge(unique_name: true) }
+
+      it "leaves vRA to name the deployment after the request" do
+        expect(catalog).to receive(:request)
+          .with(anything, hash_excluding(:name))
+          .and_return(deployment_request)
+
+        driver.catalog_request
+      end
+    end
+
+    context "when the catalog item is named rather than identified" do
       let(:config) do
-        {
-          base_url:        "https://vra.corp.local",
-          username:        "myuser",
-          password:        "mypassword",
-          domain:          "domain.corp.com",
-          verify_ssl:      true,
-          project_id:      "6ba69375-79d5-42c3-a099-7d32739f71a7",
-          image_mapping:   "VRA-nc-lnx-ce8.4-Docker",
-          flavor_mapping:  "Small",
-          catalog_id:      "2kabc423-af89-56fc-990a-82fab34ed12",
-        }
+        super().reject { |key, _value| key == :catalog_id }
+          .merge(catalog_name: "Ubuntu Server")
       end
 
+      it "looks the name up and requests the ID it resolves to" do
+        allow(catalog).to receive(:fetch_catalog_items).with("Ubuntu Server")
+          .and_return([vra_catalog_item(id: "cat-9")])
+        expect(catalog).to receive(:request).with("cat-9", anything).and_return(deployment_request)
+
+        driver.catalog_request
+      end
+
+      context "when the name matches nothing in the catalog" do
+        before do
+          allow(catalog).to receive(:fetch_catalog_items).and_return([])
+          allow(driver).to receive(:error)
+        end
+
+        it "fails rather than requesting an unknown catalog item" do
+          expect { driver.catalog_request }
+            .to raise_error(Kitchen::InstanceFailure, /without a valid catalog/)
+        end
+
+        it "says which name it could not resolve" do
+          expect { driver.catalog_request }.to raise_error(Kitchen::InstanceFailure)
+
+          expect(driver).to have_received(:error).with(/Ubuntu Server/)
+        end
+      end
+    end
+
+    context "when neither a catalog ID nor a catalog name is given" do
+      let(:config) { super().reject { |key, _value| key == :catalog_id } }
+
+      it "fails before talking to vRA" do
+        expect(catalog).not_to receive(:request)
+        expect { driver.catalog_request }.to raise_error(Kitchen::InstanceFailure)
+      end
+    end
+
+    context "when option parameters are not supplied" do
       it "does not attempt to set params on the catalog_request" do
-        expect(catalog_request).not_to receive(:set_parameters)
+        expect(deployment_request).not_to receive(:set_parameters)
         driver.catalog_request
       end
     end
 
     context "when extra parameters are set" do
       let(:config) do
-        {
-          base_url:         "https://vra.corp.local",
-          username:         "myuser",
-          password:         "mypassword",
-          domain:           "mydomain.corp.com",
-          verify_ssl:       true,
-          project_id:       "6ba69375-79d5-42c3-a099-7d32739f71a7",
-          image_mapping:    "VRA-nc-lnx-ce8.4-Docker",
-          flavor_mapping:   "Small",
-          catalog_id:      "2kabc423-af89-56fc-990a-82fab34ed12",
-          extra_parameters: { "key1" => { type: "string", value: "value1" },
-                              "key2" => { type: "integer", value: 123 } },
-        }
+        super().merge(
+          extra_parameters: {
+            "key1" => { type: "string", value: "value1" },
+            "key2" => { type: "integer", value: 123 },
+          }
+        )
       end
 
       it "sets extra parameters" do
-        expect(catalog_request).to receive(:set_parameters).with("key1", { type: "string", value: "value1" })
-        expect(catalog_request).to receive(:set_parameters).with("key2", { type: "integer", value: 123 })
+        expect(deployment_request).to receive(:set_parameters).with("key1", { type: "string", value: "value1" })
+        expect(deployment_request).to receive(:set_parameters).with("key2", { type: "integer", value: 123 })
         driver.catalog_request
       end
     end
   end
 
   describe "#vra_client" do
+    let(:client) { vra_client }
+
     it "sets up a client object" do
       expect(Vra::Client).to receive(:new).with(base_url:   config[:base_url],
-                                                username:   config[:username],
-                                                password:   config[:password],
-                                                domain:     config[:domain],
-                                                verify_ssl: config[:verify_ssl])
+        username:   config[:username],
+        password:   config[:password],
+        domain:     config[:domain],
+        verify_ssl: config[:verify_ssl])
       driver.vra_client
     end
+
+    it "builds the client once and hands the same one back" do
+      expect(Vra::Client).to receive(:new).once.and_return(client)
+
+      expect(driver.vra_client).to eq(client)
+      expect(driver.vra_client).to eq(client)
+    end
+
+    context "when cache_credentials is enabled" do
+      let(:config) { super().merge(cache_credentials: true) }
+
+      before { allow(driver).to receive(:c_save) }
+
+      it "does not prompt for credentials it already has" do
+        allow(Vra::Client).to receive(:new).and_return(client)
+        expect(driver).not_to receive(:ask)
+
+        driver.vra_client
+      end
+    end
+
+    context "when the client cannot be built" do
+      before do
+        allow(driver).to receive(:warn)
+        allow(driver).to receive(:check_config)
+      end
+
+      it "re-prompts for the credentials and tries once more" do
+        attempts = 0
+        allow(Vra::Client).to receive(:new) do
+          attempts += 1
+          raise ArgumentError, "Username and password are required" if attempts == 1
+
+          client
+        end
+
+        expect(driver.vra_client).to eq(client)
+        expect(driver).to have_received(:check_config).with(true)
+      end
+
+      it "raises rather than handing back something that is not a client" do
+        allow(Vra::Client).to receive(:new)
+          .and_raise(ArgumentError, "Username and password are required")
+
+        expect { driver.vra_client }.to raise_error(ArgumentError)
+      end
+    end
   end
 
   describe "#wait_for_request" do
@@ -534,21 +693,42 @@ describe Kitchen::Driver::Vra do
 
     context "when the requests completes normally, 3 loops" do
       it "only refreshes the request 3 times" do
-        request = double("request")
-        allow(request).to receive(:status)
-        allow(request).to receive(:completed?).exactly(3).times.and_return(false, false, true)
-        expect(request).to receive(:refresh).exactly(3).times
+        request = vra_request(status: nil)
+        allow(request).to receive(:completed?).and_return(false, false, true)
 
         driver.wait_for_request(request)
+
+        expect(request).to have_received(:refresh).exactly(3).times
       end
     end
 
     context "when the request is completed on the first loop" do
       it "only refreshes the request 1 time" do
-        request = double("request")
-        allow(request).to receive(:status)
-        allow(request).to receive(:completed?).once.and_return(true)
-        expect(request).to receive(:refresh).once
+        request = vra_request(status: nil)
+
+        driver.wait_for_request(request)
+
+        expect(request).to have_received(:refresh).once
+      end
+    end
+
+    it "reports a status once, not on every poll" do
+      request = vra_request(status: "IN_PROGRESS")
+      allow(request).to receive(:completed?).and_return(false, false, true)
+      allow(driver).to receive(:info)
+
+      driver.wait_for_request(request)
+
+      expect(driver).to have_received(:info).with("Current request status: IN_PROGRESS").once
+    end
+
+    context "with a slower refresh rate configured" do
+      let(:config) { super().merge(request_refresh_rate: 10) }
+
+      it "waits that long between polls" do
+        request = vra_request(status: nil)
+        allow(request).to receive(:completed?).and_return(false, true)
+        expect(driver).to receive(:sleep).with(10)
 
         driver.wait_for_request(request)
       end
@@ -556,16 +736,19 @@ describe Kitchen::Driver::Vra do
 
     context "when the timeout is exceeded" do
       it "prints a warning and exits" do
-        request = double("request")
         allow(Timeout).to receive(:timeout).and_raise(Timeout::Error)
-        expect { driver.wait_for_request(request) }.to raise_error(Timeout::Error)
+        allow(driver).to receive(:error)
+
+        expect { driver.wait_for_request(vra_request) }.to raise_error(Timeout::Error)
+        expect(driver).to have_received(:error).with(/did not complete in 600 seconds/)
       end
     end
 
     context "when a non-timeout exception is raised" do
       it "raises the original exception" do
-        request = double("request")
+        request = vra_request
         allow(request).to receive(:refresh).and_raise(RuntimeError)
+
         expect { driver.wait_for_request(request) }.to raise_error(RuntimeError)
       end
     end
@@ -583,6 +766,13 @@ describe Kitchen::Driver::Vra do
 
     after { FileUtils.remove_entry(cache_dir) }
 
+    # A second driver reading the cache the first one wrote, which is what the
+    # next `kitchen` run is.
+    def reader(overrides = {})
+      described_class.new(config.merge(overrides).reject { |k, _v| %i{username password}.include?(k) })
+        .tap { |driver| allow(driver).to receive(:instance).and_return(instance) }
+    end
+
     describe "#c_save" do
       it "creates the cache file" do
         driver.c_save
@@ -602,18 +792,29 @@ describe Kitchen::Driver::Vra do
         driver.c_save
         expect(File.read(cache_file)).not_to include("mypassword")
       end
+
+      it "does not write the username in the clear either" do
+        driver.c_save
+        expect(File.read(cache_file)).not_to include("myuser")
+      end
+
+      it "reports a cache it could not write rather than failing the run" do
+        allow(FileUtils).to receive(:mkdir_p).and_raise(Errno::EACCES)
+        expect(driver).to receive(:warn).with(/Unable to save credentials/)
+
+        expect { driver.c_save }.not_to raise_error
+      end
     end
 
     describe "#c_load" do
       it "restores credentials written by #c_save" do
         driver.c_save
 
-        reader = Kitchen::Driver::Vra.new(config.reject { |k, _v| %i{username password}.include?(k) })
-        allow(reader).to receive(:instance).and_return(instance)
-        reader.c_load
+        loader = reader
+        loader.c_load
 
-        expect(reader[:username]).to eq("myuser")
-        expect(reader[:password]).to eq("mypassword")
+        expect(loader[:username]).to eq("myuser")
+        expect(loader[:password]).to eq("mypassword")
       end
 
       it "does nothing when no cache file exists" do
@@ -624,9 +825,7 @@ describe Kitchen::Driver::Vra do
       it "refuses a cache written against a different base_url" do
         driver.c_save
 
-        other = Kitchen::Driver::Vra.new(config.merge(base_url: "https://other.corp.local")
-                                               .reject { |k, _v| %i{username password}.include?(k) })
-        allow(other).to receive(:instance).and_return(instance)
+        other = reader(base_url: "https://other.corp.local")
         expect(other).to receive(:warn).with(/Failed to load cached credentials/)
         other.c_load
 
@@ -638,30 +837,97 @@ describe Kitchen::Driver::Vra do
         driver.c_save
         File.write(cache_file, File.read(cache_file).succ)
 
-        loader = Kitchen::Driver::Vra.new(config.reject { |k, _v| %i{username password}.include?(k) })
-        allow(loader).to receive(:instance).and_return(instance)
+        loader = reader
         expect(loader).to receive(:warn).with(/Failed to load cached credentials/)
         loader.c_load
 
         expect(loader[:username]).to be_nil
       end
+
+      it "refuses a cache written in a layout it does not recognize" do
+        FileUtils.mkdir_p(File.dirname(cache_file))
+        File.write(cache_file, "v0:whatever")
+
+        loader = reader
+        expect(loader).to receive(:warn).with(/unrecognized cache format/)
+        loader.c_load
+
+        expect(loader[:username]).to be_nil
+      end
     end
 
     describe "#check_config" do
-      it "uses the cache instead of prompting" do
-        driver.c_save
+      it "keeps the credentials it was configured with" do
+        allow(driver).to receive(:ask)
+
+        driver.check_config
+
+        expect(driver[:username]).to eq("myuser")
+        expect(driver[:password]).to eq("mypassword")
+        expect(driver).not_to have_received(:ask)
+      end
 
-        reader = Kitchen::Driver::Vra.new(config.reject { |k, _v| %i{username password}.include?(k) })
-        allow(reader).to receive(:instance).and_return(instance)
-        allow(ENV).to receive(:[]).and_call_original
-        allow(ENV).to receive(:[]).with("VRA_USER_NAME").and_return(nil)
-        allow(ENV).to receive(:[]).with("VRA_USER_PASSWORD").and_return(nil)
-        expect(reader).not_to receive(:ask)
+      it "asks again when told to, even though it has credentials" do
+        allow(driver).to receive(:ask).and_return("newuser", "newpass")
 
-        reader.check_config
+        driver.check_config(true)
 
-        expect(reader[:username]).to eq("myuser")
-        expect(reader[:password]).to eq("mypassword")
+        expect(driver[:username]).to eq("newuser")
+        expect(driver[:password]).to eq("newpass")
+      end
+
+      it "does not write a cache file unless asked to" do
+        driver.check_config
+
+        expect(File.exist?(cache_file)).to be false
+      end
+
+      context "when cache_credentials is enabled" do
+        let(:config) { super().merge(cache_credentials: true) }
+
+        it "writes the credentials out for the next run" do
+          driver.check_config
+
+          expect(File.exist?(cache_file)).to be true
+        end
+      end
+
+      context "when the config names no credentials" do
+        it "reads them from the environment" do
+          stub_const("ENV", ENV.to_hash.merge("VRA_USER_NAME" => "envuser",
+            "VRA_USER_PASSWORD" => "envpass"))
+          loader = reader
+          expect(loader).not_to receive(:ask)
+
+          loader.check_config
+
+          expect(loader[:username]).to eq("envuser")
+          expect(loader[:password]).to eq("envpass")
+        end
+
+        it "uses the cache instead of prompting" do
+          driver.c_save
+
+          stub_const("ENV", ENV.to_hash.reject { |key, _v| key.start_with?("VRA_USER_") })
+          loader = reader
+          expect(loader).not_to receive(:ask)
+
+          loader.check_config
+
+          expect(loader[:username]).to eq("myuser")
+          expect(loader[:password]).to eq("mypassword")
+        end
+
+        it "prompts as a last resort" do
+          stub_const("ENV", ENV.to_hash.reject { |key, _v| key.start_with?("VRA_USER_") })
+          loader = reader
+          allow(loader).to receive(:ask).and_return("askeduser", "askedpass")
+
+          loader.check_config
+
+          expect(loader[:username]).to eq("askeduser")
+          expect(loader[:password]).to eq("askedpass")
+        end
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-vra
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.4.1
 platform: ruby
 authors:
 - Chef Community Tools Team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-kitchen
@@ -97,13 +97,14 @@ files:
 - ".gitignore"
 - ".markdownlint.yaml"
 - ".release-please-manifest.json"
+- ".rspec"
 - ".rubocop.yml"
 - ".yamllint"
 - ".yardopts"
 - CHANGELOG.md
 - CONTRIBUTING.md
 - Gemfile
-- LICENSE.txt
+- LICENSE
 - README.md
 - Rakefile
 - kitchen-vra.gemspec
@@ -112,6 +113,7 @@ files:
 - release-please-config.json
 - renovate.json
 - spec/spec_helper.rb
+- spec/support/vra_api.rb
 - spec/vra_spec.rb
 homepage: https://github.com/test-kitchen/kitchen-vra
 licenses: