Project: Chef InSpec (Provisioning / Security & Compliance)
File: matchers.md

+++ title = "Chef InSpec Universal Matchers Reference" draft = false gh_repo = "inspec" [menu] [menu.inspec] title = "Matchers" identifier = "inspec/reference/matchers.md Matchers" parent = "inspec/reference" weight = 40 +++ Chef InSpec uses matchers, a testing framework based on , to help compare resource values to expectations. The following matchers are available: - makes numeric comparisons. - looks for the property value in a list. - checks the equality (general-use). - checks the type-specific equality. - looks for an expected value in a list-valued property. - looks for patterns in text using regular expressions. You can use any matcher provided by ; however, these matchers are not . Use the `be` matcher with comparison operators, and use numbers and not strings for these comparisons. For example: ```ruby describe file('/proc/cpuinfo') do its('size') { should be >= 10 } its('size') { should be < 1000 } end ``` `be_in` verifies if an item is included in a list. For example: ```ruby describe resource do its('item') { should be_in LIST } end ``` Unlike , `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: ```ruby 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: ```ruby describe sshd_config do its('Protocol') { should eq '2' } its('Protocol') { should cmp '2' } its('Protocol') { should cmp 2 } end ``` `cmp` comparisons are not case sensitive: ```ruby describe auditd_conf do its('log_format') { should cmp 'raw' } its('log_format') { should cmp 'RAW' } end ``` `cmp` recognizes versions embedded in strings: ```ruby 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: ```ruby 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: ```ruby describe auditd_conf do its('log_format') { should cmp /raw/i } end ``` `cmp` allows octal comparisons: ```ruby describe file('/proc/cpuinfo') do its('mode') { should cmp '0345' } end expected: 0345 got: 0444 ``` `eq` tests for exact equality of two values. For example: ```ruby 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. ```ruby its('Port') { should eq '22' } its('Port') { should eq 22 } ``` Use for less restrictive comparisons. `include` verifies if a value is included in a list. For example: ```ruby describe passwd do its('users') { should include 'my_user' } end ``` `match` checks if a string matches a regular expression. For example: ```ruby describe sshd_config do its('Ciphers') { should_not match /cbc/ } end ```