It's helpful to have a common set of requirements for all the concerned cookbook tests. The default is to have it named spec_helper.rb at the root of the spec/unit directory. We suggest to include at least three requirements:

Here's our sample spec_helper.rb file:

require 'chefspec'
require 'chefspec/berkshelf'
ChefSpec::Coverage.start!

We'll now unit test the default apache cookbook recipe. Our first step is to require the helper created earlier in the default_spec.rb file. It will be required in all of our future tests:

require 'spec_helper'

All unit tests start with a descriptive block, as given here:

describe 'cookbook::recipe_name' do 
  [...]
end

Inside this block, we want to simulate the Chef run in a simulated CentOS 7.2 environment, with the default attributes. This is the context, and we expect this Chef run to not raise any errors:

describe 'apache::default' do
  context 'Default attributes on CentOS 7.2' do
    let(:chef_run) do
      runner = ChefSpec::ServerRunner.new(platform: 'centos', version: '7.2.1511')
      runner.converge(described_recipe)
    end

    it 'converges successfully' do
      expect { chef_run }.to_not raise_error
    end
  end
end

To find the exact past or future CentOS version we might need, we can go to the CentOS mirror site, http://mirror.centos.org/centos/, or read a full list of available simulated platforms at https://github.com/customink/fauxhai/tree/master/lib/fauxhai/platforms.

Execute our first unit test using chef exec rspec (it's using the bundled rspec from the Chef DK):

$ chef exec rspec --color
.....

Finished in 0.82521 seconds (files took 1.87 seconds to load)
5 examples, 0 failures


ChefSpec Coverage report generated...

  Total Resources:   2
  Touched Resources: 0
  Touch Coverage:    0.0%

Untouched Resources:

  yum_package[httpd]                 apache/recipes/default.rb:7
  service[httpd]                     apache/recipes/default.rb:11

We see the simulated Chef run execution times, as well as a coverage report (0%, as we didn't test anything for now). ChefSpec even shows us what's not unit tested yet!

A nice option is the documentation RSpec formatter, so we have descriptions of what's being tested. At the end of this section, we'll have something like this, using this formatter:

$ chef exec rspec --format documentation --color

apache::default
  Default attributes on CentOS 7.2
    converges successfully
    installs httpd
    enables and starts httpd service

apache::virtualhost
  Default attributes on CentOS 7.2
    converges successfully
    creates a virtualhost directory
    creates and index.html file
    creates a virtualhost configuration file

Finished in 1.14 seconds (files took 2.56 seconds to load)
7 examples, 0 failures


ChefSpec Coverage report generated...

  Total Resources:   5
  Touched Resources: 5
  Touch Coverage:    100.0%

You are awesome and so is your test coverage! Have a fantastic day!

Our default recipe starts by installing the httpd package. Here's how to test it using ChefSpec, inside the context we created earlier:

    it 'installs httpd' do
      expect(chef_run).to install_package('httpd')
    end

Execute rspec again and see the touch coverage attain 50% as one of the two resources from the default recipe is now tested.

The default recipe enables and starts the httpd service. Here's how to test if both actions are handled by the code using ChefSpec, inside the context created earlier:

    it 'enables and starts httpd service' do
      expect(chef_run).to enable_service('httpd')
      expect(chef_run).to start_service('httpd')
    end

Our test coverage is now 100% for the default recipe as we tested both declared resources.

As we have two recipes in the apache cookbook, let's create tests for our second recipe—virtualhost_spec.rb. Start it exactly like the first one, with a description, context, and an initial test for a valid Chef run:

require 'spec_helper'

describe 'apache::virtualhost' do
  context 'Default attributes on CentOS 7.2' do
    let(:chef_run) do
      runner = ChefSpec::ServerRunner.new(platform: 'centos', version: '7.2.1511')
      runner.converge(described_recipe)
    end

    it 'converges successfully' do
      expect { chef_run }.to_not raise_error
    end
  end
end

Execute RSpec and see the coverage fall from 100% to 40%. Three new resources are now untested, from the apache::virtualhost recipe:

$ chef exec rspec --color
[...]
ChefSpec Coverage report generated...

  Total Resources:   5
  Touched Resources: 2
  Touch Coverage:    40.0%

Untouched Resources:

  directory[/var/www/default]        apache/recipes/virtualhost.rb:8
  file[/var/www/default/index.html]   apache/recipes/virtualhost.rb:15
  template[/etc/httpd/conf.d/default.conf]   apache/recipes/virtualhost.rb:22

The good news is that ChefSpec still tells us which resources are not tested!

This particular apache::virtualhost recipe starts by creating a directory. Here's how we can test for this directory existence, along with its ownership parameters:

    it 'creates a virtualhost directory' do
      expect(chef_run).to create_directory('/var/www/default').with(
        user: 'root',
        group: 'root'
      )
    end

Code coverage is now 60%!

The same recipe then creates an index file. This is how we test it's created with the required ownership:

    it 'creates and index.html file' do
      expect(chef_run).to create_file('/var/www/default/index.html').with(
        user: 'root',
        group: 'root'
      )
    end

Code coverage is now 80%!

The recipe ends with the creation of Apache VirtualHost from a template. This is how to test it's in place with the default attributes:

    it 'creates a virtualhost configuration file' do
      expect(chef_run).to create_template('/etc/httpd/conf.d/default.conf').with(
        user: 'root',
        group: 'root'
      )
    end

All in all, we've now covered 100% of our resources!

As the output says:

You are awesome and so is your test coverage! Have a fantastic day!

The mysite cookbook we created earlier contains a search in a data bag to later populate a file with content. The thing is, we're unit testing, and no real Chef server is answering requests. So the tests are failing: the simulated Chef run doesn't end well because a search can't be executed. Fortunately, ChefSpec allows us to stub the data bag with real content. So here's how it looks in spec/unit/recipes/default_spec.rb from the mysite cookbook:

describe 'mysite::default' do
  context 'Default attributes on CentOS 7.2' do
    let(:chef_run) do
      runner = ChefSpec::ServerRunner.new(platform: 'centos', version: '7.2.1511')
      runner.create_data_bag('webusers', {
        'john' => {
          'id' => 'john',
          'htpasswd' => '$apr1$AUI2Y5pj$0v0PaSlLfc6QxZx1Vx5Se.'
        }
      })
      runner.converge(described_recipe)
    end

    it 'converges successfully' do
      expect { chef_run }.to_not raise_error
    end
  end
end

Now the simulated Chef run has a webusers data bag and some sample data to work with!

It's very common to include recipes inside another recipe. Typically, when using notifications for restarting a service from a file change, the concerned service must be included in the recipe where the file resource is located; otherwise, the code most probably works by chance because the required dependent cookbook is included elsewhere! Here's how to test for a cookbook inclusion:

    it 'includes the `apache` recipes' do
      expect(chef_run).to include_recipe('apache::default')
      expect(chef_run).to include_recipe('apache::virtualhost')
    end

We now ensure that dependencies are always included.

Sometimes we have to work with third-party cookbooks, that may somehow raise errors. It's the case with the official MySQL cookbook, which depends on the SELinux cookbook for the RHEL/CentOS platform. This cookbook, for some reason, doesn't work with ChefSpec, so when converged, it errors out the following string: chefspec not supported!. ChefSpec stops there, and say the Chef run is in error. As we don't have any power on why is that, here's a workaround to expect a very specific error from a Chef run, and this will be helpful many times later:

    it 'converges successfully' do
      # The selinux cookbook raises this error.
      expect { chef_run }.to raise_error(RuntimeError, 'chefspec not supported!')
    end

We've seen a selection of the most common and reusable unit tests for Chef cookbooks!