Tests

    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 and select() to choose items in the list.

    Like all templating, tests always execute on the Ansible controller, not on the target of a task, as they test local data.

    In addition to those Jinja2 tests, Ansible supplies a few more and users can easily create their own.

    Test syntax varies from (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:

    Such as:

    1. result is failed

    Testing strings

    To match strings against a substring or a regex, use the “match” or “search” filter:

    1. vars:
    2.   url: "http://example.com/users/foo/resources/bar"
    3.  
    4. tasks:
    5.     - debug:
    6.         msg: "matched pattern 1"
    7.       when: url is match("http://example.com/users/.*/resources/.*")
    8.  
    9.     - debug:
    10.         msg: "matched pattern 2"
    11.       when: url is search("/users/.*/resources/.*")
    12.  
    13.     - debug:
    14.         msg: "matched pattern 3"
    15.       when: url is search("/users/")

    ‘match’ requires a complete match in the string, while ‘search’ only requires matching a subset of the string.

    Note

    In 2.5 version_compare was renamed to version

    To compare a version number, such as checking if the ansible_facts['distribution_version']version is greater than or equal to ‘12.04’, you can use the test.

    The version test can also be used to evaluate the ansible_facts['distribution_version']:

    If ansible_facts['distribution_version'] is greater than or equal to 12.04, this test returns True, otherwise False.

    The version test accepts the following operators:

    1. <, lt, <=, le, >, gt, >=, ge, ==, =, eq, !=, <>, ne

    This test also accepts a 3rd parameter, strict which defines if strict version parsing shouldbe used. The default is , but this setting as True uses more strict version parsing:

    1. {{ sample_version_var is version('1.0', operator='lt', strict=True) }}

    Set theory tests

    New in version 2.1.

    Note

    To see if a list includes or is included by another list, you can use ‘subset’ and ‘superset’:

    New in version 2.4.

    You can use any and all to check if any or all elements in a list are true or not:

    1. vars:
    2.   mylist:
    3.       - "{{ 3 == 3 }}"
    4.       - True
    5.   myotherlist:
    6.       - False
    7.       - True
    8. tasks:
    9.  
    10.   - debug:
    11.       msg: "all are true!"
    12.     when: mylist is all
    13.  
    14.   - debug:
    15.       msg: "at least one is true"
    16.     when: myotherlist is any

    Note

    In 2.5 the following tests were renamed to remove the prefix

    The following tests can provide information about a path on the controller:

    1. - debug:
    2.     msg: "path is a directory"
    3.   when: mypath is directory
    4.  
    5. - debug:
    6.     msg: "path is a file"
    7.   when: mypath is file
    8.  
    9. - debug:
    10.     msg: "path is a symlink"
    11.   when: mypath is link
    12.  
    13. - debug:
    14.   when: mypath is exists
    15.  
    16. - debug:
    17.     msg: "path is {{ (mypath is abs)|ternary('absolute','relative')}}"
    18.  
    19. - debug:
    20.     msg: "path is the same file as path2"
    21.   when: mypath is same_file(path2)
    22.  
    23. - debug:
    24.     msg: "path is a mount"
    25.   when: mypath is mount

    Task results

    The following tasks are illustrative of the tests meant to check the status of tasks:

    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.