Test Kitchen

Use Test Kitchen to automatically test cookbooks across any combination of platforms and test suites:

• Test suites are defined in a kitchen.yml file. See the configuration documentation for options and syntax information.
• Supports cookbook testing across many cloud providers and virtualization technologies.
• Uses a comprehensive set of operating system base images from Chef’s Bento project.

The key concepts in Test Kitchen are:

• A platform is the operating system or target environment on which a cookbook is to be tested
• A suite is the Chef Infra Client configuration, a Policyfile or run-list, and (optionally) node attributes
• An instance is the combination of a specific platform and a specific suite, with each instance being assigned an auto-generated name
• A driver is the lifecycle that implements the actions associated with a specific instance—create the instance, do what is needed to converge on that instance (such as installing Chef Infra Client, uploading cookbooks, starting a Chef Infra Client run, and so on), setup anything else needed for testing, verify one (or more) suites post-converge, and then destroy that instance
• A provisioner is the component on which the Chef Infra Client code will be run, either using chef-zero or chef-solo via the chef_zero and chef_solo provisioners, respectively

Bento

Drivers

Test Kitchen uses a driver plugin architecture to enable Test Kitchen to test instances on cloud providers such as Amazon EC2, Google Compute Engine, and Microsoft Azure. You can also test on multiple local hypervisors, such as VMware, Hyper-V, or VirtualBox.

Most drivers have driver-specific configuration settings that must be added to the kitchen.yml file before Test Kitchen will be able to use that platform during cookbook testing. For information about these driver-specific settings, please refer to the driver-specific documentation.

Some popular drivers:

Validation with Chef InSpec

Test Kitchen will create a VM or cloud instance, install Chef Infra Client to that system, and converge Chef Infra Client with your local cookbook. Once this is complete, you will want to perform automated validation against the infrastructure you have built to validate its configuration. Test Kitchen allows you to run Chef InSpec tests against your converged cookbook for easy local validation of your infrastructure.

kitchen (executable)

kitchen is the command-line tool for Test Kitchen, an integration testing tool maintained by Chef Software. Test Kitchen runs tests against any combination of platforms using any combination of test suites. Each test, however, is done against a specific instance, which is comprised of a single platform and a single set of testing criteria. This allows each test to be run in isolation, ensuring that different behaviors within the same codebase can be tested thoroughly before those changes are committed to production.

kitchen.yml

Syntax

The basic structure of a kitchen.yml file is as follows:

driver:
  name: driver_name

provisioner:
  name: provisioner_name

verifier:
  name: verifier_name

transport:
  name: transport_name

platforms:
  - name: platform-version
    driver:
      name: driver_name
  - name: platform-version

suites:
  - name: suite_name
    run_list:
      - recipe[cookbook_name::recipe_name]
    attributes: { foo: "bar" }
    excludes:
      - platform-version
  - name: suite_name
    driver:
      name: driver_name
    run_list:
      - recipe[cookbook_name::recipe_name]
    attributes: { foo: "bar" }
    includes:
      - platform-version

where:

• driver_name is the name of a driver that will be used to create platform instances used during cookbook testing. This is the default driver used for all platforms and suites unless a platform or suite specifies a driver to override the default driver for that platform or suite; a driver specified for a suite will override a driver set for a platform

• provisioner_name specifies how Chef Infra Client will be simulated during testing. chef_zero and chef_solo are the most common provisioners used for testing cookbooks

• verifier_name specifies which application to use when running tests, such as inspec

• transport_name specifies which transport to use when executing commands remotely on the test instance. winrm is the default transport on Windows. The ssh transport is the default on all other operating systems.

• platform-version is the name of a platform on which Test Kitchen will perform cookbook testing, for example, ubuntu-20.04 or centos-7; depending on the platform, additional driver details—for example, instance names and URLs used with cloud platforms like OpenStack or Amazon EC2—may be required

• platforms may define Chef Infra Server attributes that are common to the collection of test suites

• suites is a collection of test suites, with each suite_name grouping defining an aspect of a cookbook to be tested. Each suite_name must specify a run-list, for example:

  run_list:
    - recipe[cookbook_name::default]
    - recipe[cookbook_name::recipe_name]
  

• Each suite_name grouping may specify attributes as a Hash: { foo: "bar" }

• A suite_name grouping may use excludes and includes to exclude/include one (or more) platforms. For example:

  excludes:
     - platform-version
     - platform-version       # for additional platforms
  

For example, a simple kitchen.yml file:

driver:
  name: vagrant

provisioner:
  name: chef_zero

platforms:
  - name: ubuntu-20.04
  - name: centos-8
  - name: debian-10

suites:
  - name: default
    run_list:
      - recipe[apache::httpd]
    excludes:
      - debian-10

This file uses HashiCorp Vagrant as the driver, which requires no additional configuration because it is the default driver used by Test Kitchen, chef-zero as the provisioner, and a single (default) test suite that runs on Ubuntu 20.04, and CentOS 7.

Work with proxies

The environment variables http_proxy, https_proxy, and ftp_proxy are honored by Test Kitchen for proxies. The client.rb file is read to look for proxy configuration settings. If http_proxy, https_proxy, and ftp_proxy are specified in the client.rb file, Chef Infra Client will configure the ENV variable based on these (and related) settings. For example:

http_proxy 'http://proxy.example.org:8080'
http_proxy_user 'myself'
http_proxy_pass 'Password1'

will be set to:

ENV['http_proxy'] = 'http://myself:Password1@proxy.example.org:8080'

Test Kitchen also supports http_proxy and https_proxy in the kitchen.yml file. You can set them manually or have them read from your local environment variables:

driver:
  name: vagrant

provisioner:
  name: chef_zero
  # Set proxy settings manually, or
  http_proxy: 'http://user:password@server:port'
  https_proxy: 'http://user:password@server:port'

  # Read from local environment variables
  http_proxy: <%= ENV['http_proxy'] %>
  https_proxy: <%= ENV['https_proxy'] %>

This will not set the proxy environment variables for applications other than Chef. The Vagrant plugin, vagrant-proxyconf, can be used to set the proxy environment variables for applications inside the VM.

Additional information

For more information about test-driven development and Test Kitchen, see the kitchen.ci website:

• kitchen.ci
• Getting Started with Test Kitchen