About Commands

Test Kitchen is driven entirely from the kitchen command line tool. Every subcommand follows the same shape:

kitchen SUBCOMMAND [INSTANCE|REGEXP|all] [FLAGS]

Run kitchen help for the full list, or kitchen help SUBCOMMAND for the flags a single subcommand accepts.

Choosing which instances to act on

An instance is one suite paired with one platform. If your kitchen.yml defines two suites and three platforms, you have six instances. Every subcommand that operates on instances accepts the same target argument:

The argument is a regular expression, not a glob. kitchen converge ubuntu converges every instance with ubuntu anywhere in its name, and kitchen converge '.*' is the same as kitchen converge all.

The instance lifecycle

Instances move through a fixed sequence of states. Each state has a subcommand, and running any subcommand also runs every earlier action the instance has not completed yet.

destroy → create → converge → setup → verify → destroy

Because the actions are cumulative, kitchen verify on a fresh checkout will create the instance, converge it, and set it up before running a single test. You rarely need to call create or setup yourself.

kitchen test runs the whole cycle from a clean slate and is the command you want in CI.

Flags shared by most subcommands

Every instance-oriented subcommand accepts these logging flags:

The five lifecycle subcommands and kitchen test additionally accept:

The five lifecycle subcommands — but not kitchen test — also accept --fail-fast (-f), which stops as soon as any instance fails instead of letting the rest finish. kitchen converge and kitchen verify accept --debug (-D) to run the provisioner or verifier in debug mode.

--concurrency with no argument means unlimited, which on a large matrix will happily start dozens of cloud instances at once. Pass a number you actually want: kitchen test -c 4.

Command reference

Lifecycle

• kitchen create — start instances
• kitchen converge — apply your configuration
• kitchen setup — prepare instances for testing
• kitchen verify — run tests
• kitchen destroy — tear instances down
• kitchen test — run the full cycle

Inspecting and debugging

• kitchen list — show instances and their state
• kitchen doctor — check for common problems
• kitchen diagnose — dump the fully computed configuration
• kitchen logs — read structured logs
• kitchen login — open a shell on an instance
• kitchen exec — run one command on instances

Project and environment

• kitchen init — add Test Kitchen to a project
• kitchen package — turn an instance into an artifact
• kitchen console — interactive Ruby console
• kitchen version — print the version

Configuration file locations

kitchen reads up to three YAML files and merges them, in increasing order of precedence:

Use KITCHEN_YAML to keep several configurations side by side:

KITCHEN_YAML=kitchen.dokken.yml kitchen test