# Test Kitchen: Ruby Setup for Isolated Platform Testing > Test Kitchen is a Ruby integration tool for exercising infrastructure code and software on isolated target platforms. Its default path combines a generated kitchen.yml, a Vagrant-backed instance, and a shell provisioner through a small command-line workflow. **test-kitchen/test-kitchen** — Test Kitchen is an integration tool for developing and testing infrastructure code and software on isolated target platforms - Repository: https://github.com/test-kitchen/test-kitchen - Stars: 1,893 · Forks: 577 - Language: Ruby - License: NOASSERTION - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/test-kitchen-test-kitchen ## Test Kitchen's integration-test boundary for Ruby projects Test Kitchen addresses the gap between writing infrastructure code and exercising it in an environment that represents the intended target platform. The README defines it as an integration tool for infrastructure code and software, while the generated kitchen.yml records what is being tested and the platforms on which it should run. A suite and platform pairing becomes an instance. This makes the project relevant to cookbook authors, infrastructure-code developers, and software teams that need an explicit target-environment workflow. The tool does not supply the application or infrastructure payload by itself. It coordinates instances and delegates provisioning to an appropriate provisioner. The README identifies Chef, Cinc, and other configuration-management tooling as dependencies of the Ruby environment from which Kitchen runs. That distinction matters: an instance can represent the target, but successful execution still depends on the chosen provisioner, its gems, and the code supplied to it. The default generated setup uses Vagrant with the shell provisioner. Test Kitchen therefore acts as the control layer for creating and operating an isolated environment, not as a replacement for Vagrant or for configuration-management software. Its value is the consistent CLI and configuration model around those parts. ## From kitchen.yml to a converged Test Kitchen instance The documented flow begins when `kitchen init` writes kitchen.yml in the project base directory. That file describes suites and target platforms. Test Kitchen treats each suite and platform combination as an instance, which gives commands a concrete name to operate on. The README uses `default-ubuntu-2004` as an example instance generated through the default setup. Calling `kitchen converge` selects an instance and applies its configuration through the configured provisioner. In the default Vagrant-backed shell setup, the shell provisioner handles the setup work, although the README does not specify its internal command format. Test Kitchen then exposes the same lifecycle for other operations. `kitchen list` enumerates configured instances, while `kitchen destroy` removes all instances. Running `kitchen test` on a supported cookbook project is documented as a way to run through the instances in serial. This architecture separates selection from execution. The instance identifier in the converge command chooses the target, kitchen.yml defines the matrix, and provisioners handle the environment-specific work. Kitchen can support libraries, Chef Infra cookbooks, or empty projects, but those projects still need a meaningful provisioner and test payload. A generated file alone does not establish that the target was configured or that a product passed. ## Installing test-kitchen and creating the first instance Test Kitchen is distributed as a RubyGem. The README gives two installation routes: install the published gem directly, or declare it in a Gemfile when Bundler already manages project dependencies. For a standalone Ruby environment, this command installs the gem from RubyGems: ```bash gem install test-kitchen ``` The command should make the `kitchen` executable available within that Ruby environment. A Bundler-based project can instead declare the dependency: ```ruby gem "test-kitchen" ``` After dependency resolution, install the bundle with: ```bash bundle install ``` Generate the initial test configuration from the project directory: ```bash kitchen init ``` The README states that this creates kitchen.yml in the project base directory. It also says the default file describes a Vagrant-backed instance using the shell provisioner. Check that generated file before running lifecycle commands because Test Kitchen relies on it to determine which instances exist. ## Running, inspecting, and destroying the default target First list the configured instances. This is the quickest way to copy the exact name accepted by the remaining commands: ```bash kitchen list ``` The output should show instances derived from the suites and platforms in kitchen.yml. The README uses `default-ubuntu-2004` as the name for a converge operation: ```bash kitchen converge default-ubuntu-2004 ``` Convergence applies the configured provisioning process to that instance. To inspect the commands available for a particular workflow, request help for the test subcommand: ```bash kitchen help test ``` For additional command-line logging, enable debug output on the test operation: ```bash kitchen test -l debug ``` The README separately mentions a `log_level` item in a provisioner section of `.kitchen.yml` for tools such as `chef-solo` or `chef-infra`. That example uses `.kitchen.yml`, whereas `kitchen init` is documented as creating `kitchen.yml`. The README does not explain whether both names are used for different purposes or whether one is conventional in older setups, so a new user should follow the generated filename rather than assuming they are interchangeable. When an instance is no longer needed, remove all managed instances with: ```bash kitchen destroy ``` The README describes this as destroying all instances, so a narrower cleanup command is not documented in the quick start. ## Provisioners and runtime dependencies in Test Kitchen's Ruby boundary The default shell provisioner offers a direct starting point, but Test Kitchen's documented design also accommodates Chef and Cinc workflows. The README specifically names `chef-solo` and `chef-infra` as provisioner examples when discussing `log_level`. It also says Chef, Cinc, and other configuration-management tools come from the Ruby environment used to run Kitchen, such as system gems, Cinc Workstation, or Chef Workstation. That dependency boundary creates two practical setup routes. A project can use the gems and provisioners available to the Ruby environment, or it can use Kitchen from a workstation installation that already contains those tools. This is the meaningful alternative to the quick-start choice: the orchestration command remains Test Kitchen, while the source of the provisioner and configuration tooling changes. The README does not provide complete provisioner configuration schemas, authentication instructions, or supported platform matrices. It also does not show how target images are selected beyond the suites and platforms represented in kitchen.yml. The repository contains multiple Kitchen YAML files, templates, schemas, and integration-related Gemfiles, but the README does not describe their contents. Claims about particular drivers, transport implementations, or exact configuration keys would therefore exceed the documented setup. ## Operational limits, release cadence, and licensing boundaries Test Kitchen is not a self-contained virtual machine test suite. Vagrant is part of the default generated instance, and Chef, Cinc, or another configuration-management tool must come from the execution environment. Installation can therefore succeed while convergence later fails because an underlying driver, guest platform, Ruby dependency, or provisioner is unavailable. The README does not document dependency diagnosis beyond general support resources and command-line debug logging. The repository is not archived. Its last push was on 2026-10-13, and the release history lists v4.1.5 on 2026-10-01, v4.1.4 on 2026-09-04, and v4.1.3 on 2026-08-24. The README says the project aims to follow Semantic Versioning 2.0.0. These facts indicate recent development activity, but they do not remove the cost of reviewing changes to kitchen.yml conventions, provisioner behavior, Ruby dependencies, and platform support when upgrading. There is also a licensing metadata mismatch that an adopter should resolve before incorporation. The repository metadata classifies the license as a custom licence that GitHub cannot classify, while the README says "Apache License, Version 2.0" and links to LICENSE. The README supports identifying the discrepancy, but it does not support drawing a compliance conclusion. Review the actual LICENSE file and any organization-specific requirements rather than relying on the GitHub classification or README label alone. ## Conclusion Test Kitchen fits infrastructure and software developers who want repeatable commands for creating, converging, testing, and destroying isolated platform instances. It is less suitable for a project that has no platform integration requirement or no need for separate environment definitions. Before adoption, inspect kitchen.yml, confirm that the Ruby environment provides the required configuration-management tooling, and evaluate the LICENSE file because the repository metadata calls it a custom licence while the README identifies Apache License, Version 2.0. ## FAQ ### How do I install Test Kitchen for a Ruby project? Install the RubyGem with `gem install test-kitchen`, or add `gem "test-kitchen"` to a Gemfile and run `bundle install`. The README links to the Getting Started Guide for broader setup instructions. ### What does `kitchen init` create in Test Kitchen? It creates kitchen.yml in the project base directory. The README says the file describes the test targets and platforms, with each suite and platform combination forming an instance. ### Which commands create, test, and remove Test Kitchen instances? `kitchen init` creates kitchen.yml, `kitchen list` shows instances, and `kitchen converge default-ubuntu-2004` converges the named example instance. `kitchen test` runs supported project instances in serial, while `kitchen destroy` destroys all instances. ## Sources - [Issues](https://github.com/test-kitchen/test-kitchen/issues) - [README](https://github.com/test-kitchen/test-kitchen/blob/main/README.md) - [Releases](https://github.com/test-kitchen/test-kitchen/releases) - [test-kitchen/test-kitchen on GitHub](https://github.com/test-kitchen/test-kitchen) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/test-kitchen-test-kitchen