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.
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