Kitchen¶
Use Test Kitchen to automatically test cookbook data across any combination of platforms and test suites:
- Defined in a kitchen.yml file. See the configuration documentation for options and syntax information.
- Uses a driver plugin architecture
- Supports cookbook testing across many cloud providers and virtualization technologies
- Supports all common testing frameworks that are used by the Ruby community
- Uses a comprehensive set of base images provided by Bento
The key concepts in Kitchen are:
- A platform is the operating system or target environment on which a cookbook is to be tested
- A suite is the chef-client configuration, a 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 the chef-client, uploading cookbooks, starting the chef-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-client code will be run, either using chef-zero or chef-solo via the
chef_zero
andchef_solo
provisioners, respectively
Bento¶
Bento is a project that contains a set of base images that are used by Chef for internal testing and to provide a comprehensive set of base images for use with Kitchen. By default, Kitchen uses the base images provided by Bento. (Custom images may also be built using Packer.)
Test Frameworks¶
An integration test is an executable test that fails when the assumptions defined by the test are proven to be false. Each test is written in Ruby and must be located in the /tests
directory within the cookbook to be tested.
The following frameworks are good options for building integration tests with Kitchen:
Test Framework | Description |
---|---|
Bats | bats (or Bash Automated Testing System) is an testing framework for Bash. Bats is also the default framework for Kitchen. |
Minitest | A small, fast, testing framework. |
Rspec | The primary testing framework for Ruby, using the words describe and it to express tests as conversation. bats, Minitest, Serverspec are all based on RSpec. |
Serverspec | RSpec-based tests for servers. |
The syntax used for the tests depends on the testing framework. RSpec-based testing is similar to the following:
it 'what_the_test_does' do
# Ruby code that defines the test
end
For example:
it 'contains the default configuration settings' do
file(File.join(node['chef_client']['conf_dir'], 'client.rb')).must_match('^chef_server_url')
file(File.join(node['chef_client']['conf_dir'], 'client.rb')).must_match('^validation_client_name')
end
or:
it 'converts ssl_verify_mode to a symbol' do
file(File.join(node['chef_client']['conf_dir'], 'client.rb')).must_match('^ssl_verify_mode :verify_peer')
end
or:
it 'disables ohai plugins' do
regexp = 'Ohai::Config\[:disabled_plugins\] =\s+\["passwd"\]'
file(File.join(node['chef_client']['conf_dir'], 'client.rb')).must_match(/#{regexp}/)
end
Handlers can also be run as part of cookbook testing. At the top of the test file, use:
require File.expand_path('../support/helpers', __FILE__)
to specify the handler, and then include the handler within the test:
it 'enables exception_handlers' do
file(File.join(node['chef_client']['conf_dir'], 'client.rb')).must_match(
'^exception_handlers << Report::UpdateResource.new'
)
end
Busser¶
Busser is a test setup and execution framework that is designed to work on remote nodes whose system dependencies cannot be relied upon. Kitchen uses Busser to run post-convergence tests via a plugin architecture that supports different test frameworks. Busser is installed automatically as part of Kitchen.
Drivers¶
Kitchen uses a driver plugin architecture to enable Kitchen to simulate testing on cloud providers, such as Amazon EC2, OpenStack, and Rackspace, and also on non-cloud platforms, such as Microsoft Windows. Each driver is responsible for managing a virtual instance of that platform so that it may be used by Kitchen during cookbook testing.
Note
The Chef development kit includes the kitchen-vagrant
driver.
Most drivers have driver-specific configuration settings that must be added to the kitchen.yml file before 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:
Driver Plugin | Description |
---|---|
kitchen-cloudstack | A driver for CloudStack. |
kitchen-digitalocean | A driver for DigitalOcean. |
kitchen-docker | A driver for Docker. |
kitchen-dsc | A driver for Windows PowerShell Desired State Configuration (DSC). |
kitchen-ec2 | A driver for Amazon EC2. |
kitchen-fog | A driver for Fog, a Ruby gem for interacting with various cloud providers. |
kitchen-google | A driver for Google Compute Engine. |
kitchen-hyperv | A driver for Hyper-V Server. |
kitchen-joyent | A driver for Joyent. |
kitchen-linode | A driver for Linode. |
kitchen-opennebula | A driver for OpenNebula. |
kitchen-openstack | A driver for OpenStack. |
kitchen-pester | A driver for Pester, a testing framework for Microsoft Windows. |
kitchen-rackspace | A driver for Rackspace. |
kitchen-terraform | A driver for Terraform. |
kitchen-vagrant | A driver for Vagrant. The default driver packaged with the Chef development kit. |
kitchen (executable)¶
kitchen is the command-line tool for Kitchen, an integration testing tool used by the chef-client. 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.
Note
Any Kitchen subcommand that does not specify an instance will be applied to all instances.
Note
For more information about the kitchen
command line tool, see kitchen.
kitchen.yml¶
Use a kitchen.yml file to define what is required to run Kitchen, including drivers, provisioners, platforms, and test suites.
Note
For more information about the kitchen.yml file, see 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 adriver
to override the default driver for that platform or suite; a driver specified for a suite will override a driver set for a platformprovisioner_name
specifies how the chef-client will be simulated during testing.chef_zero
andchef_solo
are the most common provisioners used for testing cookbooksverifier_name
specifies which application to use when running tests, such asinspec
transport_name
specifies which transport to use when executing commands remotely on the test instance.winrm
is the default transport on Windows. Thessh
transport is the default on all other operating systems.platform-version
is the name of a platform on which Kitchen will perform cookbook testing, for example,ubuntu-16.04
orcentos-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 requiredplatforms
may define Chef server attributes that are common to the collection of test suitessuites
is a collection of test suites, with eachsuite_name
grouping defining an aspect of a cookbook to be tested. Eachsuite_name
must specify a run-list, for example:run_list: - recipe[cookbook_name::default] - recipe[cookbook_name::recipe_name]
Each
suite_name
grouping may specifyattributes
as a Hash:{ foo: "bar" }
A
suite_name
grouping may useexcludes
andincludes
to exclude/include one (or more) platforms. For example:excludes: - platform-version - platform-version # for additional platforms
For example, a very simple kitchen.yml file:
driver:
name: vagrant
provisioner:
name: chef_zero
platforms:
- name: ubuntu-16.04
- name: centos-7
- name: debian-9
suites:
- name: default
run_list:
- recipe[apache::httpd]
excludes:
- debian-9
This file uses Vagrant as the driver, which requires no additional configuration because it’s the default driver used by Kitchen, chef-zero as the provisioner, and a single (default) test suite that runs on Ubuntu 16.04, and CentOS 7.
Work with Proxies¶
The environment variables http_proxy
, https_proxy
, and ftp_proxy
are honored by 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, the chef-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'
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.
For more information …¶
For more information about test-driven development and Kitchen: