document tests (#78685)

Document the builtin test plugins

Co-authored-by: Felix Fontein <felix@fontein.de>

lib/ansible/plugins/test/abs.yml

@@ -0,0 +1,23 @@
+DOCUMENTATION:
+  name: abs
+  author: Ansible Core
+  version_added: "2.5"
+  short_description: is the path absolute
+  aliases: [is_abs]
+  description:
+    - Check if the provided path is absolute, not relative.
+    - An absolute path expresses the location of a filesystem object starting at the filesystem root and requires no context.
+    - A relative path does not start at the filesystem root and requires a 'current' directory as a context to resolve.
+  options:
+    _input:
+      description: A path.
+      type: path
+
+EXAMPLES:
+    is_path_absolute: "{{ '/etc/hosts' is abs }}}"
+    relative_paths: "{{ all_paths | reject('abs') }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the path is absolute, C(False) if it is relative.
+    type: boolean

lib/ansible/plugins/test/all.yml

@@ -0,0 +1,23 @@
+DOCUMENTATION:
+  name: all
+  author: Ansible Core
+  version_added: "2.4"
+  short_description: are all conditions in a list true
+  description:
+    - This test checks each condition in a list for truthiness.
+    - Same as the C(all) Python function.
+  options:
+    _input:
+      description: List of conditions, each can be a boolean or conditional expression that results in a boolean value.
+      type: list
+      elements: raw
+      required: True
+EXAMPLES: |
+  varexpression: "{{ 3 == 3 }}"
+  # are all statements true?
+  {{ [true, booleanvar, varexpression] is all }}
+
+RETURN:
+  _value:
+    description: Returns C(True) if all elements of the list were True, C(False) otherwise.
+    type: boolean

lib/ansible/plugins/test/any.yml

@@ -0,0 +1,23 @@
+DOCUMENTATION:
+  name: any
+  author: Ansible Core
+  version_added: "2.4"
+  short_description: is any conditions in a list true
+  description:
+    - This test checks each condition in a list for truthiness.
+    - Same as the C(any) Python function.
+  options:
+    _input:
+      description: List of conditions, each can be a boolean or conditional expression that results in a boolean value.
+      type: list
+      elements: raw
+      required: True
+EXAMPLES: |
+  varexpression: "{{ 3 == 3 }}"
+  # are all statements true?
+  {{ [false, booleanvar, varexpression] is any}}
+
+RETURN:
+  _value:
+    description: Returns C(True) if any element of the list was true, C(False) otherwise.
+    type: boolean

lib/ansible/plugins/test/changed.yml

@@ -2,7 +2,8 @@ DOCUMENTATION:
   name: changed
   author: Ansible Core
   version_added: "1.9"
-  short_description: check if task required changes
+  short_description: did the task require changes
+  aliases: [change]
   description:
     - Tests if task required changes to complete
     - This test checks for the existance of a C(changed) key in the input dictionary and that it is C(True) if present

lib/ansible/plugins/test/contains.yml

@@ -0,0 +1,49 @@
+DOCUMENTATION:
+  name: contains
+  author: Ansible Core
+  version_added: "2.4"
+  short_description: does the list contain this element
+  description:
+    - Checks the supplied element against the input list to see if it exists within it.
+  options:
+    _input:
+      description: List of elements to compare.
+      type: list
+      elements: raw
+      required: True
+    _contained:
+      description: Element to test for.
+      type: raw
+      required: True
+EXAMPLES: |
+  # simple expression
+  {{ listofthings is contains('this') }}
+
+  # as a selector
+  - action: module=doessomething
+    when: lacp_groups|selectattr('interfaces', 'contains', 'em1')|first).master
+    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
+RETURN:
+  _value:
+    description: Returns C(True) if the specified element is contained in the supplied sequence, C(False) otherwise.
+    type: boolean

lib/ansible/plugins/test/directory.yml

@@ -0,0 +1,21 @@
+DOCUMENTATION:
+  name: directory
+  author: Ansible Core
+  version_added: "2.5"
+  short_description: does the path resolve to an existing directory
+  description:
+    - Check if the provided path maps to an existing directory on the controller's filesystem (localhost).
+  options:
+    _input:
+      description: A path.
+      type: path
+
+EXAMPLES:
+  vars:
+    my_etc_hosts_not_a_dir: "{{ '/etc/hosts' is directory}}"
+    list_of_files: "{{ list_of_paths | reject('directory') }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the path corresponds to an existing directory on the filesystem on the controller, c(False) if otherwise.
+    type: boolean

lib/ansible/plugins/test/exists.yml

@@ -0,0 +1,22 @@
+DOCUMENTATION:
+  name: exists
+  author: Ansible Core
+  version_added: "2.5"
+  short_description: does the path exist, follow symlinks
+  description:
+    - Check if the provided path maps to an existing filesystem object on the controller (localhost).
+    - Follows symlinks and checks the target of the symlink instead of the link itself, use the C(link) or C(link_exists) tests to check on the link.
+  options:
+    _input:
+      description: a path
+      type: path
+
+EXAMPLES:
+  vars:
+    my_etc_hosts_exists: "{{ '/etc/hosts' is exist }}"
+    list_of_local_files_to_copy_to_remote: "{{ list_of_all_possible_files | select('exists') }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the path corresponds to an existing filesystem object on the controller (after following symlinks), C(False) if otherwise.
+    type: boolean

lib/ansible/plugins/test/failed.yml

@@ -2,10 +2,12 @@ DOCUMENTATION:
   name: failed
   author: Ansible Core
   version_added: "1.9"
-  short_description: check if task failed
+  short_description: did the task fail
+  aliases: [failure]
   description:
-    - Tests if task finished in failure , opposite of C(success).
-    - This test checks for the existance of a C(failed) key in the input dictionary and that it is C(True) if present
+    - Tests if task finished in failure, opposite of C(succeeded).
+    - This test checks for the existance of a C(failed) key in the input dictionary and that it is C(True) if present.
+    - Tasks that get skipped or not executed due to other failures (syntax, templating, unreachable host, etc) do not return a 'failed' status.
   options:
     _input:
       description: registered result from an Ansible task
@@ -13,9 +15,9 @@ DOCUMENTATION:
       required: True
 EXAMPLES: |
   # test 'status' to know how to respond
-  {{ (taskresults is failed }}
+  {{ taskresults is failed }}
 
 RETURN:
   _value:
-    description: Returns C(False) if the task was completed as a failure, C(True) if otherwise.
+    description: Returns C(True) if the task was failed, C(False) otherwise.
     type: boolean

lib/ansible/plugins/test/falsy.yml

@@ -0,0 +1,24 @@
+DOCUMENTATION:
+  name: falsy
+  author: Ansible Core
+  version_added: "2.10"
+  short_description: Pythonic false
+  description:
+    - This check is a more Python version of what is 'false'.
+    - It is the opposite of 'truthy'.
+  options:
+    _input:
+      description: An expression that can be expressed in a boolean context.
+      type: string
+      required: True
+    convert_bool:
+      description: Attempts to convert the result to a strict Python boolean vs normally acceptable values (C(yes)/C(no), C(on)/C(off), C(0)/C(1), etc).
+      type: bool
+      default: false
+EXAMPLES: |
+    thisisfalse: '{{ "any string" is falsy }}'
+    thisistrue: '{{ "" is falsy }}'
+RETURN:
+  _value:
+    description: Returns C(False) if the condition is not "Python truthy", C(True) otherwise.
+    type: boolean

lib/ansible/plugins/test/file.yml

@@ -0,0 +1,22 @@
+DOCUMENTATION:
+  name: file
+  author: Ansible Core
+  version_added: "2.5"
+  short_description: does the path resolve to an existing file
+  description:
+    - Check if the provided path maps to an existing file on the controller's filesystem (localhost)
+  aliases: [is_file]
+  options:
+    _input:
+      description: A path.
+      type: path
+
+EXAMPLES:
+  vars:
+    my_etc_hosts_is_a_file: "{{ '/etc/hosts' is file }}"
+    list_of_files: "{{ list_of_paths | select('file') }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the path corresponds to an existing file on the filesystem on the controller, C(False) if otherwise.
+    type: boolean

lib/ansible/plugins/test/files.py

@@ -29,20 +29,20 @@ class TestModule(object):
     def tests(self):
         return {
             # file testing
-            'is_dir': isdir,
             'directory': isdir,
-            'is_file': isfile,
+            'is_dir': isdir,
             'file': isfile,
-            'is_link': islink,
+            'is_file': isfile,
             'link': islink,
+            'is_link': islink,
             'exists': exists,
             'link_exists': lexists,
 
             # path testing
-            'is_abs': isabs,
             'abs': isabs,
-            'is_same_file': samefile,
+            'is_abs': isabs,
             'same_file': samefile,
-            'is_mount': ismount,
+            'is_same_file': samefile,
             'mount': ismount,
+            'is_mount': ismount,
         }

lib/ansible/plugins/test/finished.yml

@@ -2,7 +2,7 @@ DOCUMENTATION:
   name: finished
   author: Ansible Core
   version_added: "1.9"
-  short_description: check if a task has finished
+  short_description: Did async task finish
   description:
     - Used to test if an async task has finished, it will aslo work with normal tasks but will issue a warning.
     - This test checks for the existance of a C(finished) key in the input dictionary and that it is C(1) if present

lib/ansible/plugins/test/is_abs.yml

@@ -0,0 +1 @@
+abs.yml

lib/ansible/plugins/test/is_dir.yml

@@ -0,0 +1 @@
+directory.yml

lib/ansible/plugins/test/is_file.yml

@@ -0,0 +1 @@
+file.yml

lib/ansible/plugins/test/is_link.yml

@@ -0,0 +1 @@
+link.yml

lib/ansible/plugins/test/is_same_file.yml

@@ -0,0 +1 @@
+same_file.yml

lib/ansible/plugins/test/ismount.yml

@@ -0,0 +1 @@
+mount.yml

lib/ansible/plugins/test/isnan.yml

@@ -0,0 +1 @@
+nan.yml

lib/ansible/plugins/test/issubset.yml

@@ -0,0 +1 @@
+subset.yml

lib/ansible/plugins/test/issuperset.yml

@@ -0,0 +1 @@
+superset.yml

lib/ansible/plugins/test/link.yml

@@ -0,0 +1,21 @@
+DOCUMENTATION:
+  name: link
+  author: Ansible Core
+  version_added: "2.5"
+  short_description: does the path reference existing symbolic link
+  aliases: [islink]
+  description:
+    - Check if the provided path maps to an existing symlink on the controller's filesystem (localhost).
+  options:
+    _input:
+      description: A path.
+      type: path
+
+EXAMPLES:
+    ismyhostsalink: "{{ '/etc/hosts' is link}}"
+    list_of_symlinks: "{{ list_of_paths | select('link') }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the path corresponds to an existing symlink on the filesystem on the controller, C(False) if otherwise.
+    type: boolean

lib/ansible/plugins/test/link_exists.yml

@@ -0,0 +1,21 @@
+DOCUMENTATION:
+  name: link_exists
+  author: Ansible Core
+  version_added: "2.5"
+  short_description: does the path exist, no follow
+  description:
+    - Check if the provided path maps to an existing symlink on the controller's filesystem (localhost).
+    - Does not follow symlinks, so it only verifies that the link itself exists.
+  options:
+    _input:
+      description: A path.
+      type: path
+
+EXAMPLES:
+    ismyhostsalink: "{{ '/etc/hosts' is link_exists}}"
+    list_of_symlinks: "{{ list_of_paths | select('link_exists') }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the path corresponds to an existing filesystem object on the controller, C(False) if otherwise.
+    type: boolean

lib/ansible/plugins/test/match.yml

@@ -0,0 +1,32 @@
+DOCUMENTATION:
+  name: match
+  author: Ansible Core
+  short_description: Does string match regular expression from the start
+  description:
+    - Compare string against regular expression using Python's match function,
+      this means the regex is automatically anchored at the start of the string.
+  options:
+    _input:
+      description: String to match.
+      type: string
+      required: True
+    pattern:
+      description: Regex to match against.
+      type: string
+      required: True
+    ignorecase:
+      description: Use case insenstive matching.
+      type:
+      default: False
+    multiline:
+      description: Match against mulitple lines in string.
+      type: boolean
+      default: False
+EXAMPLES: |
+  url: "https://example.com/users/foo/resources/bar"
+  foundmatch: url is match("https://example.com/users/.*/resources")
+  nomatch: url is match("/users/.*/resources")
+RETURN:
+  _value:
+    description: Returns C(True) if there is a match, C(False) otherwise.
+    type: boolean

lib/ansible/plugins/test/mathstuff.py

@@ -50,13 +50,13 @@ class TestModule:
     def tests(self):
         return {
             # set theory
-            'issubset': issubset,
             'subset': issubset,
-            'issuperset': issuperset,
+            'issubset': issubset,
             'superset': issuperset,
+            'issuperset': issuperset,
             'contains': contains,
 
             # numbers
-            'isnan': isnotanumber,
             'nan': isnotanumber,
+            'isnan': isnotanumber,
         }

lib/ansible/plugins/test/mount.yml

@@ -0,0 +1,22 @@
+DOCUMENTATION:
+  name: mount
+  author: Ansible Core
+  version_added: "2.5"
+  short_description: does the path resolve to mount point
+  description:
+    - Check if the provided path maps to a filesystem mount point on the controller (localhost).
+  aliases: [is_mount]
+  options:
+    _input:
+      description: A path.
+      type: path
+
+EXAMPLES:
+  vars:
+    ihopefalse: "{{ '/etc/hosts' is mount }}"
+    normallytrue: "{{ '/tmp' is mount }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the path corresponds to a mount point on the controller, C(False) if otherwise.
+    type: boolean

lib/ansible/plugins/test/nan.yml

@@ -0,0 +1,20 @@
+DOCUMENTATION:
+  name: nan
+  author: Ansible Core
+  version_added: "2.5"
+  short_description: is this not a number (NaN)
+  description:
+    - Whether the input is a special floating point number called L(not a number, https://en.wikipedia.org/wiki/NaN).
+  aliases: [is_file]
+  options:
+    _input:
+      description: Possible number representation or string that can be converted into one.
+      type: raw
+      required: true
+EXAMPLES:
+    isnan: "{{ '42' is nan }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the input is NaN, C(False) if otherwise.
+    type: boolean

lib/ansible/plugins/test/reachable.yml

@@ -2,7 +2,7 @@ DOCUMENTATION:
   name: reachable
   author: Ansible Core
   version_added: "1.9"
-  short_description: check task didn't return that host was unreachable
+  short_description: Task did not end due to unreachable host
   description:
     - Tests if task was able to reach the host for execution
     - This test checks for the existance of a C(unreachable) key in the input dictionary and that it is C(False) if present

lib/ansible/plugins/test/regex.yml

@@ -0,0 +1,37 @@
+DOCUMENTATION:
+  name: regex
+  author: Ansible Core
+  short_description: Does string match regular expression from the start
+  description:
+    - Compare string against regular expression using Python's match or search functions.
+  options:
+    _input:
+      description: String to match.
+      type: string
+      required: True
+    pattern:
+      description: Regex to match against.
+      type: string
+      required: True
+    ignorecase:
+      description: Use case insenstive matching.
+      type: boolean
+      default: False
+    multiline:
+      description: Match against multiple lines in string.
+      type: boolean
+      default: False
+    match_type:
+      description: Decide which function to be used to do the matching.
+      type: string
+      choices: [match, search]
+      default: search
+
+EXAMPLES: |
+  url: "https://example.com/users/foo/resources/bar"
+  foundmatch: url is regex("example\.com/\w+/foo")
+
+RETURN:
+  _value:
+    description: Returns C(True) if there is a match, C(False) otherwise.
+    type: boolean

lib/ansible/plugins/test/same_file.yml

@@ -0,0 +1,24 @@
+DOCUMENTATION:
+  name: same_file
+  author: Ansible Core
+  version_added: "2.5"
+  short_description: compares two paths to see if they resolve to the same filesystem object
+  description: Check if the provided paths map to the same location on the controller's filesystem (localhost).
+  aliases: [is_file]
+  options:
+    _input:
+      description: A path.
+      type: path
+      required: true
+    _path2:
+      description: Another path.
+      type: path
+      required: true
+
+EXAMPLES: |
+  amionelevelfromroot: "{{ '/etc/hosts' is same_file('../etc/hosts') }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the paths correspond to the same location on the filesystem on the controller, C(False) if otherwise.
+    type: boolean

lib/ansible/plugins/test/search.yml

@@ -0,0 +1,33 @@
+DOCUMENTATION:
+  name: search
+  author: Ansible Core
+  short_description: Does string match a regular expression
+  description:
+    - Compare string against regular expression using Python's C(search) function.
+  options:
+    _input:
+      description: String to match.
+      type: string
+      required: True
+    pattern:
+      description: Regex to match against.
+      type: string
+      required: True
+    ignorecase:
+      description: Use case insenstive matching.
+      type:
+      default: False
+    multiline:
+      description: Match against mulitple lines in string.
+      type: boolean
+      default: False
+
+EXAMPLES: |
+  url: "https://example.com/users/foo/resources/bar"
+  foundmatch: url is search("https://example.com/users/.*/resources")
+  alsomatch: url is search("users/.*/resources")
+
+RETURN:
+  _value:
+    description: Returns C(True) if there is a match, C(False) otherwise.
+    type: boolean

lib/ansible/plugins/test/skipped.yml

@@ -2,7 +2,8 @@ DOCUMENTATION:
   name: skipped
   author: Ansible Core
   version_added: "1.9"
-  short_description: check if task was skipped
+  short_description: Was task skipped
+  aliases: [skip]
   description:
     - Tests if task was skipped
     - This test checks for the existance of a C(skipped) key in the input dictionary and that it is C(True) if present

lib/ansible/plugins/test/started.yml

@@ -2,7 +2,7 @@ DOCUMENTATION:
   name: started
   author: Ansible Core
   version_added: "1.9"
-  short_description: check if a task has started
+  short_description: Was async task started
   description:
     - Used to check if an async task has started, will also work with non async tasks but will issue a warning.
     - This test checks for the existance of a C(started) key in the input dictionary and that it is C(1) if present

lib/ansible/plugins/test/subset.yml

@@ -0,0 +1,28 @@
+DOCUMENTATION:
+  name: subset
+  author: Ansible Core
+  version_added: "2.4"
+  aliases: [issubset]
+  short_description: is the list a subset of this other list
+  description:
+    - Validate if the first list is a sub set (is included) of the second list.
+    - Same as the C(all) Python function.
+  options:
+    _input:
+      description: List.
+      type: list
+      elements: raw
+      required: True
+    _superset:
+      description: List to test against.
+      type: list
+      elements: raw
+      required: True
+EXAMPLES: |
+  big: [1,2,3,4,5]
+  sml: [3,4]
+  issmallinbig: '{{ small is subset(big) }}'
+RETURN:
+  _value:
+    description: Returns C(True) if the specified list is a subset of the provided list, C(False) otherwise.
+    type: boolean

lib/ansible/plugins/test/success.yml

@@ -3,6 +3,7 @@ DOCUMENTATION:
   author: Ansible Core
   version_added: "1.9"
   short_description: check task success
+  aliases: [succeeded, successful]
   description:
     - Tests if task finished successfully, opposite of C(failed).
     - This test checks for the existance of a C(failed) key in the input dictionary and that it is C(False) if present

lib/ansible/plugins/test/superset.yml

@@ -0,0 +1,28 @@
+DOCUMENTATION:
+  name: superset
+  author: Ansible Core
+  version_added: "2.4"
+  short_description: is the list a superset of this other list
+  aliases: [issuperset]
+  description:
+    - Validate if the first list is a super set (includes) the second list.
+    - Same as the C(all) Python function.
+  options:
+    _input:
+      description: List.
+      type: list
+      elements: raw
+      required: True
+    _subset:
+      description: List to test against.
+      type: list
+      elements: raw
+      required: True
+EXAMPLES: |
+  big: [1,2,3,4,5]
+  sml: [3,4]
+  issmallinbig: '{{ big is superset(small) }}'
+RETURN:
+  _value:
+    description: Returns C(True) if the specified list is a superset of the provided list, C(False) otherwise.
+    type: boolean

lib/ansible/plugins/test/truthy.yml

@@ -0,0 +1,24 @@
+DOCUMENTATION:
+  name: truthy
+  author: Ansible Core
+  version_added: "2.10"
+  short_description: Pythonic true
+  description:
+    - This check is a more Python version of what is 'true'.
+    - It is the opposite of C(falsy).
+  options:
+    _input:
+      description: An expression that can be expressed in a boolean context.
+      type: string
+      required: True
+    convert_bool:
+      description: Attempts to convert to strict python boolean vs normally acceptable values (C(yes)/C(no), C(on)/C(off), C(0)/C(1), etc).
+      type: bool
+      default: false
+EXAMPLES: |
+    thisistrue: '{{ "any string" is truthy }}'
+    thisisfalse: '{{ "" is truthy }}'
+RETURN:
+  _value:
+    description: Returns C(True) if the condition is not "Python truthy", C(False) otherwise.
+    type: boolean

lib/ansible/plugins/test/unreachable.yml

@@ -2,7 +2,7 @@ DOCUMENTATION:
   name: unreachable
   author: Ansible Core
   version_added: "1.9"
-  short_description: check task returned that the host was unreachable
+  short_description: Did task end due to the host was unreachable
   description:
     - Tests if task was not able to reach the host for execution
     - This test checks for the existance of a C(unreachable) key in the input dictionary and that it's value is C(True)

lib/ansible/plugins/test/uri.yml

@@ -2,7 +2,7 @@ DOCUMENTATION:
   name: uri
   author: Ansible Core
   version_added: "2.14"
-  short_description: check if string is a valid URI
+  short_description: is the string a valid URI
   description:
     - Validates that the input string conforms to the URI standard, optionally that is also in the list of schemas provided.
   options:

lib/ansible/plugins/test/url.yml

@@ -2,7 +2,7 @@ DOCUMENTATION:
   name: url
   author: Ansible Core
   version_added: "2.14"
-  short_description: check if string is a valid URL
+  short_description: is the string a valid URL
   description:
     - Validates a string to conform to the URL standard.
   options:

lib/ansible/plugins/test/urn.yml

@@ -2,7 +2,7 @@ DOCUMENTATION:
   name: urn
   author: Ansible Core
   version_added: "2.14"
-  short_description: check if string is a valid URN
+  short_description: is the string a valid URN
   description:
     - Validates that the input string conforms to the URN standard.
   options:

lib/ansible/plugins/test/vault_encrypted.yml

@@ -0,0 +1,19 @@
+DOCUMENTATION:
+  name: truthy
+  author: Ansible Core
+  version_added: "2.10"
+  short_description: Is this an encrypted vault
+  description:
+    - Verifies if the input is an Ansible vault.
+  options:
+    _input:
+      description: The possible vault.
+      type: string
+      required: True
+EXAMPLES: |
+    thisisfalse: '{{ "any string" is ansible_vault }}'
+    thisistrue: '{{ "$ANSIBLE_VAULT;1.2;AES256;dev...." is ansible_vault }}'
+RETURN:
+  _value:
+    description: Returns C(True) if the input is a valid ansible vault, C(False) otherwise.
+    type: boolean

lib/ansible/plugins/test/version.yml

@@ -3,6 +3,7 @@ DOCUMENTATION:
   author: Ansible Core
   version_added: "1.6"
   short_description: compare version strings
+  aliases: [version_compare]
   description:
     - Compare version strings using various versioning schemes
   options: