Chef InSpec Universal Matchers Reference

Chef InSpec uses matchers, a testing framework based on RSpec, to help compare resource values to expectations. The following matchers are available:

• be - makes numeric comparisons.
• be_in - looks for the property value in a list.
• cmp - checks the equality (general-use).
• eq - checks the type-specific equality.
• include - looks for an expected value in a list-valued property.
• match - looks for patterns in text using regular expressions.

You can use any matcher provided by RSpec::Expectations; however, these matchers are not supported by InSpec.

See Test Expectations with Chef InSpec on Learn Chef to learn more about Chef InSpec’s built-in matchers.

be

Use the be matcher with comparison operators, and use numbers and not strings for these comparisons. For example:

describe file('/proc/cpuinfo') do
  its('size') { should be >= 10 }
  its('size') { should be < 1000 }
end

be_in

be_in verifies if an item is included in a list. For example:

describe resource do
  its('item') { should be_in LIST }
end

cmp

Unlike eq, cmp makes less restrictive comparisons. It tries to fit the actual value to the type you are comparing. This matcher is meant to relieve the user from having to write type casts and resolutions.

Examples:

describe sshd_config do
  its('Protocol') { should cmp 2 }
end

describe passwd.uid(0) do
  its('users') { should cmp 'root' }
end

The cmp matcher compares values in the following ways:

• cmp can compare strings to numbers:

  describe sshd_config do
    # Only '2' works
    its('Protocol') { should eq '2' }
  
    # Both of these work
    its('Protocol') { should cmp '2' }
    its('Protocol') { should cmp 2 }
  end
  

• cmp comparisons are not case sensitive:

  describe auditd_conf do
    its('log_format') { should cmp 'raw' }
    its('log_format') { should cmp 'RAW' }
  end
  

• cmp recognizes versions embedded in strings:

  describe package('curl') do
    its('version') { should cmp > '7.35.0-1ubuntu2.10' }
  end
  

• cmp can compare a single-value array with a string to a value:

  describe passwd.uids(0) do
    its('users') { should cmp 'root' }
    its('users') { should cmp ['root'] }
  end
  

• cmp can compare a single-value array with a string to a regular expression:

  describe auditd_conf do
    its('log_format') { should cmp /raw/i }
  end
  

• cmp allows octal comparisons:

  describe file('/proc/cpuinfo') do
    its('mode') { should cmp '0345' }
  end
  
  expected: 0345
  got: 0444
  

eq

eq tests for exact equality of two values. For example:

describe sshd_config do
  its('RSAAuthentication') { should_not eq 'no' }
  its('Protocol') { should eq '2' }
end

eq fails if types do not match. When comparing configuration entries that take numerical values, do not use quotes as it becomes a string.

its('Port') { should eq '22' }
# passes

its('Port') { should eq 22 }
# fails: '2' != 2 (string vs integer)

Use cmp for less restrictive comparisons.

include

include verifies if a value is included in a list. For example:

describe passwd do
  its('users') { should include 'my_user' }
end

match

match checks if a string matches a regular expression. For example:

describe sshd_config do
  its('Ciphers') { should_not match /cbc/ }
end