diff options
author | Brian Coca <bcoca@users.noreply.github.com> | 2022-09-07 09:49:23 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-09-07 09:49:23 -0400 |
commit | 77ba025a1301c62dd945fd0f18153c5eef9a0b77 (patch) | |
tree | 9eb2c05ede7cac81658d2724279935bf62acf866 /lib | |
parent | fcfdca8e7d2875f81d441a24d7b53ec12a04b4de (diff) | |
download | ansible-77ba025a1301c62dd945fd0f18153c5eef9a0b77.tar.gz |
document tests (#78685)
Document the builtin test plugins
Co-authored-by: Felix Fontein <felix@fontein.de>
Diffstat (limited to 'lib')
43 files changed, 554 insertions, 23 deletions
diff --git a/lib/ansible/plugins/test/abs.yml b/lib/ansible/plugins/test/abs.yml new file mode 100644 index 0000000000..a2a43fb05a --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/all.yml b/lib/ansible/plugins/test/all.yml new file mode 100644 index 0000000000..e227d6e422 --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/any.yml b/lib/ansible/plugins/test/any.yml new file mode 100644 index 0000000000..0ce9e48cdf --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/changed.yml b/lib/ansible/plugins/test/changed.yml index c626feafb3..1fb1e5e8a0 100644 --- a/lib/ansible/plugins/test/changed.yml +++ b/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 diff --git a/lib/ansible/plugins/test/contains.yml b/lib/ansible/plugins/test/contains.yml new file mode 100644 index 0000000000..68741da09e --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/directory.yml b/lib/ansible/plugins/test/directory.yml new file mode 100644 index 0000000000..1e03d81301 --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/exists.yml b/lib/ansible/plugins/test/exists.yml new file mode 100644 index 0000000000..8e911b816c --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/failed.yml b/lib/ansible/plugins/test/failed.yml index 8446808d5f..b8a9b3e7f7 100644 --- a/lib/ansible/plugins/test/failed.yml +++ b/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 diff --git a/lib/ansible/plugins/test/falsy.yml b/lib/ansible/plugins/test/falsy.yml new file mode 100644 index 0000000000..49a198f12a --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/file.yml b/lib/ansible/plugins/test/file.yml new file mode 100644 index 0000000000..ee619892e8 --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/files.py b/lib/ansible/plugins/test/files.py index bb0dfd0134..35761a45f4 100644 --- a/lib/ansible/plugins/test/files.py +++ b/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, } diff --git a/lib/ansible/plugins/test/finished.yml b/lib/ansible/plugins/test/finished.yml index 06d053a565..b01b132a2f 100644 --- a/lib/ansible/plugins/test/finished.yml +++ b/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 diff --git a/lib/ansible/plugins/test/is_abs.yml b/lib/ansible/plugins/test/is_abs.yml new file mode 120000 index 0000000000..27d8741434 --- /dev/null +++ b/lib/ansible/plugins/test/is_abs.yml @@ -0,0 +1 @@ +abs.yml
\ No newline at end of file diff --git a/lib/ansible/plugins/test/is_dir.yml b/lib/ansible/plugins/test/is_dir.yml new file mode 120000 index 0000000000..9b346b6d34 --- /dev/null +++ b/lib/ansible/plugins/test/is_dir.yml @@ -0,0 +1 @@ +directory.yml
\ No newline at end of file diff --git a/lib/ansible/plugins/test/is_file.yml b/lib/ansible/plugins/test/is_file.yml new file mode 120000 index 0000000000..b84b46f17a --- /dev/null +++ b/lib/ansible/plugins/test/is_file.yml @@ -0,0 +1 @@ +file.yml
\ No newline at end of file diff --git a/lib/ansible/plugins/test/is_link.yml b/lib/ansible/plugins/test/is_link.yml new file mode 120000 index 0000000000..784a1fc5a8 --- /dev/null +++ b/lib/ansible/plugins/test/is_link.yml @@ -0,0 +1 @@ +link.yml
\ No newline at end of file diff --git a/lib/ansible/plugins/test/is_same_file.yml b/lib/ansible/plugins/test/is_same_file.yml new file mode 120000 index 0000000000..c7df9edbc5 --- /dev/null +++ b/lib/ansible/plugins/test/is_same_file.yml @@ -0,0 +1 @@ +same_file.yml
\ No newline at end of file diff --git a/lib/ansible/plugins/test/ismount.yml b/lib/ansible/plugins/test/ismount.yml new file mode 120000 index 0000000000..782933d9dd --- /dev/null +++ b/lib/ansible/plugins/test/ismount.yml @@ -0,0 +1 @@ +mount.yml
\ No newline at end of file diff --git a/lib/ansible/plugins/test/isnan.yml b/lib/ansible/plugins/test/isnan.yml new file mode 120000 index 0000000000..4308c9d23f --- /dev/null +++ b/lib/ansible/plugins/test/isnan.yml @@ -0,0 +1 @@ +nan.yml
\ No newline at end of file diff --git a/lib/ansible/plugins/test/issubset.yml b/lib/ansible/plugins/test/issubset.yml new file mode 120000 index 0000000000..a77e5b3c9c --- /dev/null +++ b/lib/ansible/plugins/test/issubset.yml @@ -0,0 +1 @@ +subset.yml
\ No newline at end of file diff --git a/lib/ansible/plugins/test/issuperset.yml b/lib/ansible/plugins/test/issuperset.yml new file mode 120000 index 0000000000..ecb11158b5 --- /dev/null +++ b/lib/ansible/plugins/test/issuperset.yml @@ -0,0 +1 @@ +superset.yml
\ No newline at end of file diff --git a/lib/ansible/plugins/test/link.yml b/lib/ansible/plugins/test/link.yml new file mode 100644 index 0000000000..8457c5a5bd --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/link_exists.yml b/lib/ansible/plugins/test/link_exists.yml new file mode 100644 index 0000000000..f8631cd94d --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/match.yml b/lib/ansible/plugins/test/match.yml new file mode 100644 index 0000000000..1687545db0 --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/mathstuff.py b/lib/ansible/plugins/test/mathstuff.py index 952562cc17..9a3f467bf2 100644 --- a/lib/ansible/plugins/test/mathstuff.py +++ b/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, } diff --git a/lib/ansible/plugins/test/mount.yml b/lib/ansible/plugins/test/mount.yml new file mode 100644 index 0000000000..a15d98f4b8 --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/nan.yml b/lib/ansible/plugins/test/nan.yml new file mode 100644 index 0000000000..7297ef9e69 --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/reachable.yml b/lib/ansible/plugins/test/reachable.yml index 5d2b66bb90..8cb1ce30f2 100644 --- a/lib/ansible/plugins/test/reachable.yml +++ b/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 diff --git a/lib/ansible/plugins/test/regex.yml b/lib/ansible/plugins/test/regex.yml new file mode 100644 index 0000000000..90ca78673e --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/same_file.yml b/lib/ansible/plugins/test/same_file.yml new file mode 100644 index 0000000000..a10a36acc3 --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/search.yml b/lib/ansible/plugins/test/search.yml new file mode 100644 index 0000000000..9e94f0f319 --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/skipped.yml b/lib/ansible/plugins/test/skipped.yml index 692c536e87..97271728ad 100644 --- a/lib/ansible/plugins/test/skipped.yml +++ b/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 diff --git a/lib/ansible/plugins/test/started.yml b/lib/ansible/plugins/test/started.yml index 686607a563..0cb0602a13 100644 --- a/lib/ansible/plugins/test/started.yml +++ b/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 diff --git a/lib/ansible/plugins/test/subset.yml b/lib/ansible/plugins/test/subset.yml new file mode 100644 index 0000000000..d57d05bd6d --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/success.yml b/lib/ansible/plugins/test/success.yml index 0761ba4a9b..4626f9fe53 100644 --- a/lib/ansible/plugins/test/success.yml +++ b/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 diff --git a/lib/ansible/plugins/test/superset.yml b/lib/ansible/plugins/test/superset.yml new file mode 100644 index 0000000000..72be3d5efb --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/truthy.yml b/lib/ansible/plugins/test/truthy.yml new file mode 100644 index 0000000000..01d5255905 --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/unreachable.yml b/lib/ansible/plugins/test/unreachable.yml index d2837a8f85..ed6c17e72f 100644 --- a/lib/ansible/plugins/test/unreachable.yml +++ b/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) diff --git a/lib/ansible/plugins/test/uri.yml b/lib/ansible/plugins/test/uri.yml index 1e6120d7cc..bb3b8bdd9c 100644 --- a/lib/ansible/plugins/test/uri.yml +++ b/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: diff --git a/lib/ansible/plugins/test/url.yml b/lib/ansible/plugins/test/url.yml index 6285e64a49..36b6c7706e 100644 --- a/lib/ansible/plugins/test/url.yml +++ b/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: diff --git a/lib/ansible/plugins/test/urn.yml b/lib/ansible/plugins/test/urn.yml index 321b5a5667..81a66863af 100644 --- a/lib/ansible/plugins/test/urn.yml +++ b/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: diff --git a/lib/ansible/plugins/test/vault_encrypted.yml b/lib/ansible/plugins/test/vault_encrypted.yml new file mode 100644 index 0000000000..58d79f16f7 --- /dev/null +++ b/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 diff --git a/lib/ansible/plugins/test/version.yml b/lib/ansible/plugins/test/version.yml index 0ecd38cec9..92b6048439 100644 --- a/lib/ansible/plugins/test/version.yml +++ b/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: |