inspec/docs/matchers.md
Thomas Petchel a48aea53c5 Add additional links to Learn Chef Rally content (#2477)
* Fix under construction page
Previously, the content was hidden behind the banner. The buttons also
did not contain horizontal spacing.

* Add links to Learn Chef Rally content.
I also corrected a few caplitalization issues and edited a few sentences for clarity.

* ssh => SSH
* Update Slack URL
Was pointing to Habitat by mistake.

Signed-off-by: Thomas Petchel <tpetchel@gmail.com>
2018-03-14 11:01:12 -04:00

3.6 KiB

title
InSpec Universal Matchers Reference

InSpec Universal Matchers Reference

InSpec uses matchers to help compare resource values to expectations. The following matchers are available:

You may also use any matcher provided by RSpec::Expectations, but those matchers are outside of InSpec's scope of support.

The following InSpec-supported universal matchers are available:

  • be - make numeric comparisons
  • be_in - look for the property value in a list
  • cmp - general-use equality (try this first)
  • eq - type-specific equality
  • include - look for an expected value in a list-valued property
  • match - look for patterns in text using regular expressions

See Explore InSpec resources on Learn Chef Rally to learn more about InSpec's built-in matchers.

be

This matcher can be followed by many different comparison operators. Always make sure to use numbers, not strings, for these comparisons.

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

cmp

Unlike eq, cmp is a matcher for less-restrictive comparisons. It will try to fit the actual value to the type you are comparing it to. This is meant to relieve the user from having to write type-casts and resolutions.

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

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

cmp behaves in the following way:

  • Compare strings to numbers

    describe sshd_config do
      its('Protocol') { should eq '2' }
    
      its('Protocol') { should cmp '2' }
      its('Protocol') { should cmp 2 }
    end
    
  • String comparisons are not case-sensitive

    describe auditd_conf do
      its('log_format') { should cmp 'raw' }
      its('log_format') { should cmp 'RAW' }
    end
    
  • Recognize versions embedded in strings

    describe package(curl) do
      its('version') { should cmp > '7.35.0-1ubuntu2.10' }
    end
    
  • Compare arrays with only one entry to a value

    describe passwd.uids(0) do
      its('users') { should cmp 'root' }
      its('users') { should cmp ['root'] }
    end
    
  • Single-value arrays of strings may also be compared to a regex

    describe auditd_conf do
      its('log_format') { should cmp /raw/i }
    end
    
  • Improved printing of octal comparisons

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

eq

Test for exact equality of two values.

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

eq fails if types don't match. Please keep this in mind, when comparing configuration entries that are numbers:

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

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

For less restrictive comparisons, please use cmp.


include

Verifies if a value is included in a list.

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

be_in

Verifies that an item is included in a list.

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

match

Check if a string matches a regular expression.

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