Cookbooks and Testing

My Testing Journey

I learned the importance of cookbook testing the hard way. Early in my Chef journey, I uploaded a cookbook to production that worked perfectly on my test VM but failed spectacularly on production CentOS servers because I'd only tested on Ubuntu. The incident caused a 2-hour outage and taught me an invaluable lesson: test everything, test thoroughly, and test across platforms.

Since then, I've built a comprehensive testing workflow that catches issues before they reach production. This article shares the testing practices that have kept my infrastructure stable through hundreds of cookbook deployments.

The Testing Pyramid for Chef

         ┌─────────────┐
         │  Manual     │  ← Rare, final validation
         │  Testing    │
         ├─────────────┤
         │ Integration │  ← Test Kitchen
         │   Tests     │
         ├─────────────┤
         │    Unit     │  ← ChefSpec
         │   Tests     │
         ├─────────────┤
         │   Syntax    │  ← Cookstyle, Foodcritic
         │   Checks    │
         └─────────────┘

Each layer catches different types of issues.

Syntax Checking with Cookstyle

Cookstyle enforces Chef coding standards and catches common mistakes.

Running Cookstyle

# Check entire cookbook
cd ~/chef-repo/cookbooks/webserver
cookstyle .

# Auto-fix safe issues
cookstyle -a .

# Check specific file
cookstyle recipes/default.rb

Example output:

Inspecting 5 files
...C.

Offenses:

recipes/default.rb:10:3: C: Style/StringLiterals: Prefer single-quoted strings
  description "Install nginx"
  ^^^^^^^^^^^

1 file inspected, 1 offense detected

My .rubocop.yml Configuration

I customize Cookstyle rules for my team:

# .rubocop.yml
AllCops:
  TargetChefVersion: 15.0
  Exclude:
    - 'vendor/**/*'
    - 'spec/**/*'

Style/StringLiterals:
  EnforcedStyle: single_quotes

Metrics/LineLength:
  Max: 120

ChefCorrectness/IncorrectLibraryInjection:
  Enabled: true

ChefDeprecations/DeprecatedChefSpecPlatform:
  Enabled: true

Unit Testing with ChefSpec

ChefSpec tests cookbook logic without actually converging nodes.

Setting Up ChefSpec

# ChefSpec is included with Chef Workstation
cd ~/chef-repo/cookbooks/webserver

# Create spec directory
mkdir -p spec/unit/recipes

Writing Your First ChefSpec Test

spec/unit/recipes/default_spec.rb:

require 'spec_helper'

describe 'webserver::default' do
  let(:chef_run) do
    ChefSpec::ServerRunner.new(platform: 'ubuntu', version: '20.04') do |node|
      node.normal['webserver']['port'] = 8080
    end.converge(described_recipe)
  end

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

  it 'creates nginx configuration' do
    expect(chef_run).to create_template('/etc/nginx/nginx.conf').with(
      owner: 'root',
      group: 'root',
      mode: '0644'
    )
  end

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

  it 'notifies nginx to reload when config changes' do
    template = chef_run.template('/etc/nginx/nginx.conf')
    expect(template).to notify('service[nginx]').to(:reload).delayed
  end
end

spec/spec_helper.rb:

require 'chefspec'
require 'chefspec/berkshelf'

RSpec.configure do |config|
  config.platform = 'ubuntu'
  config.version = '20.04'
  config.log_level = :error
end

Running ChefSpec Tests

# Run all specs
chef exec rspec

# Run specific spec
chef exec rspec spec/unit/recipes/default_spec.rb

# Run with coverage report
chef exec rspec --format documentation

Example output:

webserver::default
  installs nginx package
  creates nginx configuration
  enables and starts nginx service
  notifies nginx to reload when config changes

Finished in 0.5 seconds
4 examples, 0 failures

Testing Different Platforms

describe 'webserver::default' do
  platforms = {
    'ubuntu' => ['18.04', '20.04'],
    'centos' => ['7', '8']
  }

  platforms.each do |platform, versions|
    versions.each do |version|
      context "on #{platform} #{version}" do
        let(:chef_run) do
          ChefSpec::ServerRunner.new(
            platform: platform,
            version: version
          ).converge(described_recipe)
        end

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

Why this matters: Catches platform-specific issues early.

Testing Conditional Logic

recipes/configure.rb:

if node['webserver']['ssl_enabled']
  package 'ssl-cert' do
    action :install
  end

  template '/etc/nginx/ssl.conf' do
    source 'ssl.conf.erb'
  end
end

spec/unit/recipes/configure_spec.rb:

describe 'webserver::configure' do
  context 'when SSL is enabled' do
    let(:chef_run) do
      ChefSpec::ServerRunner.new do |node|
        node.normal['webserver']['ssl_enabled'] = true
      end.converge(described_recipe)
    end

    it 'installs ssl-cert package' do
      expect(chef_run).to install_package('ssl-cert')
    end

    it 'creates SSL configuration' do
      expect(chef_run).to create_template('/etc/nginx/ssl.conf')
    end
  end

  context 'when SSL is disabled' do
    let(:chef_run) do
      ChefSpec::ServerRunner.new do |node|
        node.normal['webserver']['ssl_enabled'] = false
      end.converge(described_recipe)
    end

    it 'does not install ssl-cert package' do
      expect(chef_run).not_to install_package('ssl-cert')
    end

    it 'does not create SSL configuration' do
      expect(chef_run).not_to create_template('/etc/nginx/ssl.conf')
    end
  end
end

Integration Testing with Test Kitchen

Test Kitchen provisions real VMs or containers and converges your cookbook.

Kitchen Configuration

.kitchen.yml:

---
driver:
  name: vagrant

provisioner:
  name: chef_zero
  product_name: chef
  enforce_idempotency: true
  multiple_converge: 2
  deprecations_as_errors: true

verifier:
  name: inspec

platforms:
  - name: ubuntu-20.04
  - name: ubuntu-22.04
  - name: centos-7
  - name: centos-8

suites:
  - name: default
    run_list:
      - recipe[webserver::default]
    verifier:
      inspec_tests:
        - test/integration/default
    attributes:
      webserver:
        port: 80
        
  - name: ssl
    run_list:
      - recipe[webserver::default]
    verifier:
      inspec_tests:
        - test/integration/ssl
    attributes:
      webserver:
        port: 443
        ssl_enabled: true

My configuration choices:

• enforce_idempotency - Ensures cookbook is truly idempotent

• multiple_converge: 2 - Runs chef-client twice to verify

• deprecations_as_errors - Catch deprecation warnings early

Writing InSpec Integration Tests

test/integration/default/default_test.rb:

describe package('nginx') do
  it { should be_installed }
end

describe service('nginx') do
  it { should be_installed }
  it { should be_enabled }
  it { should be_running }
end

describe file('/etc/nginx/nginx.conf') do
  it { should exist }
  it { should be_file }
  it { should be_owned_by 'root' }
  its('mode') { should cmp '0644' }
end

describe port(80) do
  it { should be_listening }
  its('protocols') { should include 'tcp' }
end

describe http('http://localhost') do
  its('status') { should cmp 200 }
end

test/integration/ssl/ssl_test.rb:

describe package('ssl-cert') do
  it { should be_installed }
end

describe file('/etc/nginx/ssl.conf') do
  it { should exist }
  its('content') { should match /ssl_protocols TLSv1.2 TLSv1.3/ }
end

describe port(443) do
  it { should be_listening }
  its('protocols') { should include 'tcp' }
end

describe ssl(port: 443).protocols('tls1.2') do
  it { should be_enabled }
end

Test Kitchen Workflow

# List all test instances
kitchen list

# Create instances
kitchen create

# Converge (apply cookbook)
kitchen converge

# Verify with InSpec tests
kitchen verify

# Login to debug
kitchen login default-ubuntu-2004

# Destroy instances
kitchen destroy

# Run full test cycle
kitchen test

# Test specific platform
kitchen test default-ubuntu-2004

# Test in parallel (faster)
kitchen test -c 4

My daily workflow:

# 1. Make cookbook changes
vim recipes/default.rb

# 2. Quick syntax check
cookstyle recipes/default.rb

# 3. Unit tests
chef exec rspec

# 4. Integration test on Ubuntu
kitchen converge default-ubuntu-2004
kitchen verify default-ubuntu-2004

# 5. If looks good, test all platforms
kitchen test

Advanced Testing Patterns

Testing Data Bags

Creating test data bags:

test/fixtures/data_bags/users/alice.json:

{
  "id": "alice",
  "comment": "Alice Developer",
  "shell": "/bin/bash",
  "groups": ["developers", "sudo"]
}

.kitchen.yml:

provisioner:
  name: chef_zero
  data_bags_path: test/fixtures/data_bags

Test:

describe user('alice') do
  it { should exist }
  its('groups') { should include 'developers' }
  its('shell') { should eq '/bin/bash' }
end

Testing with Different Attributes

.kitchen.yml:

suites:
  - name: default
    attributes:
      webserver:
        port: 80
        workers: 2
        
  - name: production
    attributes:
      webserver:
        port: 80
        workers: 8
        ssl_enabled: true
        
  - name: development
    attributes:
      webserver:
        port: 8080
        workers: 1
        debug: true

Using Docker for Faster Tests

.kitchen.yml:

driver:
  name: docker
  privileged: true
  use_sudo: false

platforms:
  - name: ubuntu-20.04
    driver_config:
      image: ubuntu:20.04
      platform: ubuntu
      
  - name: centos-8
    driver_config:
      image: centos:8
      platform: rhel

Benefits:

• Much faster than VMs (seconds vs minutes)

• Lower resource usage

• Good for most testing scenarios

Limitations:

• Can't test systemd services easily

• Not suitable for kernel-level testing

My Complete Testing Workflow

1. Pre-Commit Checks

.git/hooks/pre-commit:

#!/bin/bash

echo "Running pre-commit checks..."

# Cookstyle
echo "Running Cookstyle..."
cookstyle .
if [ $? -ne 0 ]; then
  echo "Cookstyle failed. Please fix issues."
  exit 1
fi

# ChefSpec
echo "Running unit tests..."
chef exec rspec
if [ $? -ne 0 ]; then
  echo "Unit tests failed. Please fix issues."
  exit 1
fi

echo "All pre-commit checks passed!"
exit 0

2. CI/CD Pipeline

Jenkinsfile:

pipeline {
  agent any
  
  stages {
    stage('Syntax') {
      steps {
        sh 'cookstyle .'
      }
    }
    
    stage('Unit Tests') {
      steps {
        sh 'chef exec rspec'
      }
    }
    
    stage('Integration Tests') {
      parallel {
        stage('Ubuntu 20.04') {
          steps {
            sh 'kitchen test default-ubuntu-2004'
          }
        }
        stage('CentOS 8') {
          steps {
            sh 'kitchen test default-centos-8'
          }
        }
      }
    }
    
    stage('Upload to Chef Server') {
      when {
        branch 'main'
      }
      steps {
        sh 'knife cookbook upload webserver'
      }
    }
  }
  
  post {
    always {
      sh 'kitchen destroy'
    }
  }
}

3. Version Management

metadata.rb:

name 'webserver'
version '1.3.0'  # Update with each change

CHANGELOG.md:

# Changelog

## 1.3.0 (2026-01-07)
- Added SSL support
- Improved error handling
- Updated tests for TLS 1.3

## 1.2.0 (2025-12-15)
- Added support for CentOS 8
- Fixed idempotency issues
- Added ChefSpec tests

## 1.1.0 (2025-11-20)
- Initial production release

Real-World Testing Example

Here's how I test a complete application cookbook:

Cookbook: Rails application deployment

Structure:

rails_app/
├── recipes/
│   ├── default.rb
│   ├── dependencies.rb
│   ├── database.rb
│   ├── application.rb
│   └── service.rb
├── spec/
│   └── unit/
│       └── recipes/
│           ├── default_spec.rb
│           ├── dependencies_spec.rb
│           └── database_spec.rb
├── test/
│   └── integration/
│       └── default/
│           ├── dependencies_test.rb
│           ├── database_test.rb
│           ├── application_test.rb
│           └── service_test.rb
└── .kitchen.yml

test/integration/default/application_test.rb:

# Test application deployment
describe file('/opt/myapp') do
  it { should be_directory }
  it { should be_owned_by 'deploy' }
end

describe file('/opt/myapp/config/database.yml') do
  it { should exist }
  its('owner') { should eq 'deploy' }
  its('mode') { should cmp '0600' }
end

# Test database connectivity
describe command('cd /opt/myapp && bundle exec rails runner "puts ActiveRecord::Base.connection.active?"') do
  its('stdout') { should match /true/ }
  its('exit_status') { should eq 0 }
end

# Test application response
describe http('http://localhost:3000/health') do
  its('status') { should cmp 200 }
  its('body') { should match /OK/ }
end

# Test background workers
describe processes('sidekiq') do
  it { should exist }
  its('users') { should include 'deploy' }
end

Results:

• Caught database connection issues before production

• Identified missing gem dependencies on CentOS

• Verified all services start correctly

• Validated health check endpoints

Testing Best Practices

1. Test Idempotency

# .kitchen.yml
provisioner:
  multiple_converge: 2
  enforce_idempotency: true

Why: Ensures cookbook can run multiple times safely.

2. Test All Supported Platforms

platforms:
  - name: ubuntu-18.04
  - name: ubuntu-20.04
  - name: ubuntu-22.04
  - name: centos-7
  - name: centos-8

My lesson: Test the platforms you actually use in production.

3. Test Edge Cases

# Test missing attributes
context 'when port is not specified' do
  let(:chef_run) do
    ChefSpec::ServerRunner.new.converge(described_recipe)
  end

  it 'uses default port 80' do
    expect(chef_run.node['webserver']['port']).to eq(80)
  end
end

4. Use Descriptive Test Names

# Bad
it 'works' do
  expect(chef_run).to install_package('nginx')
end

# Good
it 'installs nginx package' do
  expect(chef_run).to install_package('nginx')
end

5. Keep Tests Fast

# Cache chef_run
let(:chef_run) do
  ChefSpec::ServerRunner.new.converge(described_recipe)
end

# Don't repeat expensive operations
before do
  stub_command('which nginx').and_return(true)
end

Debugging Failed Tests

ChefSpec Debugging

# Print node attributes
puts chef_run.node['webserver'].inspect

# Print resources
puts chef_run.find_resource(:package, 'nginx').inspect

# Check if resource was created
expect(chef_run).to create_template('/etc/nginx/nginx.conf')

Test Kitchen Debugging

# Verbose output
kitchen converge --log-level=debug

# Login to instance
kitchen login default-ubuntu-2004

# Inside instance
sudo chef-client -l debug
cat /tmp/kitchen/cache/chef-stacktrace.out

Common Test Failures

1. Platform Not Found

Platform ubuntu-20.04 not found

Solution: Update Vagrant box

vagrant box update

2. Resource Not Found in ChefSpec

expected ... to install_package("nginx") but it did not

Solution: Check recipe is converged

let(:chef_run) do
  ChefSpec::ServerRunner.new.converge('webserver::default')  # Specify recipe
end

3. Service Not Running in Test Kitchen

expected Service "nginx" to be running

Solution: Check logs

kitchen login
sudo journalctl -u nginx

What's Next?

You now understand: ✅ Syntax checking with Cookstyle ✅ Unit testing with ChefSpec ✅ Integration testing with Test Kitchen ✅ Multi-platform testing strategies ✅ CI/CD integration for automated testing ✅ Debugging test failures

Continue to Chef Server and Node Management to learn about scaling your Chef infrastructure, or explore Best Practices for production deployment patterns.

Testing isn't optional - it's the foundation of reliable automation. With these practices, you'll catch issues early and deploy with confidence.

---

Ready to scale your Chef infrastructure? Continue to Chef Server and Node Management