Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 37 ยท Testing with Test Kitchen

Test Kitchen: Testing Cookbooks on Real Machines

Learn Test Kitchen for Chef: kitchen.yml drivers, platforms and suites, the create, converge, verify and destroy lifecycle, and model the lifecycle in Ruby.

Unit tests tell you your Ruby logic is right. They cannot tell you whether apt really installs the package on Ubuntu 24.04, whether the service starts, or whether the config file is accepted by the program. For that you need a real machine. Test Kitchen creates a temporary virtual machine or container, runs your cookbook on it with a real Chef client, runs checks against the result, and throws the machine away.

This lesson explains kitchen.yml, the four main commands, how the instance state machine works, and a typical development loop. The runnable example models the lifecycle in Ruby, because real instances (Docker, Vagrant, cloud VMs) cannot be started from this page.

Test Kitchen and Chef are not available on this site. kitchen.yml files and shell commands below are real and read-only. The Ruby stand-in models the instance lifecycle and is labelled as such.

kitchen.yml

The file has four parts: a driver (what creates machines), a provisioner (what applies the cookbook), a verifier (what checks the result), and lists of platforms and suites.

YAML
---
driver:
  name: dokken          # containers; vagrant, ec2, azurerm and others also exist
  chef_version: latest

provisioner:
  name: dokken

transport:
  name: dokken

verifier:
  name: inspec

platforms:
  - name: ubuntu-24.04
    driver:
      image: dokken/ubuntu-24.04
  - name: almalinux-9
    driver:
      image: dokken/almalinux-9

suites:
  - name: default
    run_list:
      - recipe[myapp::default]
    verifier:
      inspec_tests:
        - test/integration/default
    attributes:
      myapp:
        port: 8080
  - name: tls
    run_list:
      - recipe[myapp::tls]

Test Kitchen builds the matrix: every suite on every platform. Two platforms and two suites give four instances, named like default-ubuntu-2404 and tls-almalinux-9. For Policyfile cookbooks you set provisioner: name: policyfile_zero and a named_run_list instead of run_list.

The lifecycle

stateDiagram-v2
  [*] --> Dormant
  Dormant --> Created: kitchen create
  Created --> Converged: kitchen converge
  Converged --> Verified: kitchen verify
  Verified --> Dormant: kitchen destroy
  Converged --> Converged: kitchen converge (again)
  Created --> Dormant: kitchen destroy

Each command moves an instance to the next state; kitchen test runs all of them in one go.

Command What happens
kitchen list Show instances and their state
kitchen create [name] Start the machine
kitchen converge [name] Install Chef, upload the cookbook and run the run list
kitchen verify [name] Run the tests (InSpec) on the converged machine
kitchen destroy [name] Remove the machine
kitchen test [name] create, converge, verify, then destroy (destroy also on success)
kitchen login [name] Open a shell inside the instance to look around

converge is the one you repeat most: edit a recipe, run kitchen converge, and Chef applies only the difference. A second converge with no changes is also a free idempotence check: the run should report zero updated resources.

Stand-in: model the lifecycle

Ruby Stand-in: instances, states and the test matrix

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The output shows the matrix of four instance names, a first converge that updates four resources, a second converge that updates none, a failing verify (the invented config valid check is false), and the error you get when you try to converge an instance that was never created. Test Kitchen reports similar errors.

A good development loop

  1. kitchen create once, at the start of the day.
  2. Edit a recipe, run kitchen converge, read the output.
  3. When the converge is stable, add or adjust an InSpec test and run kitchen verify.
  4. Run kitchen converge again to check that nothing changes (idempotence).
  5. Before pushing, run kitchen test on every platform, or let CI do it.
  6. kitchen destroy to free memory and disk space.

Debug tips: kitchen converge -l debug shows detailed Chef logs; kitchen login drops you into the machine where you can run chef-client by hand or inspect /var/chef/cache.

Choosing a driver

  • dokken: Docker containers, fast (seconds), great for most cookbooks. It cannot test things that need a full init system or kernel features (some reboots, systemd corner cases).
  • vagrant: full VMs with VirtualBox or Hyper-V; slower, but closest to a real server.
  • cloud drivers (ec2, azurerm, gce): real cloud instances; slow and cost money, good for final checks of cloud-specific recipes.

Use a container driver on every commit and a VM or cloud run before releases.

Speed and cost

A full matrix is slow if every combination runs serially. In CI, run each instance as a separate job (kitchen test default-ubuntu-2404). Cache the Chef installer, pull base images ahead of time, and keep your suites focused: one suite per behavior, not one giant suite.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does kitchen converge do?

    Converge installs the chef client, copies the cookbook, and runs the configured run list on the instance.
  2. 2. Two platforms and three suites give how many instances?

    Test Kitchen builds the cross product of suites and platforms: 2 x 3 = 6 instances.
  3. 3. How can a second kitchen converge be used as a test?

    If the second converge still changes resources, something in the recipe is not idempotent.
  4. 4. What does kitchen test do?

    kitchen test runs the whole lifecycle and cleans up, which is what CI usually executes.

Summary

  • Test Kitchen creates a throwaway machine, converges your cookbook on it, runs tests, and destroys it.
  • kitchen.yml defines the driver, provisioner, verifier, platforms and suites; instances are suites times platforms.
  • Main commands: create, converge, verify, destroy, test, login, list.
  • A second converge checks idempotence; dokken is fast, Vagrant and cloud drivers are more realistic.

Next: ChefSpec: Fast Unit Tests for Recipes