kitchen-vro 1.2.2 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1a6899da676fb0df64521fdb9d7cee84203814ee7c39c72fcac972ff560b94b
-  data.tar.gz: e657a749324c80812ce60c376105be7466a320b8a048559316685f1b1b770349
+  metadata.gz: 4fc3cc482e4cfc62f76afb15b09ebb335f5264994f182ca23df1188633894fe1
+  data.tar.gz: 1ef0ecb0109e0c2f6aa97a2a231b859a4328bc757043119db1842b32d8fc469b
 SHA512:
-  metadata.gz: 7e0ddc75df599792061715375990fbca7a536a6f43daf481282165f877ba7ede51f2d7275a1d7bf646d5d9d4f86d76c7dbce8a75c0ed4d8f15fe10ee8b7995d5
-  data.tar.gz: 428309a5ea9fa075bc53c8c93acec33226a0936afcfed0fcd4a46259a8d13535eddde664878174f13e1bf331ac3207de5eab0c4b36ced5b18257624f757d1205
+  metadata.gz: ba21a283e5a306d50aaba9623d7a3c8456ef949021465e97566c110a52435c8dfa4b8b0ea4fdb4f2fd56d16d0e5b743a1f0c84df67869b1d65b344cb666e3fca
+  data.tar.gz: 7e22ba6bcaff192cb73975f998326316001a919d3b13e56983e9f250e8d8511980a9dd80c8520cb38f81fbb7d2a1d429394be4774d6b3275e7e3a1947d00061a

data/.github/workflows/publish.yaml

@@ -9,13 +9,13 @@ jobs:
   release-please:
     runs-on: ubuntu-latest
     steps:
-      - uses: googleapis/release-please-action@v4
+      - uses: googleapis/release-please-action@v5
         id: release
         with:
           token: ${{ secrets.PORTER_GITHUB_TOKEN }}
 
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         if: ${{ steps.release.outputs.release_created }}
 
       - name: Build and publish to GitHub Package

data/.gitignore

@@ -7,3 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+doc/
+.yardoc

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.2.2"
+  ".": "1.2.4"
 }

data/.rubocop.yml

@@ -1,10 +1,9 @@
 ---
 require:
-  - chefstyle
+  - cookstyle/chefstyle
 
 AllCops:
-  Include:
-    - "**/*.rb"
+  TargetRubyVersion: 3.1
   Exclude:
     - "vendor/**/*"
     - "spec/**/*"

data/.yamllint

@@ -0,0 +1,6 @@
+---
+extends: default
+rules:
+  line-length:
+    max: 256
+    level: warning

data/.yardopts

@@ -0,0 +1,11 @@
+--markup markdown
+--output-dir doc
+--readme README.md
+--title "kitchen-vro"
+--protected
+--private
+lib/**/*.rb
+-
+CHANGELOG.md
+CONTRIBUTING.md
+LICENSE.txt

data/CHANGELOG.md

@@ -1,43 +1,68 @@
 # VRO Changelog
 
-## [1.2.2](https://github.com/test-kitchen/kitchen-vro/compare/v1.2.1...v1.2.2) (2024-06-19)
+## Unreleased
 
+* chore(deps): update googleapis/release-please-action action to v5 ([#31](https://github.com/test-kitchen/kitchen-vro/pull/31)) ([309dc1d](https://github.com/test-kitchen/kitchen-vro/commit/309dc1d))
+* chore(deps): update actions/checkout action to v7 ([#32](https://github.com/test-kitchen/kitchen-vro/pull/32)) ([df90c2f](https://github.com/test-kitchen/kitchen-vro/commit/df90c2f))
+* Require Ruby 3.1+ and modernize CI ([#33](https://github.com/test-kitchen/kitchen-vro/pull/33)) ([ba13a07](https://github.com/test-kitchen/kitchen-vro/commit/ba13a07))
+* Remove chefstyle and add the gem version badge ([#34](https://github.com/test-kitchen/kitchen-vro/pull/34)) ([88348d7](https://github.com/test-kitchen/kitchen-vro/commit/88348d7))
+* Let cookstyle decide which files to lint ([#35](https://github.com/test-kitchen/kitchen-vro/pull/35)) ([c252779](https://github.com/test-kitchen/kitchen-vro/commit/c252779))
+* Docs: rewrite README for new users and split contributor docs ([#36](https://github.com/test-kitchen/kitchen-vro/pull/36)) ([c32f1a3](https://github.com/test-kitchen/kitchen-vro/commit/c32f1a3))
 
-### Bug Fixes
+## [1.2.4](https://github.com/test-kitchen/kitchen-vro/compare/v1.2.3...v1.2.4) (2026-08-24)
 
-* release please deprecation ([#25](https://github.com/test-kitchen/kitchen-vro/issues/25)) ([2fc4da5](https://github.com/test-kitchen/kitchen-vro/commit/2fc4da56e566b52d631f5ccbf661131f14609c13))
 
-## [1.2.1](https://github.com/test-kitchen/kitchen-vro/compare/v1.2.1...v1.2.1) (2024-06-09)
-
-
-### Features
+### Bug Fixes
 
-* update workflows ([#15](https://github.com/test-kitchen/kitchen-vro/issues/15)) ([277a0ab](https://github.com/test-kitchen/kitchen-vro/commit/277a0aba28a50b99272962973a589898dd144fad))
-* Workflows ([#10](https://github.com/test-kitchen/kitchen-vro/issues/10)) ([3f51d13](https://github.com/test-kitchen/kitchen-vro/commit/3f51d13a5afc683f6f3c1c4816f37ec0c65c4d63))
+* correct the doubled scheme in the gemspec homepage ([#41](https://github.com/test-kitchen/kitchen-vro/issues/41)) ([0dc7756](https://github.com/test-kitchen/kitchen-vro/commit/0dc7756b703c2cd758e842dee0725f2124682569))
+* require cookstyle/chefstyle so style checks actually run ([#43](https://github.com/test-kitchen/kitchen-vro/issues/43)) ([8b8d6b4](https://github.com/test-kitchen/kitchen-vro/commit/8b8d6b45d96ad5f436d0a947a10a15a5fac7ec4d))
+* require test-kitchen 3.0 or newer ([#39](https://github.com/test-kitchen/kitchen-vro/issues/39)) ([f54a6c9](https://github.com/test-kitchen/kitchen-vro/commit/f54a6c9dae6b681875a1ec9b5d9a0cc8efd0bd97))
 
+## [1.2.3](https://github.com/test-kitchen/kitchen-vro/compare/v1.2.2...v1.2.3) (2026-01-22)
 
-### Miscellaneous Chores
+### Bug Fixes
 
-* bump verion to 1.2.1 ([#22](https://github.com/test-kitchen/kitchen-vro/issues/22)) ([498f90f](https://github.com/test-kitchen/kitchen-vro/commit/498f90ff6618b643795d29adbc120c5b4dc4fb26))
-* release 1.2.0 ([#18](https://github.com/test-kitchen/kitchen-vro/issues/18)) ([3356c6f](https://github.com/test-kitchen/kitchen-vro/commit/3356c6f22b91c02283ec4d31a7ac6179ecd27876))
+* bump tk dep to allow tk 4 ([#29](https://github.com/test-kitchen/kitchen-vro/issues/29)) ([2a89105](https://github.com/test-kitchen/kitchen-vro/commit/2a89105a15a65c974d4f9793950c8c6ceab963c1))
 
-## [1.2.0](https://github.com/test-kitchen/kitchen-vro/compare/v1.2.0...v1.2.0) (2024-04-10)
+### Other Changes
 
+* chore(deps): update actions/checkout action to v6 ([#28](https://github.com/test-kitchen/kitchen-vro/pull/28)) ([008fa0e](https://github.com/test-kitchen/kitchen-vro/commit/008fa0e))
 
-### Miscellaneous Chores
+## [1.2.2](https://github.com/test-kitchen/kitchen-vro/compare/v1.2.1...v1.2.2) (2024-06-19)
 
-* release 1.2.0 ([#18](https://github.com/test-kitchen/kitchen-vro/issues/18)) ([3356c6f](https://github.com/test-kitchen/kitchen-vro/commit/3356c6f22b91c02283ec4d31a7ac6179ecd27876))
+### Bug Fixes
 
-## [1.2.0](https://github.com/test-kitchen/kitchen-vro/compare/v1.1.0...v1.2.0) (2024-02-28)
+* release please deprecation ([#25](https://github.com/test-kitchen/kitchen-vro/issues/25)) ([2fc4da5](https://github.com/test-kitchen/kitchen-vro/commit/2fc4da56e566b52d631f5ccbf661131f14609c13))
 
+## [1.2.1](https://github.com/test-kitchen/kitchen-vro/compare/v1.2.1...v1.2.1) (2024-06-09)
 
 ### Features
 
 * update workflows ([#15](https://github.com/test-kitchen/kitchen-vro/issues/15)) ([277a0ab](https://github.com/test-kitchen/kitchen-vro/commit/277a0aba28a50b99272962973a589898dd144fad))
+* Workflows ([#10](https://github.com/test-kitchen/kitchen-vro/issues/10)) ([3f51d13](https://github.com/test-kitchen/kitchen-vro/commit/3f51d13a5afc683f6f3c1c4816f37ec0c65c4d63))
 
-## [1.1.0](https://github.com/test-kitchen/kitchen-vro/compare/v1.0.0...v1.1.0) (2023-11-27)
 
+### Miscellaneous Chores
 
-### Features
+* bump verion to 1.2.1 ([#22](https://github.com/test-kitchen/kitchen-vro/issues/22)) ([498f90f](https://github.com/test-kitchen/kitchen-vro/commit/498f90ff6618b643795d29adbc120c5b4dc4fb26))
+* release 1.2.0 ([#18](https://github.com/test-kitchen/kitchen-vro/issues/18)) ([3356c6f](https://github.com/test-kitchen/kitchen-vro/commit/3356c6f22b91c02283ec4d31a7ac6179ecd27876))
+
+### Other Changes
 
 * Workflows ([#10](https://github.com/test-kitchen/kitchen-vro/issues/10)) ([3f51d13](https://github.com/test-kitchen/kitchen-vro/commit/3f51d13a5afc683f6f3c1c4816f37ec0c65c4d63))
+* adding to travis ([e197f8b](https://github.com/test-kitchen/kitchen-vro/commit/e197f8b))
+* disabling ruby 2.0 in travis due to vcoworkflows bug ([7e40c92](https://github.com/test-kitchen/kitchen-vro/commit/7e40c92))
+* adding slack notifications to travis ([d158e38](https://github.com/test-kitchen/kitchen-vro/commit/d158e38))
+* disabling rvm 2.0.0 again ([6027c75](https://github.com/test-kitchen/kitchen-vro/commit/6027c75))
+* fixing travis notifications ([#2](https://github.com/test-kitchen/kitchen-vro/pull/2)) ([c76470e](https://github.com/test-kitchen/kitchen-vro/commit/c76470e))
+* Bump Rubocop to resolve CVE ([#6](https://github.com/test-kitchen/kitchen-vro/pull/6)) ([07665c6](https://github.com/test-kitchen/kitchen-vro/commit/07665c6))
+* Update kitchen-vro.gemspec ([1b5439b](https://github.com/test-kitchen/kitchen-vro/commit/1b5439b))
+
+* chore(deps): update dependency webmock to v3 ([#11](https://github.com/test-kitchen/kitchen-vro/pull/11)) ([8f3b368](https://github.com/test-kitchen/kitchen-vro/commit/8f3b368))
+* Fix gemspec dependencies test-kitchen logic ([#14](https://github.com/test-kitchen/kitchen-vro/pull/14)) ([011d339](https://github.com/test-kitchen/kitchen-vro/commit/011d339))
+* chore(deps): update google-github-actions/release-please-action action to v4 ([#13](https://github.com/test-kitchen/kitchen-vro/pull/13)) ([49aa642](https://github.com/test-kitchen/kitchen-vro/commit/49aa642))
+
+## 1.0.0 (2015-08-25)
+
+* empty repo ([604d029](https://github.com/test-kitchen/kitchen-vro/commit/604d029))
+* Initial release of kitchen-vro ([#1](https://github.com/test-kitchen/kitchen-vro/pull/1)) ([45f2291](https://github.com/test-kitchen/kitchen-vro/commit/45f2291))

data/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to kitchen-vro
+
+We'd love to hear from you if this driver doesn't perform the way you expect. Bug reports, feature requests, and pull requests are all welcome.
+
+## Reporting issues
+
+Report bugs and request features on the [issue tracker](https://github.com/test-kitchen/kitchen-vro/issues). For bugs, please include:
+
+- the version of kitchen-vro and Test Kitchen you are using
+- your vRO version
+- your `kitchen.yml` with credentials and internal hostnames removed
+- the input and output parameters of the workflows involved
+- the output of the failing command, ideally with `-l debug`
+
+## Development setup
+
+Clone the repository and install the dependencies:
+
+```sh
+git clone https://github.com/test-kitchen/kitchen-vro.git
+cd kitchen-vro
+bundle install
+```
+
+## Running the tests
+
+Run the unit tests and the style check together:
+
+```sh
+bundle exec rake
+```
+
+Run them individually:
+
+```sh
+bundle exec rake test    # RSpec unit tests
+bundle exec rake style   # Cookstyle / RuboCop
+```
+
+To run a single spec file:
+
+```sh
+bundle exec rspec spec/kitchen/driver/vro_spec.rb
+```
+
+Many style offenses can be corrected automatically:
+
+```sh
+bundle exec cookstyle -a
+```
+
+The unit tests stub the vRO client, so they do not contact an appliance and do
+not require credentials.
+
+### Manual testing against vRO
+
+Changes that touch workflow execution or parameter handling should also be
+exercised against a real appliance, since the stubbed tests cannot catch
+API-level regressions.
+
+You will need a create workflow and a destroy workflow meeting the requirements
+in the README's Workflow design section. Set the password in the environment
+rather than in `kitchen.yml`, and confirm after `kitchen destroy` that the
+destroy workflow actually removed the machine — a create that fails partway
+through can leave one behind.
+
+## Submitting changes
+
+1. Fork the repository.
+2. Create a feature branch off `main`.
+3. Make your change, adding or updating tests to cover it.
+4. Make sure `bundle exec rake` passes.
+5. Push the branch to your fork and open a pull request.
+
+Please keep pull requests focused on a single change — it makes review much
+faster. Update the documentation in `README.md` when you add or change a
+configuration option, and the Workflow design section when you change what the
+driver expects of a workflow.
+
+## Release process
+
+Releases are handled by the maintainers.
+
+1. Update `lib/kitchen/driver/version.rb` with the new version.
+2. Update `CHANGELOG.md`.
+3. Merge to `main`; the [publish workflow](.github/workflows/publish.yaml) builds
+   the gem and pushes it to RubyGems.

data/Gemfile

@@ -1,14 +1,17 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 gemspec
 
 group :test do
-  gem 'bundler'
-  gem 'rake'
-  gem 'rspec', '~> 3.2'
-  gem 'webmock',   '~> 3.0'
+  gem "rake"
+  gem "rspec", "~> 3.2"
+  gem "webmock",   "~> 3.0"
 end
 
-group :chefstyle do
-  gem 'chefstyle', '~> 2.2', '>= 2.2.3'
+group :docs do
+  gem "yard"
+end
+
+group :cookstyle do
+  gem "cookstyle"
 end

data/README.md

@@ -1,78 +1,146 @@
 # kitchen-vro
 
-A driver to allow Test Kitchen to consume VMware resources provisioned by
-way of vRealize Orchestrator workflows.
+[![Gem Version](https://badge.fury.io/rb/kitchen-vro.svg)](https://badge.fury.io/rb/kitchen-vro)
 
-vRO allows you to create any workflow you can imagine, but our plugin needs
-to make some assumptions about the workflows you design in order to properly
-provision and destroy resources.  Therefore, please pay special attention to
-the **Workflow Design** section below and ensure your workflows adhere to
-these design requirements.
+A [Test Kitchen](https://kitchen.ci/) driver that provisions and destroys VMware resources by running [vRealize Orchestrator](https://www.vmware.com/products/vrealize-orchestrator.html) (vRO) workflows, so you can test your cookbooks and infrastructure code against machines built by your own workflows.
 
-## Installation
+Because a vRO workflow can do anything, this driver has to make some assumptions about the ones it calls. Read [Workflow design](#workflow-design) before you start — your create and destroy workflows must expose specific parameters for the driver to work.
 
-Add this line to your application's Gemfile:
+> This documentation uses [Cinc Workstation](https://cinc.sh/) and the `cinc` commands throughout. Everything here works identically with Chef Workstation — see [Using with Chef](#using-with-chef).
 
-```ruby
-gem 'kitchen-vro'
-```
+## Requirements
 
-And then execute:
+- Ruby 3.1 or later (already satisfied if you use Cinc Workstation)
+- Access to a vRealize Orchestrator appliance
+- A **create** workflow and a **destroy** workflow meeting the requirements in [Workflow design](#workflow-design)
+- Permission to execute those workflows
 
-```shell
-bundle
-```
+## Installation
 
-Or install it yourself as:
+This driver ships as part of [Cinc Workstation](https://cinc.sh/start/workstation/). If you have Cinc Workstation installed, there is nothing else to install.
 
-```shell
+To install it into a standalone Ruby:
+
+```sh
 gem install kitchen-vro
 ```
 
-Or even better, install it via ChefDK:
+Or with Bundler, add it to your `Gemfile`:
 
-```shell
-chef gem install kitchen-vro
+```ruby
+gem "kitchen-vro"
 ```
 
-## Usage
+...then run `bundle install`.
 
-After installing the gem as described above, edit your .kitchen.yml file to set the driver to 'vro' and supply your login credentials:
+## Quick Start
 
 ```yaml
+---
 driver:
   name: vro
   vro_username: user@domain.com
-  vro_password: MyS33kretPassword
+  vro_password: <%= ENV['VRO_PASSWORD'] %>
   vro_base_url: https://vra.corp.local:8281
+  create_workflow_name: Create TK Server
+  destroy_workflow_name: Destroy TK Server
+
+provisioner:
+  name: cinc_infra
+
+verifier:
+  name: cinc_auditor
+
+platforms:
+  - name: centos-9
+
+suites:
+  - name: default
+    run_list:
+      - recipe[my_cookbook::default]
 ```
 
-Additionally, the following parameters are required, either globally or per-platform:
+Then run the full test cycle:
+
+```sh
+cinc kitchen test
+```
+
+Or step through it:
+
+```sh
+cinc kitchen create    # run the create workflow and wait for it
+cinc kitchen converge  # apply your cookbook
+cinc kitchen verify    # run your tests
+cinc kitchen destroy   # run the destroy workflow
+```
 
-* **create_workflow_name**: The name of the vRO workflow to execute to create a server.
-* **destroy_workflow_name**: The name of the vRO workflow to execute to destroy a server.
+Keep the password out of `kitchen.yml` by reading it from the environment, as above.
 
-There are a number of optional parameters you can configure as well:
+## Configuration
 
-* **create_workflow_id**: If your create workflow name is not unique within vRO, you can use
-   this parameter to specify the workflow unique ID.
-* **destroy_workflow_id**: If your destroy workflow name is not unique within vRO, you can use
-   this parameter to specify the workflow unique ID.
-* **create_workflow_parameters**: A hash of key-value pairs of parameters to pass to your
-   create workflow.
-* **destroy_workflow_parameters**: A hash of key-value pairs of parameters to pass to your
-   destroy workflow.
-* **request_timeout**: Number of seconds to wait for a vRO workflow to execute.  Default: 300
-* **vro_disable_ssl_verify**: Disable SSL validation.  Default: false
+All options below are set under the `driver:` key in `kitchen.yml`, or per platform under `platforms[].driver:`.
 
-An example `.kitchen.yml` that uses a combination of global and per-platform
-settings might look like this:
+### Required
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `vro_base_url` | *none* | Base URL of the vRO appliance, e.g. `https://vra.corp.local:8281`. Required. |
+| `vro_username` | *none* | Username to authenticate with, e.g. `user@domain.com`. Required. |
+| `vro_password` | *none* | Password to authenticate with. Required. |
+| `create_workflow_name` | *none* | Name of the vRO workflow that creates a server. Required. |
+| `destroy_workflow_name` | *none* | Name of the vRO workflow that destroys a server. Required. |
+
+### Workflow selection and parameters
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `create_workflow_id` | `nil` | Unique ID of the create workflow. Use this when the workflow name is not unique within vRO. |
+| `destroy_workflow_id` | `nil` | Unique ID of the destroy workflow. Use this when the workflow name is not unique within vRO. |
+| `create_workflow_parameters` | `{}` | Hash of key/value parameters passed to the create workflow. |
+| `destroy_workflow_parameters` | `{}` | Hash of key/value parameters passed to the destroy workflow. |
+
+### Connection
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `request_timeout` | `300` | Seconds to wait for a workflow to finish executing. |
+| `vro_disable_ssl_verify` | `false` | Skip TLS certificate validation. Only use this against a lab appliance with a self-signed certificate. |
+
+## Workflow design
+
+There is no limit to what your vRO workflows can do, but they must meet the
+following requirements for the driver to drive them.
+
+### Create workflow
+
+- Must have an output parameter called **`ip_address`**, which Test Kitchen
+  connects to in order to bootstrap and test the node.
+- Must have an output parameter called **`server_id`**, a unique ID for the
+  server that was created. The driver passes this to the destroy workflow later.
+- Must end with a raised exception if creation did not succeed. The workflow
+  status must not be `completed` when it has failed, or the driver will treat a
+  failed build as a success.
+
+### Destroy workflow
+
+- Must have an input parameter called **`server_id`**, which the driver
+  populates with the value returned by the create workflow.
+- Must end with a raised exception if destruction did not succeed. The workflow
+  status must not be `completed` when it has failed.
+
+## Examples
+
+### Per-platform workflow parameters
+
+Global settings live under `driver:`, and the parameters that differ per
+operating system live under each platform:
 
 ```yaml
 driver:
   name: vro
   vro_username: user@domain.com
-  vro_password: MyS33kretPassword
+  vro_password: <%= ENV['VRO_PASSWORD'] %>
   vro_base_url: https://vra.corp.local:8281
   create_workflow_name: Create TK Server
   destroy_workflow_name: Destroy TK Server
@@ -92,55 +160,98 @@ platforms:
         memory: 4096
 ```
 
-## Workflow Design
+### Workflow names that are not unique
 
-There are no limits as to what you can do with your vRO workflows!  However,
-they must meet the following requirements.
+```yaml
+driver:
+  name: vro
+  vro_base_url: https://vra.corp.local:8281
+  vro_username: user@domain.com
+  vro_password: <%= ENV['VRO_PASSWORD'] %>
+  create_workflow_name: Create TK Server
+  create_workflow_id: 9f4d4a7e-1234-4b8b-9c2f-77b6c9f0e111
+  destroy_workflow_name: Destroy TK Server
+  destroy_workflow_id: 3a1b2c3d-5678-4e9f-8a1b-22c4d6e8f0a1
+```
+
+### Passing parameters to the destroy workflow
+
+```yaml
+driver:
+  name: vro
+  vro_base_url: https://vra.corp.local:8281
+  vro_username: user@domain.com
+  vro_password: <%= ENV['VRO_PASSWORD'] %>
+  create_workflow_name: Create TK Server
+  destroy_workflow_name: Destroy TK Server
+  destroy_workflow_parameters:
+    force: true
+    reason: test-kitchen cleanup
+```
+
+### Slow workflows
+
+```yaml
+driver:
+  name: vro
+  vro_base_url: https://vra.corp.local:8281
+  vro_username: user@domain.com
+  vro_password: <%= ENV['VRO_PASSWORD'] %>
+  create_workflow_name: Create TK Server
+  destroy_workflow_name: Destroy TK Server
+  request_timeout: 1800
+```
+
+### Lab appliance with a self-signed certificate
 
-### Create Workflow
+```yaml
+driver:
+  name: vro
+  vro_base_url: https://vro.lab.local:8281
+  vro_username: user@lab.local
+  vro_password: <%= ENV['VRO_PASSWORD'] %>
+  create_workflow_name: Create TK Server
+  destroy_workflow_name: Destroy TK Server
+  vro_disable_ssl_verify: true
+```
 
-* Must contain an output parameter called `ip_address` that Test Kitchen can
-   connect to in order to bootstrap and test your node.
-* Must contain an output parameter called `server_id` that is a unique ID of
-   the server created.  Test Kitchen will provide this value to the Destroy
-   Workflow in order to request the destruction of the server once testing is
-   complete.
-* Must end the workflow with a raised exception if the creation did not
-   succeed.  The workflow status must not be 'completed.'
+## Troubleshooting
 
-### Destroy Workflow
+**Test Kitchen cannot connect after a successful create.** Check that the create
+workflow really does return an `ip_address` output parameter, and that the
+address is reachable from where you are running Test Kitchen.
 
-* Must contain an input parameter called `server_id` that Test Kitchen will
-   populate with the unique ID returned from the Create Workflow output.
-* Must end the workflow with a raised exception if the creation did not
-     succeed.  The workflow status must not be 'completed.'
+**A failed build is reported as successful.** The workflow finished with status
+`completed` despite failing. Raise an exception in the workflow on failure, as
+described in [Workflow design](#workflow-design).
 
-## License and Authors
+**`kitchen destroy` does nothing, or destroys the wrong machine.** The destroy
+workflow must take a `server_id` input parameter, and the create workflow must
+return a matching `server_id` output.
 
-Author:: Chef Partner Engineering (<partnereng@chef.io>)
+**The workflow times out.** Increase `request_timeout`; the default is 300
+seconds, which is short for a full VM build.
 
-Copyright:: Copyright (c) 2015 Chef Software, Inc.
+## Using with Chef
 
-License:: Apache License, Version 2.0
+This driver is not tied to Cinc. The examples above use Cinc Workstation and the `cinc_infra` provisioner, but the driver works exactly the same with [Chef Workstation](https://www.chef.io/downloads/tools/workstation) — run `kitchen` instead of `cinc kitchen`, and use `chef_infra` instead of `cinc_infra`:
 
-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
+```yaml
+provisioner:
+  name: chef_infra
 
-```text
-http://www.apache.org/licenses/LICENSE-2.0
+verifier:
+  name: inspec
 ```
 
-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.
+No driver configuration changes are needed.
 
 ## Contributing
 
-We'd love to hear from you if this doesn't perform in the manner you expect. Please log a GitHub issue, or even better, submit a Pull Request with a fix!
+We'd love to hear from you if this doesn't perform the way you expect. Bug reports and pull requests are welcome on [GitHub](https://github.com/test-kitchen/kitchen-vro). See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, how to run the tests, and the release process.
+
+## License and Authors
+
+Author: Chef Partner Engineering (<partnereng@chef.io>)
 
-1. Fork it ( <https://github.com/chef-partners/kitchen-vro/fork> )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

data/Rakefile

@@ -2,15 +2,33 @@ require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 begin
-  require "chefstyle"
+  require "cookstyle/chefstyle"
   require "rubocop/rake_task"
   RuboCop::RakeTask.new(:style) do |task|
     task.options += ["--display-cop-names", "--no-color"]
   end
 rescue LoadError
-  puts "chefstyle is not available. (sudo) gem install chefstyle to do style checking."
+  puts "cookstyle is not available. (sudo) gem install cookstyle to do style checking."
 end
 
 RSpec::Core::RakeTask.new(:test)
 
 task default: %i{test style}
+
+begin
+  require "yard"
+
+  # Options and the file list live in .yardopts so that a bare `yard` from the
+  # command line produces exactly what `rake doc` does.
+  YARD::Rake::YardocTask.new(:doc)
+
+  desc "List anything in lib/ that is still undocumented"
+  task :doc_coverage do
+    sh "yard stats --list-undoc"
+  end
+rescue LoadError
+  desc "Generate YARD documentation (not installed)"
+  task :doc do
+    abort "YARD is not installed. Run: bundle install"
+  end
+end

data/kitchen-vro.gemspec

@@ -3,20 +3,20 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "kitchen/driver/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "kitchen-vro"
+  spec.name = "kitchen-vro"
+  spec.required_ruby_version = ">= 3.1"
   spec.version       = Kitchen::Driver::VRO_VERSION
   spec.authors       = ["Test Kitchen Team"]
   spec.email         = ["help@sous-chefs.org"]
   spec.summary       = "A Test Kitchen driver for VMware vRealize Orchestrator (vRO)"
   spec.description   = spec.summary
-  spec.homepage      = "https://https://github.com/test-kitchen/kitchen-vro"
-  spec.license       = "Apache 2.0"
+  spec.homepage      = "https://github.com/test-kitchen/kitchen-vro"
+  spec.license       = "Apache-2.0"
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = []
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "test-kitchen", ">= 1.4", "< 4"
+  spec.add_dependency "test-kitchen", ">= 3.0", "< 5"
   spec.add_dependency "vcoworkflows", "~> 0.2"
 end

data/lib/kitchen/driver/version.rb

@@ -16,8 +16,11 @@
 # limitations under the License.
 #
 
+# Test Kitchen's top-level namespace.
 module Kitchen
+  # Test Kitchen's driver plugins.
   module Driver
-    VRO_VERSION = "1.2.2".freeze
+    # The version of the kitchen-vro gem.
+    VRO_VERSION = "1.2.4".freeze
   end
 end

data/lib/kitchen/driver/vro.rb

@@ -21,8 +21,28 @@ require "vcoworkflows"
 require_relative "version"
 
 module Kitchen
+  # Test Kitchen's driver plugins.
   module Driver
+    # Test Kitchen driver for VMware vRealize Orchestrator (vRO).
+    #
+    # This driver does not build a machine itself. It runs two vRO workflows
+    # you supply -- one to create a server and one to destroy it -- and treats
+    # their output parameters as the machine's identity.
+    #
+    # The create workflow must return two output parameters, +server_id+ and
+    # +ip_address+, both non-empty. +server_id+ is stored in instance state
+    # and handed back to the destroy workflow, and +ip_address+ becomes the
+    # address the transport connects to. A workflow that completes without
+    # those two fails the +create+, since there would be nothing to connect to
+    # and nothing to tear down later.
+    #
+    # @see https://www.vmware.com/products/vrealize-orchestrator.html vRealize Orchestrator
     class Vro < Kitchen::Driver::Base
+      # @!attribute [rw] workflow_name
+      #   @return [String] name of the workflow currently being run
+      # @!attribute [rw] workflow_id
+      #   @return [String, nil] id of the workflow currently being run, used
+      #     to disambiguate when several workflows share a name
       attr_accessor :workflow_name, :workflow_id
 
       kitchen_driver_api_version 2
@@ -41,10 +61,19 @@ module Kitchen
       default_config :destroy_workflow_parameters, {}
       default_config :request_timeout, 300
 
+      # @return [String] the driver's display name in `kitchen list`
       def name
         "vRO"
       end
 
+      # Runs the create workflow and waits for the server to be reachable.
+      #
+      # Returns immediately if state already names a server, so a re-run does
+      # not create a second one.
+      #
+      # @param state [Hash] mutable instance state; gains +server_id+ and
+      #   +hostname+
+      # @return [void]
       def create(state)
         return unless state[:server_id].nil?
 
@@ -56,6 +85,10 @@ module Kitchen
         info("Server #{state[:hostname]} (#{state[:server_id]}) ready.")
       end
 
+      # Runs the destroy workflow for the server named in state.
+      #
+      # @param state [Hash] instance state naming the server
+      # @return [void]
       def destroy(state)
         return if state[:server_id].nil?
 
@@ -64,6 +97,9 @@ module Kitchen
         info("Server #{state[:hostname]} (#{state[:server_id]}) destroyed.")
       end
 
+      # Connection settings for the vRO API.
+      #
+      # @return [VcoWorkflows::Config]
       def vro_config
         @vro_config ||= VcoWorkflows::Config.new(
           url: config[:vro_base_url],
@@ -73,6 +109,13 @@ module Kitchen
         )
       end
 
+      # Client for the workflow named by {#workflow_name} and {#workflow_id}.
+      #
+      # Memoized, and reset by {#set_workflow_vars}, so switching from the
+      # create workflow to the destroy workflow builds a fresh client rather
+      # than reusing the previous workflow's.
+      #
+      # @return [VcoWorkflows::Workflow]
       def vro_client
         @vro_client ||= VcoWorkflows::Workflow.new(
           workflow_name,
@@ -81,16 +124,32 @@ module Kitchen
         )
       end
 
+      # @return [Boolean] whether to verify the vRO server's TLS certificate
       def verify_ssl?
         !config[:vro_disable_ssl_verify]
       end
 
+      # Points the driver at a different workflow.
+      #
+      # Clears the memoized client, which is what makes it safe to run the
+      # destroy workflow after the create workflow in the same process.
+      #
+      # @param name [String] workflow name
+      # @param id [String, nil] workflow id, when the name is ambiguous
+      # @return [void]
       def set_workflow_vars(name, id)
         @vro_client    = nil
         @workflow_name = name
         @workflow_id   = id
       end
 
+      # Runs the create workflow and records what it produced.
+      #
+      # @param state [Hash] mutable instance state; gains +server_id+ and
+      #   +hostname+
+      # @return [void]
+      # @raise [RuntimeError] if the workflow did not complete successfully,
+      #   or did not return a usable +server_id+ and +ip_address+
       def execute_create_workflow(state)
         set_workflow_vars(config[:create_workflow_name], config[:create_workflow_id])
         set_workflow_parameters(config[:create_workflow_parameters])
@@ -105,6 +164,11 @@ module Kitchen
         state[:hostname]  = output_parameter_value("ip_address")
       end
 
+      # Runs the destroy workflow, passing it the stored +server_id+.
+      #
+      # @param state [Hash] instance state naming the server
+      # @return [void]
+      # @raise [RuntimeError] if the workflow did not complete successfully
       def execute_destroy_workflow(state)
         set_workflow_vars(config[:destroy_workflow_name], config[:destroy_workflow_id])
         set_workflow_parameters(config[:destroy_workflow_parameters])
@@ -115,6 +179,11 @@ module Kitchen
         raise "The workflow did not complete successfully. Check the vRO UI for more info." unless workflow_successful?
       end
 
+      # Submits the current workflow for execution.
+      #
+      # @return [void]
+      # @raise [RestClient::BadRequest] if vRO rejects the request, after
+      #   logging the response body, which is where vRO puts the reason
       def execute_workflow
         vro_client.execute
       rescue RestClient::BadRequest => e
@@ -125,6 +194,10 @@ module Kitchen
         raise
       end
 
+      # Polls until the running workflow's token is no longer alive.
+      #
+      # @return [void]
+      # @raise [Timeout::Error] if it does not finish within +request_timeout+
       def wait_for_workflow
         wait_time = config[:request_timeout]
         Timeout.timeout(wait_time) do
@@ -139,6 +212,13 @@ module Kitchen
         raise Timeout::Error, "Workflow did not complete in #{wait_time} seconds. Please check the vRO UI for more information."
       end
 
+      # Waits for the transport to accept a connection.
+      #
+      # A server that never becomes reachable is destroyed before the error is
+      # re-raised, so a failed create does not leave a machine behind.
+      #
+      # @param state [Hash] instance state describing how to connect
+      # @return [void]
       def wait_for_server(state)
         instance.transport.connection(state).wait_until_ready
       rescue
@@ -147,24 +227,39 @@ module Kitchen
         raise
       end
 
+      # Sets input parameters on the current workflow.
+      #
+      # @param data [Hash] parameter names to values; names are stringified
+      # @return [void]
       def set_workflow_parameters(data) # rubocop:disable Style/AccessorMethodName
         data.each do |key, value|
           vro_client.parameter(key.to_s, value)
         end
       end
 
+      # Output parameters from the finished workflow run.
+      #
+      # @return [Hash{String => VcoWorkflows::WorkflowParameter}]
       def output_parameters
         @output_parameters ||= vro_client.token.output_parameters
       end
 
+      # @param key [String] output parameter name
+      # @return [String] the parameter's value, stringified
       def output_parameter_value(key)
         output_parameters[key].value.to_s
       end
 
+      # @param key [String] output parameter name
+      # @return [Boolean] true when the parameter is missing or empty
       def output_parameter_empty?(key)
         output_parameter_value(key).nil? || output_parameter_value(key).empty?
       end
 
+      # Checks that the create workflow returned what the driver needs.
+      #
+      # @return [void]
+      # @raise [RuntimeError] if +server_id+ or +ip_address+ is absent or empty
       def validate_create_output_parameters!
         raise "The workflow output did not contain a server_id and ip_address parameter." unless
           output_parameters.key?("server_id") && output_parameters.key?("ip_address")
@@ -173,6 +268,7 @@ module Kitchen
         raise "The ip_address parameter was empty." if output_parameter_empty?("ip_address")
       end
 
+      # @return [Boolean] whether the workflow run reached the "completed" state
       def workflow_successful?
         vro_client.token.state == "completed"
       end

data/spec/vro_spec.rb

@@ -64,6 +64,96 @@ describe Kitchen::Driver::Vro do
     allow(driver).to receive(:instance).and_return(instance)
   end
 
+  describe 'plugin metadata' do
+    it 'is a Test Kitchen driver' do
+      expect(driver).to be_a(Kitchen::Driver::Base)
+    end
+
+    it 'shows up as vRO in kitchen list' do
+      expect(driver.name).to eq('vRO')
+    end
+
+    it 'reports its own gem version to kitchen diagnose' do
+      expect(driver.diagnose_plugin[:version]).to eq(Kitchen::Driver::VRO_VERSION)
+    end
+  end
+
+  describe 'configuration' do
+    it 'verifies TLS by default' do
+      expect(driver[:vro_disable_ssl_verify]).to eq(false)
+    end
+
+    it 'defaults to a 300 second workflow timeout' do
+      expect(driver[:request_timeout]).to eq(300)
+    end
+
+    it 'defaults both workflow ids to nil so the name is used alone' do
+      config.delete(:create_workflow_id)
+      config.delete(:destroy_workflow_id)
+
+      expect(driver[:create_workflow_id]).to be_nil
+      expect(driver[:destroy_workflow_id]).to be_nil
+    end
+
+    it 'defaults both workflow parameter sets to empty' do
+      expect(driver[:create_workflow_parameters]).to eq({})
+      expect(driver[:destroy_workflow_parameters]).to eq({})
+    end
+
+    %i[vro_username vro_password vro_base_url
+       create_workflow_name destroy_workflow_name].each do |key|
+      it "refuses to run without #{key}" do
+        config.delete(key)
+
+        expect { driver.finalize_config!(instance) }
+          .to raise_error(Kitchen::UserError, /#{key}/)
+      end
+    end
+  end
+
+  describe '#set_workflow_vars' do
+    it 'points the driver at the named workflow' do
+      driver.set_workflow_vars('Some Workflow', 'workflow-9')
+
+      expect(driver.workflow_name).to eq('Some Workflow')
+      expect(driver.workflow_id).to eq('workflow-9')
+    end
+
+    it 'discards the memoized client so the next call builds a new one' do
+      first = double('first client')
+      allow(VcoWorkflows::Workflow).to receive(:new).and_return(first)
+      allow(driver).to receive(:vro_config).and_return(double('config'))
+      driver.set_workflow_vars('Create Workflow', 'workflow-1')
+      expect(driver.vro_client).to eq(first)
+
+      second = double('second client')
+      allow(VcoWorkflows::Workflow).to receive(:new).and_return(second)
+      driver.set_workflow_vars('Destroy Workflow', 'workflow-2')
+
+      expect(driver.vro_client).to eq(second)
+    end
+  end
+
+  describe '#workflow_successful?' do
+    let(:vro_client) { double('vro_client') }
+
+    before do
+      allow(driver).to receive(:vro_client).and_return(vro_client)
+    end
+
+    it 'is true when vRO reports the run completed' do
+      allow(vro_client).to receive(:token).and_return(double(state: 'completed'))
+
+      expect(driver.workflow_successful?).to eq(true)
+    end
+
+    it 'is false for any other state' do
+      allow(vro_client).to receive(:token).and_return(double(state: 'failed'))
+
+      expect(driver.workflow_successful?).to eq(false)
+    end
+  end
+
   describe '#create' do
     context 'when a server already exists' do
       let(:state) { { server_id: 'server-12345' } }
@@ -142,11 +232,11 @@ describe Kitchen::Driver::Vro do
 
     context 'when vro_disable_ssl_verify is false' do
       before do
-        config[:vro_disable_ssl_verify] = true
+        config[:vro_disable_ssl_verify] = false
       end
 
       it 'returns true' do
-        expect(driver.verify_ssl?).to eq(false)
+        expect(driver.verify_ssl?).to eq(true)
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-vro
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.2.4
 platform: ruby
 authors:
 - Test Kitchen Team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-19 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-kitchen
@@ -16,20 +16,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '3.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '4'
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '3.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '4'
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: vcoworkflows
   requirement: !ruby/object:Gem::Requirement
@@ -59,7 +59,10 @@ files:
 - ".release-please-manifest.json"
 - ".rspec"
 - ".rubocop.yml"
+- ".yamllint"
+- ".yardopts"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -71,9 +74,9 @@ files:
 - renovate.json
 - spec/spec_helper.rb
 - spec/vro_spec.rb
-homepage: https://https://github.com/test-kitchen/kitchen-vro
+homepage: https://github.com/test-kitchen/kitchen-vro
 licenses:
-- Apache 2.0
+- Apache-2.0
 metadata: {}
 post_install_message:
 rdoc_options: []
@@ -83,17 +86,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: A Test Kitchen driver for VMware vRealize Orchestrator (vRO)
-test_files:
-- spec/spec_helper.rb
-- spec/vro_spec.rb
+test_files: []