add matchers docs

This commit is contained in:
Dominik Richter 2016-02-18 13:44:21 +01:00
parent 03bf732d82
commit 301a39d4f0

129
docs/matchers.rst Normal file
View file

@ -0,0 +1,129 @@
=====================================================
InSpec Matchers Reference
=====================================================
Inspec uses matchers to help compare resource values to expectations. The following matchers are available:
* `be`
* `cmp`
* `eq`
* `include`
* `match`
be
=====================================================
This matcher can be followed by many different comparison operators. Always make sure to use numbers, not strings, for these comparisons.
.. code-block:: ruby
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.
.. code-block:: ruby
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
.. code-block:: ruby
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
.. code-block:: ruby
describe auditd_conf do
its('log_format') { should cmp 'raw' }
its('log_format') { should cmp 'RAW' }
end
* Compare arrays with only one entry to a value
.. code-block:: ruby
describe passwd.uids(0) do
its('users') { should cmp 'root' }
its('users') { should cmp ['root'] }
end
* Improved printing of octal comparisons
.. code-block:: ruby
describe file('/proc/cpuinfo') do
its('mode') { should cmp '0345' }
end
expected: 0345
got: 0444
eq
=====================================================
Test for exact equality of two values.
.. code-block:: ruby
describe sshd_config do
its('RSAAuthentication') { should_not eq 'no' }
its('Protocol') { should eq '2' }
end
It fails if types don't match. Please keep this in mind, when comparing configuration
entries that are numbers:
.. code-block:: ruby
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.
.. code-block:: ruby
describe passwd do
its('users') { should include 'my_user' }
end
match
=====================================================
Check if a string matches a regular expression.
.. code-block:: ruby
describe sshd_config do
its('Ciphers') { should_not match /cbc/ }
end