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

(cherry picked from commit 938c0fa944cabdc1a21745abade7f05ac3e6ee26)

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

5 files changed, 36 insertions, 17 deletions

diff --git a/changelogs/fragments/ansible-test-docs-links.yml b/changelogs/fragments/ansible-test-docs-links.yml
new file mode 100644
index 0000000000..6941788042
--- /dev/null
+++ b/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.
diff --git a/test/lib/ansible_test/_internal/commands/integration/cloud/aws.py b/test/lib/ansible_test/_internal/commands/integration/cloud/aws.py
index a34d714dd2..94e60667c3 100644
--- a/test/lib/ansible_test/_internal/commands/integration/cloud/aws.py
+++ b/test/lib/ansible_test/_internal/commands/integration/cloud/aws.py
@@ -127,5 +127,5 @@ class AwsCloudEnvironment(CloudEnvironment):
         """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)
diff --git a/test/lib/ansible_test/_internal/commands/sanity/integration_aliases.py b/test/lib/ansible_test/_internal/commands/sanity/integration_aliases.py
index 6d29968bf8..3ff9895988 100644
--- a/test/lib/ansible_test/_internal/commands/sanity/integration_aliases.py
+++ b/test/lib/ansible_test/_internal/commands/sanity/integration_aliases.py
@@ -46,6 +46,7 @@ from ...util import (
 )
 
 from ...util_common import (
+    get_docs_url,
     write_json_test_results,
     ResultType,
 )
@@ -64,7 +65,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)]:
diff --git a/test/lib/ansible_test/_internal/test.py b/test/lib/ansible_test/_internal/test.py
index b67addc3ec..2ebda60eaf 100644
--- a/test/lib/ansible_test/_internal/test.py
+++ b/test/lib/ansible_test/_internal/test.py
@@ -2,15 +2,14 @@
 from __future__ import annotations
 
 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,
@@ -340,19 +339,8 @@ class TestFailure(TestResult):
         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
 
diff --git a/test/lib/ansible_test/_internal/util_common.py b/test/lib/ansible_test/_internal/util_common.py
index b4d42420b9..f77040b170 100644
--- a/test/lib/ansible_test/_internal/util_common.py
+++ b/test/lib/ansible_test/_internal/util_common.py
@@ -23,6 +23,7 @@ from .encoding import (
 from .util import (
     cache,
     display,
+    get_ansible_version,
     remove_tree,
     MODE_DIRECTORY,
     MODE_FILE_EXECUTE,
@@ -146,6 +147,31 @@ class CommonConfig:
         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):  # type: (CommonConfig) -> None
     """Create result directories."""
     if args.explain: