2018-04-20 02:02:30 +02:00
.. _playbooks_tests:
2018-03-14 20:44:21 +01:00
2017-01-18 03:55:03 +01:00
Tests
-----
2016-07-12 16:13:00 +02:00
.. contents :: Topics
2017-11-27 23:58:08 +01:00
`Tests <http://jinja.pocoo.org/docs/dev/templates/#tests> `_ in Jinja are a way of evaluating template expressions and returning True or False.
Jinja ships with many of these. See `builtin tests`_ in the official Jinja template documentation.
2017-12-07 15:25:46 +01:00
The main difference between tests and filters are that Jinja tests are used for comparisons, whereas filters are used for data manipulation, and have different applications in jinja. Tests can also be used in list processing filters, like `` map() `` and `` select() `` to choose items in the list.
2016-07-12 16:13:00 +02:00
2017-01-18 03:55:03 +01:00
Like all templating, tests always execute on the Ansible controller, **not** on the target of a task, as they test local data.
2016-07-12 16:13:00 +02:00
In addition to those Jinja2 tests, Ansible supplies a few more and users can easily create their own.
2017-11-27 23:58:08 +01:00
.. _test_syntax:
Test syntax
`` ` ` ` ` ` ` ` ``
`Test syntax <http://jinja.pocoo.org/docs/dev/templates/#tests> `_ varies from `filter syntax <http://jinja.pocoo.org/docs/dev/templates/#filters> `_ (`` variable | filter `` ). Historically Ansible has registered tests as both jinja tests and jinja filters, allowing for them to be referenced using filter syntax.
As of Ansible 2.5, using a jinja test as a filter will generate a warning.
The syntax for using a jinja test is as follows::
variable is test_name
Such as::
result is failed
2016-07-12 16:13:00 +02:00
.. _testing_strings:
Testing strings
2017-01-18 03:55:03 +01:00
`` ` ` ` ` ` ` ` ` ` ` ` ``
2016-07-12 16:13:00 +02:00
2018-11-02 21:53:55 +01:00
To match strings against a substring or a regular expression, use the "match", "search" or "regex" filters::
2016-07-12 16:13:00 +02:00
vars:
url: "http://example.com/users/foo/resources/bar"
tasks:
2018-09-06 17:26:58 +02:00
- debug:
2018-02-05 15:14:15 +01:00
msg: "matched pattern 1"
2017-11-27 23:58:08 +01:00
when: url is match("http://example.com/users/.*/resources/.* ")
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "matched pattern 2"
2017-11-27 23:58:08 +01:00
when: url is search("/users/.*/resources/.* ")
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "matched pattern 3"
2017-11-27 23:58:08 +01:00
when: url is search("/users/")
2016-07-12 16:13:00 +02:00
2018-11-02 21:53:55 +01:00
- debug:
msg: "matched pattern 4"
when: url is regex("example.com/\w+/foo")
2016-07-12 16:13:00 +02:00
'match' requires a complete match in the string, while 'search' only requires matching a subset of the string.
.. _testing_versions:
Version Comparison
2017-01-18 03:55:03 +01:00
`` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ``
2016-07-12 16:13:00 +02:00
.. versionadded :: 1.6
2017-11-27 23:58:08 +01:00
.. note :: In 2.5 `` version_compare `` was renamed to `` version ``
2018-09-06 17:26:58 +02:00
To compare a version number, such as checking if the `` ansible_facts['distribution_version'] ``
2017-11-27 23:58:08 +01:00
version is greater than or equal to '12.04', you can use the `` version `` test.
2016-07-12 16:13:00 +02:00
2018-09-06 17:26:58 +02:00
The `` version `` test can also be used to evaluate the `` ansible_facts['distribution_version'] `` ::
2016-07-12 16:13:00 +02:00
2018-09-06 17:26:58 +02:00
{{ ansible_facts['distribution_version'] is version('12.04', '>=') }}
2016-07-12 16:13:00 +02:00
2018-09-06 17:26:58 +02:00
If `` ansible_facts['distribution_version'] `` is greater than or equal to 12.04, this test returns True, otherwise False.
2016-07-12 16:13:00 +02:00
2017-11-27 23:58:08 +01:00
The `` version `` test accepts the following operators::
2016-07-12 16:13:00 +02:00
<, lt, <=, le, >, gt, >=, ge, ==, =, eq, !=, <>, ne
2018-11-26 22:55:25 +01:00
This test also accepts a 3rd parameter, `` strict `` which defines if strict version parsing as defined by `` distutils.version.StrictVersion `` should be used. The default is `` False `` (using `` distutils.version.LooseVersion `` ), `` True `` enables strict version parsing::
2016-07-12 16:13:00 +02:00
2017-11-27 23:58:08 +01:00
{{ sample_version_var is version('1.0', operator='lt', strict=True) }}
2016-07-12 16:13:00 +02:00
.. _math_tests:
2018-08-22 21:22:10 +02:00
Set theory tests
`` ` ` ` ` ` ` ` ` ` ` ` ` ``
2016-07-12 16:13:00 +02:00
2016-10-24 21:53:44 +02:00
.. versionadded :: 2.1
2017-11-27 23:58:08 +01:00
.. note :: In 2.5 `` issubset `` and `` issuperset `` were renamed to `` subset `` and `` superset ``
To see if a list includes or is included by another list, you can use 'subset' and 'superset'::
2016-07-12 16:13:00 +02:00
vars:
a: [1,2,3,4,5]
b: [2,3]
tasks:
2018-02-05 15:14:15 +01:00
- debug:
msg: "A includes B"
2017-11-27 23:58:08 +01:00
when: a is superset(b)
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "B is included in A"
2017-11-27 23:58:08 +01:00
when: b is subset(a)
2016-07-12 16:13:00 +02:00
2018-11-07 21:49:00 +01:00
.. _contains_test:
Test if a list contains a value
`` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ``
.. versionadded :: 2.8
Ansible includes a `` contains `` test which operates similarly, but in reverse of the Jinja2 provided `` in `` test.
This is designed with the ability to allow use of `` contains `` with filters such as `` map `` and `` selectattr `` ::
vars:
lacp_groups:
- master: lacp0
network: 10.65.100.0/24
gateway: 10.65.100.1
dns4:
- 10.65.100.10
- 10.65.100.11
interfaces:
- em1
- em2
- master: lacp1
network: 10.65.120.0/24
gateway: 10.65.120.1
dns4:
- 10.65.100.10
- 10.65.100.11
interfaces:
- em3
- em4
tasks:
- debug:
msg: "{{ (lacp_groups|selectattr('interfaces', 'contains', 'em1')|first).master }}"
2016-07-12 16:13:00 +02:00
.. _path_tests:
2017-03-15 23:09:25 +01:00
.. versionadded :: 2.4
You can use `any` and `all` to check if any or all elements in a list are true or not::
vars:
mylist:
- 1
2018-06-26 21:53:58 +02:00
- "{{ 3 == 3 }}"
2017-03-15 23:09:25 +01:00
- True
myotherlist:
- False
- True
tasks:
2018-02-05 15:14:15 +01:00
- debug:
msg: "all are true!"
2017-03-15 23:09:25 +01:00
when: mylist is all
2018-02-05 15:14:15 +01:00
- debug:
msg: "at least one is true"
2017-11-27 23:58:08 +01:00
when: myotherlist is any
2017-03-15 23:09:25 +01:00
2016-07-12 16:13:00 +02:00
Testing paths
2017-01-18 03:55:03 +01:00
`` ` ` ` ` ` ` ` ` ` ``
2016-07-12 16:13:00 +02:00
2018-07-07 21:04:05 +02:00
.. note :: In 2.5 the following tests were renamed to remove the `` is_ `` prefix
2017-11-27 23:58:08 +01:00
2016-07-12 16:13:00 +02:00
The following tests can provide information about a path on the controller::
2018-02-05 15:14:15 +01:00
- debug:
msg: "path is a directory"
2017-11-27 23:58:08 +01:00
when: mypath is directory
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "path is a file"
2017-11-27 23:58:08 +01:00
when: mypath is file
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "path is a symlink"
2017-11-27 23:58:08 +01:00
when: mypath is link
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "path already exists"
2017-11-27 23:58:08 +01:00
when: mypath is exists
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "path is {{ (mypath is abs)|ternary('absolute','relative')}}"
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "path is the same file as path2"
2017-11-27 23:58:08 +01:00
when: mypath is same_file(path2)
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "path is a mount"
2017-11-27 23:58:08 +01:00
when: mypath is mount
2016-07-12 16:13:00 +02:00
.. _test_task_results:
Task results
2017-01-18 03:55:03 +01:00
`` ` ` ` ` ` ` ` ` ``
2016-07-12 16:13:00 +02:00
The following tasks are illustrative of the tests meant to check the status of tasks::
tasks:
- shell: /usr/bin/foo
register: result
ignore_errors: True
2018-02-05 15:14:15 +01:00
- debug:
msg: "it failed"
2017-11-27 23:58:08 +01:00
when: result is failed
2016-07-12 16:13:00 +02:00
# in most cases you'll want a handler, but if you want to do something right now, this is nice
2018-02-05 15:14:15 +01:00
- debug:
msg: "it changed"
2017-11-27 23:58:08 +01:00
when: result is changed
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "it succeeded in Ansible >= 2.1"
2017-11-27 23:58:08 +01:00
when: result is succeeded
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "it succeeded"
2017-11-27 23:58:08 +01:00
when: result is success
2016-07-12 16:13:00 +02:00
2018-02-05 15:14:15 +01:00
- debug:
msg: "it was skipped"
2017-11-27 23:58:08 +01:00
when: result is skipped
2016-07-12 16:13:00 +02:00
.. note :: From 2.1, you can also use success, failure, change, and skip so that the grammar matches, for those who need to be strict about it.
.. _builtin tests: http://jinja.pocoo.org/docs/templates/#builtin-tests
.. seealso ::
:doc: `playbooks`
An introduction to playbooks
:doc: `playbooks_conditionals`
Conditional statements in playbooks
:doc: `playbooks_variables`
All about variables
:doc: `playbooks_loops`
Looping in playbooks
2017-06-06 23:39:48 +02:00
:doc: `playbooks_reuse_roles`
2016-07-12 16:13:00 +02:00
Playbook organization by roles
:doc: `playbooks_best_practices`
Best practices in playbooks
2018-07-21 15:48:47 +02:00
`User Mailing List <https://groups.google.com/group/ansible-devel> `_
2016-07-12 16:13:00 +02:00
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net> `_
#ansible IRC chat channel