Add uri, urn and url test plugins (#77423)

and docs!

Co-authored-by: Tabah Baridule <dulemartins07@gmail.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/added_uri_tests.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - new tests url, uri and urn will verify string as such, but they don't check existance of the resource

lib/ansible/plugins/test/uri.py

@@ -0,0 +1,46 @@
+# (c) Ansible Project
+
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+from urllib.parse import urlparse
+
+
+def is_uri(value, schemes=None):
+    ''' Will verify that the string passed is a valid 'URI', if given a list of valid schemes it will match those '''
+    try:
+        x = urlparse(value)
+        isit = all([x.scheme is not None, x.path is not None, not schemes or x.scheme in schemes])
+    except Exception as e:
+        isit = False
+    return isit
+
+
+def is_url(value, schemes=None):
+    ''' Will verify that the string passed is a valid 'URL' '''
+
+    isit = is_uri(value, schemes)
+    if isit:
+        try:
+            x = urlparse(value)
+            isit = bool(x.netloc or x.scheme == 'file')
+        except Exception as e:
+            isit = False
+    return isit
+
+
+def is_urn(value):
+    return is_uri(value, ['urn'])
+
+
+class TestModule(object):
+    ''' Ansible URI jinja2 test '''
+
+    def tests(self):
+        return {
+            # file testing
+            'uri': is_uri,
+            'url': is_url,
+            'urn': is_urn,
+        }

lib/ansible/plugins/test/uri.yml

@@ -0,0 +1,30 @@
+DOCUMENTATION:
+  name: uri
+  author: Ansible Core
+  version_added: "2.14"
+  short_description: check if string is 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:
+    _input:
+      description: Possible URI.
+      type: string
+      required: True
+    schemes:
+      description: Subset of URI schemas to validate against, otherwise B(any) scheme is considered valid.
+      type: list
+      elements: string
+      required: False
+EXAMPLES: |
+  # URLs are URIs
+  {{ 'http://example.com' is uri }}
+  # but not all URIs are URLs
+  {{ 'mailto://nowone@example.com' is uri }}
+  # looking only for file transfers URIs
+  {{ 'mailto://nowone@example.com' is not uri(schemes=['ftp', 'ftps', 'sftp', 'file']) }}
+  # make sure URL conforms to the 'special schemas'
+  {{ 'http://nobody:secret@example.com' is uri(['ftp', 'ftps', 'http', 'https', 'ws', 'wss']) }}
+RETURN:
+  _value:
+    description: Returns C(false) if the string is not a URI or the schema extracted does not match the supplied list.
+    type: boolean

lib/ansible/plugins/test/url.yml

@@ -0,0 +1,29 @@
+DOCUMENTATION:
+  name: url
+  author: Ansible Core
+  version_added: "2.14"
+  short_description: check if string is a valid URL
+  description:
+    - Validates a string to conform to the URL standard.
+  options:
+    _input:
+      description: Possible URL.
+      type: string
+      required: True
+    schemes:
+      description: Subset of URI schemas to validate against, otherwise B(any) scheme is considered valid.
+      type: list
+      elements: string
+EXAMPLES: |
+  # simple URL
+  {{ 'http://example.com' is url }}
+  # looking only for file transfers URIs
+  {{ 'mailto://nowone@example.com' is not uri(schemes=['ftp', 'ftps', 'sftp', 'file']) }}
+  #  but it is according to standard
+  {{ 'mailto://nowone@example.com' is not uri }}
+  # more complex URL
+  {{ 'ftp://admin:secret@example.com/path/to/myfile.yml' is url }}
+RETURN:
+  _value:
+    description: Returns C(false) if the string is not a URL, C(true) otherwise.
+    type: boolean

lib/ansible/plugins/test/urn.yml

@@ -0,0 +1,21 @@
+DOCUMENTATION:
+  name: urn
+  author: Ansible Core
+  version_added: "2.14"
+  short_description: check if string is a valid URN
+  description:
+    - Validates that the input string conforms to the URN standard.
+  options:
+    _input:
+      description: Possible URN.
+      type: string
+      required: True
+EXAMPLES: |
+  # ISBN in URN format
+  {{ 'urn:isbn:9780302376463' is urn }}
+  # this is URL/URI but not URN
+  {{ 'mailto://nowone@example.com' is not urn }}
+RETURN:
+  _value:
+    description: Returns C(true) if the string is a URN and C(false) if  it is not.
+    type: boolean

test/integration/targets/test_uri/aliases

@@ -0,0 +1 @@
+shippable/posix/group5

test/integration/targets/test_uri/tasks/main.yml

@@ -0,0 +1,43 @@
+- name: urX tests
+  vars:
+    special: ['http', 'https', 'ftp', 'ftps', 'ws', 'wss', 'file']
+  block:
+  - name: Assert uri tests
+    assert:
+      that:
+        - "'http://searchengine.tld' is uri"      # simple case, urls are uris but not all uris are urls
+        - "'ftp://searchengine.tld' is uri"       # other scheme
+        - "'file://etc/hosts' is uri"
+        - "'mailto://me@example.com' is uri"
+        - "'sftp://me@example.com' is uri"
+        - "'asldkfjhalsidfthjo' is uri" # junk can look like uri (either implied scheme or empty path)
+        - "'asldkfjhalsidfthjo' is not uri(special)" # validate against the schemes i know i need
+        - "'http://admin:secret@example.com' is uri"
+        - "'ftps://admin:secret@example.com' is uri"
+        - "'admin:secret@example.com' is uri" # scheme is implied
+        - "'http://admin:secret@example.com/myfile?parm=1&param=2' is uri"
+        - "'urn:isbn:9780307476463' is uri" # book ref
+
+  - name: Assert url tests
+    assert:
+      that:
+        - "'http://searchengine.tld' is url"      # simple case
+        - "'htp://searchengine.tld' is not url(special)"   # bad scheme for explicit expectations
+        - "'htp://searchengine.tld' is url"   # bad scheme, but valid if no explicit list
+        - "'ftp://searchengine.tld' is url"
+        - "'ftp://searchengine.tld' is url"
+        - "'ftp:// searchengine.tld' is url"
+        - "'file://etc/hosts' is url"
+        - "'mailto://me@example.com' is url"
+        - "'asldkfjhalsidfthjo' is not url" # junk
+        - "'http://admin:secret@example.com' is url"
+        - "'ftps://admin:secret@example.com' is url"
+        - "'admin:secret@example.com' is not url"
+        - "'http://admin:secret@example.com/myfile?parm=1&param=2' is url"
+        - "'urn:isbn:9780307476463' is not url" # book ref
+  - name: assert urn
+    assert:
+      that:
+        - "'urn:isbn:9780307476463' is urn" # book ref
+        - "'ftps://admin:secret@example.com' is not urn"
+        - "'admin:secret@example.com' is not urn"