[stable-2.14] ansible-test - Fix and update documentation links.

(cherry picked from commit 938c0fa)

Co-authored-by: Matt Clay <matt@mystile.com>

changelogs/fragments/ansible-test-docs-links.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - ansible-test - Fix broken documentation link for ``aws`` test plugin error messages.
+minor_changes:
+  - ansible-test - Improve consistency of version specific documentation links.

test/lib/ansible_test/_internal/commands/integration/cloud/aws.py

@@ -127,5 +127,5 @@ def on_failure(self, target: IntegrationTarget, tries: int) -> None:
         """Callback to run when an integration target fails."""
         if not tries and self.managed:
             display.notice('If %s failed due to permissions, the IAM test policy may need to be updated. '
-                           'https://docs.ansible.com/ansible-core/devel/dev_guide/platforms/aws_guidelines.html#aws-permissions-for-integration-tests.'
+                           'https://docs.ansible.com/ansible/devel/collections/amazon/aws/docsite/dev_guidelines.html#aws-permissions-for-integration-tests'
                            % target.name)

test/lib/ansible_test/_internal/commands/sanity/integration_aliases.py

@@ -49,6 +49,7 @@
 )
 
 from ...util_common import (
+    get_docs_url,
     write_json_test_results,
     ResultType,
 )
@@ -67,7 +68,7 @@ class IntegrationAliasesTest(SanitySingleVersion):
     UNSTABLE = 'unstable/'
     UNSUPPORTED = 'unsupported/'
 
-    EXPLAIN_URL = 'https://docs.ansible.com/ansible-core/devel/dev_guide/testing/sanity/integration-aliases.html'
+    EXPLAIN_URL = get_docs_url('https://docs.ansible.com/ansible-core/devel/dev_guide/testing/sanity/integration-aliases.html')
 
     TEMPLATE_DISABLED = """
     The following integration tests are **disabled** [[explain]({explain_url}#disabled)]:

test/lib/ansible_test/_internal/test.py

@@ -3,15 +3,14 @@
 
 import collections.abc as c
 import datetime
-import re
 import typing as t
 
 from .util import (
     display,
-    get_ansible_version,
 )
 
 from .util_common import (
+    get_docs_url,
     write_text_test_results,
     write_json_test_results,
     ResultType,
@@ -341,19 +340,8 @@ def find_docs(self):
         if self.command != 'sanity':
             return None  # only sanity tests have docs links
 
-        # Use the major.minor version for the URL only if this a release that
-        # matches the pattern 2.4.0, otherwise, use 'devel'
-        ansible_version = get_ansible_version()
-        url_version = 'devel'
-        if re.search(r'^[0-9.]+$', ansible_version):
-            url_version = '.'.join(ansible_version.split('.')[:2])
-
-        testing_docs_url = 'https://docs.ansible.com/ansible-core/%s/dev_guide/testing' % url_version
-
-        url = '%s/%s/' % (testing_docs_url, self.command)
-
-        if self.test:
-            url += '%s.html' % self.test
+        filename = f'{self.test}.html' if self.test else ''
+        url = get_docs_url(f'https://docs.ansible.com/ansible-core/devel/dev_guide/testing/{self.command}/{filename}')
 
         return url
 

test/lib/ansible_test/_internal/util_common.py

@@ -24,6 +24,7 @@
 from .util import (
     cache,
     display,
+    get_ansible_version,
     remove_tree,
     MODE_DIRECTORY,
     MODE_FILE_EXECUTE,
@@ -151,6 +152,31 @@ def get_ansible_config(self) -> str:
         return os.path.join(ANSIBLE_TEST_DATA_ROOT, 'ansible.cfg')
 
 
+def get_docs_url(url: str) -> str:
+    """
+    Return the given docs.ansible.com URL updated to match the running ansible-test version, if it is not a pre-release version.
+    The URL should be in the form: https://docs.ansible.com/ansible/devel/path/to/doc.html
+    Where 'devel' will be replaced with the current version, unless it is a pre-release version.
+    When run under a pre-release version, the URL will remain unchanged.
+    This serves to provide a fallback URL for pre-release versions.
+    It also makes searching the source for docs links easier, since a full URL is provided to this function.
+    """
+    url_prefix = 'https://docs.ansible.com/ansible-core/devel/'
+
+    if not url.startswith(url_prefix):
+        raise ValueError(f'URL "{url}" does not start with: {url_prefix}')
+
+    ansible_version = get_ansible_version()
+
+    if re.search(r'^[0-9.]+$', ansible_version):
+        url_version = '.'.join(ansible_version.split('.')[:2])
+        new_prefix = f'https://docs.ansible.com/ansible-core/{url_version}/'
+
+        url = url.replace(url_prefix, new_prefix)
+
+    return url
+
+
 def create_result_directories(args: CommonConfig) -> None:
     """Create result directories."""
     if args.explain: