antsibull-nox 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

antsibull_nox/sessions.py

@@ -10,16 +10,24 @@ Create nox sessions.
 
 from __future__ import annotations
 
+import json
 import os
 import shlex
 import subprocess
 import sys
 import typing as t
+from contextlib import contextmanager
 from dataclasses import asdict, dataclass
 from pathlib import Path
 
 import nox
 
+from .ansible import (
+    AnsibleCoreVersion,
+    get_ansible_core_info,
+    get_ansible_core_package_name,
+    get_supported_core_versions,
+)
 from .collection import (
     CollectionData,
     force_collection_version,
@@ -30,17 +38,21 @@ from .collection import (
 from .data_util import prepare_data_script
 from .paths import (
     copy_collection,
+    copy_directory_tree_into,
     create_temp_directory,
     filter_paths,
     find_data_directory,
     list_all_files,
     remove_path,
 )
+from .python import get_installed_python_versions
+from .utils import Version
 
 # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables
 # https://docs.gitlab.com/ci/variables/predefined_variables/#predefined-variables
 # https://docs.travis-ci.com/user/environment-variables/#default-environment-variables
 IN_CI = os.environ.get("CI") == "true"
+IN_GITHUB_ACTIONS = bool(os.environ.get("GITHUB_ACTION"))
 ALLOW_EDITABLE = os.environ.get("ALLOW_EDITABLE", str(not IN_CI)).lower() in (
     "1",
     "true",
@@ -60,6 +72,28 @@ MODULE_PATHS = [
     "tests/unit/plugins/module_utils/",
 ]
 
+_SESSIONS: dict[str, list[dict[str, t.Any]]] = {}
+
+
+@contextmanager
+def _ci_group(name: str) -> t.Iterator[None]:
+    """
+    Try to ensure that the output inside the context is printed in a collapsable group.
+
+    This is highly CI system dependent, and currently only works for GitHub Actions.
+    """
+    if IN_GITHUB_ACTIONS:
+        print(f"::group::{name}")
+    yield
+    if IN_GITHUB_ACTIONS:
+        print("::endgroup::")
+
+
+def _register(name: str, data: dict[str, t.Any]) -> None:
+    if name not in _SESSIONS:
+        _SESSIONS[name] = []
+    _SESSIONS[name].append(data)
+
 
 def install(session: nox.Session, *args: str, editable: bool = False, **kwargs):
     """
@@ -167,6 +201,7 @@ def prepare_collections(
         extra_deps_files=extra_deps_files,
         extra_collections=extra_collections,
         with_current=False,
+        global_cache_dir=session.cache_dir,
     )
     current_setup = setup_current_tree(place, setup.current_collection)
     return CollectionSetup(
@@ -179,26 +214,84 @@ def prepare_collections(
 
 
 def _run_bare_script(
-    session: nox.Session, /, name: str, *, extra_data: dict[str, t.Any] | None = None
+    session: nox.Session,
+    /,
+    name: str,
+    *,
+    use_session_python: bool = False,
+    files: list[Path] | None = None,
+    extra_data: dict[str, t.Any] | None = None,
 ) -> None:
-    files = list_all_files()
+    if files is None:
+        files = list_all_files()
     data = prepare_data_script(
         session,
         base_name=name,
         paths=files,
         extra_data=extra_data,
     )
+    python = sys.executable
+    env = {}
+    if use_session_python:
+        python = "python"
+        env["PYTHONPATH"] = str(find_data_directory())
     session.run(
-        sys.executable,
+        python,
         find_data_directory() / f"{name}.py",
         "--data",
         data,
         external=True,
+        env=env,
     )
 
 
+def _compose_description(
+    *,
+    prefix: str | dict[t.Literal["one", "other"], str] | None = None,
+    programs: dict[str, str | bool | None],
+) -> str:
+    parts: list[str] = []
+
+    def add(text: str, *, comma: bool = False) -> None:
+        if parts:
+            if comma:
+                parts.append(", ")
+            else:
+                parts.append(" ")
+        parts.append(text)
+
+    active_programs = [
+        (program, value if isinstance(value, str) else None)
+        for program, value in programs.items()
+        if value not in (False, None)
+    ]
+
+    if prefix:
+        if isinstance(prefix, dict):
+            if len(active_programs) == 1 and "one" in prefix:
+                add(prefix["one"])
+            else:
+                add(prefix["other"])
+        else:
+            add(prefix)
+
+    for index, (program, value) in enumerate(active_programs):
+        if index + 1 == len(active_programs) and index > 0:
+            add("and", comma=index > 1)
+        add(program, comma=index > 0 and index + 1 < len(active_programs))
+        if value is not None:
+            add(f"({value})")
+
+    return "".join(parts)
+
+
 def add_lint(
-    *, make_lint_default: bool, has_formatters: bool, has_codeqa: bool, has_typing: bool
+    *,
+    make_lint_default: bool,
+    has_formatters: bool,
+    has_codeqa: bool,
+    has_yamllint: bool,
+    has_typing: bool,
 ) -> None:
     """
     Add nox meta session for linting.
@@ -212,11 +305,28 @@ def add_lint(
         dependent_sessions.append("formatters")
     if has_codeqa:
         dependent_sessions.append("codeqa")
+    if has_yamllint:
+        dependent_sessions.append("yamllint")
     if has_typing:
         dependent_sessions.append("typing")
-    nox.session(  # type: ignore
-        lint, name="lint", default=make_lint_default, requires=dependent_sessions
+
+    lint.__doc__ = _compose_description(
+        prefix={
+            "one": "Meta session for triggering the following session:",
+            "other": "Meta session for triggering the following sessions:",
+        },
+        programs={
+            "formatters": has_formatters,
+            "codeqa": has_codeqa,
+            "yamllint": has_yamllint,
+            "typing": has_typing,
+        },
     )
+    nox.session(
+        name="lint",
+        default=make_lint_default,
+        requires=dependent_sessions,
+    )(lint)
 
 
 def add_formatters(
@@ -299,7 +409,17 @@ def add_formatters(
         if run_black or run_black_modules:
             execute_black(session)
 
-    nox.session(formatters, name="formatters", default=False)  # type: ignore
+    formatters.__doc__ = _compose_description(
+        prefix={
+            "one": "Run code formatter:",
+            "other": "Run code formatters:",
+        },
+        programs={
+            "isort": run_isort,
+            "black": run_black,
+        },
+    )
+    nox.session(name="formatters", default=False)(formatters)
 
 
 def add_codeqa(  # noqa: C901
@@ -412,7 +532,120 @@ def add_codeqa(  # noqa: C901
         if run_pylint and prepared_collections:
             execute_pylint(session, prepared_collections)
 
-    nox.session(codeqa, name="codeqa", default=False)  # type: ignore
+    codeqa.__doc__ = _compose_description(
+        prefix={
+            "other": "Run code QA:",
+        },
+        programs={
+            "flake8": run_flake8,
+            "pylint": run_pylint,
+        },
+    )
+    nox.session(name="codeqa", default=False)(codeqa)
+
+
+def add_yamllint(
+    *,
+    run_yamllint: bool,
+    yamllint_config: str | os.PathLike | None,
+    yamllint_config_plugins: str | os.PathLike | None,
+    yamllint_config_plugins_examples: str | os.PathLike | None,
+    yamllint_package: str,
+) -> None:
+    """
+    Add yamllint session for linting YAML files and plugin/module docs.
+    """
+
+    def compose_dependencies() -> list[str]:
+        deps = []
+        if run_yamllint:
+            deps.append(yamllint_package)
+        return deps
+
+    def to_str(config: str | os.PathLike | None) -> str | None:
+        return str(config) if config else None
+
+    def execute_yamllint(session: nox.Session) -> None:
+        # Run yamllint
+        all_files = list_all_files()
+        cwd = Path.cwd()
+        all_yaml_filenames = [
+            str(file.relative_to(cwd))
+            for file in all_files
+            if file.name.lower().endswith((".yml", ".yaml"))
+        ]
+        if not all_yaml_filenames:
+            session.warn("Skipping yamllint since no YAML file was found...")
+            return
+
+        command = ["yamllint"]
+        if yamllint_config is not None:
+            command.extend(
+                [
+                    "-c",
+                    str(yamllint_config),
+                ]
+            )
+        command.append("--strict")
+        command.append("--")
+        command.extend(all_yaml_filenames)
+        command.extend(session.posargs)
+        session.run(*command)
+
+    def execute_plugin_yamllint(session: nox.Session) -> None:
+        # Run yamllint
+        all_files = list_all_files()
+        cwd = Path.cwd()
+        plugins_dir = cwd / "plugins"
+        ignore_dirs = [
+            plugins_dir / "action",
+            plugins_dir / "module_utils",
+            plugins_dir / "plugin_utils",
+        ]
+        all_plugin_files = [
+            file
+            for file in all_files
+            if file.is_relative_to(plugins_dir)
+            and file.name.lower().endswith((".py", ".yml", ".yaml"))
+            and not any(file.is_relative_to(dir) for dir in ignore_dirs)
+        ]
+        if not all_plugin_files:
+            session.warn(
+                "Skipping yamllint for modules/plugins since"
+                " no appropriate Python file was found..."
+            )
+            return
+        _run_bare_script(
+            session,
+            "plugin-yamllint",
+            use_session_python=True,
+            files=all_plugin_files,
+            extra_data={
+                "config": to_str(yamllint_config_plugins or yamllint_config),
+                "config_examples": to_str(
+                    yamllint_config_plugins_examples
+                    or yamllint_config_plugins
+                    or yamllint_config
+                ),
+            },
+        )
+
+    def yamllint(session: nox.Session) -> None:
+        install(session, *compose_dependencies())
+        if run_yamllint:
+            execute_yamllint(session)
+            execute_plugin_yamllint(session)
+
+    yamllint.__doc__ = _compose_description(
+        prefix={
+            "one": "Run YAML checker:",
+            "other": "Run YAML checkers:",
+        },
+        programs={
+            "yamllint": run_yamllint,
+        },
+    )
+    nox.session(name="yamllint", default=False)(yamllint)
 
 
 def add_typing(
@@ -479,7 +712,16 @@ def add_typing(
         if run_mypy and prepared_collections:
             execute_mypy(session, prepared_collections)
 
-    nox.session(typing, name="typing", default=False)  # type: ignore
+    typing.__doc__ = _compose_description(
+        prefix={
+            "one": "Run type checker:",
+            "other": "Run type checkers:",
+        },
+        programs={
+            "mypy": run_mypy,
+        },
+    )
+    nox.session(name="typing", default=False)(typing)
 
 
 def add_lint_sessions(
@@ -506,6 +748,12 @@ def add_lint_sessions(
     pylint_package: str = "pylint",
     pylint_ansible_core_package: str | None = "ansible-core",
     pylint_extra_deps: list[str] | None = None,
+    # yamllint:
+    run_yamllint: bool = False,
+    yamllint_config: str | os.PathLike | None = None,
+    yamllint_config_plugins: str | os.PathLike | None = None,
+    yamllint_config_plugins_examples: str | os.PathLike | None = None,
+    yamllint_package: str = "yamllint",
     # mypy:
     run_mypy: bool = True,
     mypy_config: str | os.PathLike | None = None,
@@ -518,11 +766,13 @@ def add_lint_sessions(
     """
     has_formatters = run_isort or run_black or run_black_modules or False
     has_codeqa = run_flake8 or run_pylint
+    has_yamllint = run_yamllint
     has_typing = run_mypy
 
     add_lint(
         has_formatters=has_formatters,
         has_codeqa=has_codeqa,
+        has_yamllint=has_yamllint,
         has_typing=has_typing,
         make_lint_default=make_lint_default,
     )
@@ -553,6 +803,15 @@ def add_lint_sessions(
             pylint_extra_deps=pylint_extra_deps or [],
         )
 
+    if has_yamllint:
+        add_yamllint(
+            run_yamllint=run_yamllint,
+            yamllint_config=yamllint_config,
+            yamllint_config_plugins=yamllint_config_plugins,
+            yamllint_config_plugins_examples=yamllint_config_plugins_examples,
+            yamllint_package=yamllint_package,
+        )
+
     if has_typing:
         add_typing(
             extra_code_files=extra_code_files or [],
@@ -571,7 +830,7 @@ def add_docs_check(
     ansible_core_package: str = "ansible-core",
     validate_collection_refs: t.Literal["self", "dependent", "all"] | None = None,
     extra_collections: list[str] | None = None,
-):
+) -> None:
     """
     Add docs-check session for linting.
     """
@@ -609,9 +868,11 @@ def add_docs_check(
         if prepared_collections:
             execute_antsibull_docs(session, prepared_collections)
 
-    nox.session(  # type: ignore
-        docs_check, name="docs-check", default=make_docs_check_default
-    )
+    docs_check.__doc__ = "Run 'antsibull-docs lint-collection-docs'"
+    nox.session(
+        name="docs-check",
+        default=make_docs_check_default,
+    )(docs_check)
 
 
 def add_license_check(
@@ -621,7 +882,7 @@ def add_license_check(
     reuse_package: str = "reuse",
     run_license_check: bool = True,
     license_check_extra_ignore_paths: list[str] | None = None,
-):
+) -> None:
     """
     Add license-check session for license checks.
     """
@@ -645,9 +906,22 @@ def add_license_check(
                 },
             )
 
-    nox.session(  # type: ignore
-        license_check, name="license-check", default=make_license_check_default
+    license_check.__doc__ = _compose_description(
+        prefix={
+            "one": "Run license checker:",
+            "other": "Run license checkers:",
+        },
+        programs={
+            "reuse": run_reuse,
+            "license-check": (
+                "ensure GPLv3+ for plugins" if run_license_check else False
+            ),
+        },
     )
+    nox.session(
+        name="license-check",
+        default=make_license_check_default,
+    )(license_check)
 
 
 @dataclass
@@ -688,7 +962,7 @@ def add_extra_checks(
     # action-groups:
     run_action_groups: bool = False,
     action_groups_config: list[ActionGroup] | None = None,
-):
+) -> None:
     """
     Add extra-checks session for extra checks.
     """
@@ -730,12 +1004,25 @@ def add_extra_checks(
         if run_action_groups:
             execute_action_groups(session)
 
-    nox.session(  # type: ignore
-        extra_checks,
+    extra_checks.__doc__ = _compose_description(
+        prefix={
+            "one": "Run extra checker:",
+            "other": "Run extra checkers:",
+        },
+        programs={
+            "no-unwanted-files": (
+                "checks for unwanted files in plugins/"
+                if run_no_unwanted_files
+                else False
+            ),
+            "action-groups": "validate action groups" if run_action_groups else False,
+        },
+    )
+    nox.session(
         name="extra-checks",
         python=False,
         default=make_extra_checks_default,
-    )
+    )(extra_checks)
 
 
 def add_build_import_check(
@@ -745,9 +1032,9 @@ def add_build_import_check(
     run_galaxy_importer: bool = True,
     galaxy_importer_package: str = "galaxy-importer",
     galaxy_importer_config_path: (
-        str | None
+        str | os.PathLike | None
     ) = None,  # https://github.com/ansible/galaxy-importer#configuration
-):
+) -> None:
     """
     Add license-check session for license checks.
     """
@@ -793,7 +1080,7 @@ def add_build_import_check(
             env = {}
             if galaxy_importer_config_path:
                 env["GALAXY_IMPORTER_CONFIG"] = str(
-                    Path.cwd() / galaxy_importer_config_path
+                    Path(galaxy_importer_config_path).absolute()
                 )
             with session.chdir(collection_dir):
                 import_log = (
@@ -808,7 +1095,8 @@ def add_build_import_check(
                     or ""
                 )
             if import_log:
-                print(import_log)
+                with _ci_group("Run Galaxy importer"):
+                    print(import_log)
                 error_prefix = "ERROR:"
                 errors = []
                 for line in import_log.splitlines():
@@ -821,13 +1109,589 @@ def add_build_import_check(
                         f" error{'' if len(errors) == 1 else 's'}:\n{messages}"
                     )
 
-    nox.session(  # type: ignore
-        build_import_check,
+    build_import_check.__doc__ = _compose_description(
+        prefix={
+            "one": "Run build and import checker:",
+            "other": "Run build and import checkers:",
+        },
+        programs={
+            "build-collection": True,
+            "galaxy-importer": (
+                "test whether Galaxy will import built collection"
+                if run_galaxy_importer
+                else False
+            ),
+        },
+    )
+    nox.session(
         name="build-import-check",
         default=make_build_import_check_default,
+    )(build_import_check)
+
+
+def _parse_ansible_core_version(
+    version: str | AnsibleCoreVersion,
+) -> AnsibleCoreVersion:
+    if version in ("devel", "milestone"):
+        # For some reason mypy doesn't notice that
+        return t.cast(AnsibleCoreVersion, version)
+    if isinstance(version, Version):
+        return version
+    return Version.parse(version)
+
+
+def add_ansible_test_session(
+    *,
+    name: str,
+    description: str | None,
+    extra_deps_files: list[str | os.PathLike] | None = None,
+    ansible_test_params: list[str],
+    add_posargs: bool = True,
+    default: bool,
+    ansible_core_version: str | AnsibleCoreVersion,
+    ansible_core_source: t.Literal["git", "pypi"] = "git",
+    ansible_core_repo_name: str | None = None,
+    ansible_core_branch_name: str | None = None,
+    handle_coverage: t.Literal["never", "always", "auto"] = "auto",
+    register_name: str | None = None,
+    register_extra_data: dict[str, t.Any] | None = None,
+) -> None:
+    """
+    Add generic ansible-test session.
+
+    Returns a list of Python versions set for this session.
+    """
+    parsed_ansible_core_version = _parse_ansible_core_version(ansible_core_version)
+
+    def compose_dependencies() -> list[str]:
+        deps = [
+            get_ansible_core_package_name(
+                parsed_ansible_core_version,
+                source=ansible_core_source,
+                ansible_repo=ansible_core_repo_name,
+                branch_name=ansible_core_branch_name,
+            )
+        ]
+        return deps
+
+    def run_ansible_test(session: nox.Session) -> None:
+        install(session, *compose_dependencies())
+        prepared_collections = prepare_collections(
+            session,
+            install_in_site_packages=False,
+            extra_deps_files=extra_deps_files,
+            install_out_of_tree=True,
+        )
+        if not prepared_collections:
+            session.warn("Skipping ansible-test...")
+            return
+        cwd = Path.cwd()
+        with session.chdir(prepared_collections.current_path):
+            command = ["ansible-test"] + ansible_test_params
+            if add_posargs and session.posargs:
+                command.extend(session.posargs)
+            session.run(*command)
+
+            coverage = (handle_coverage == "auto" and "--coverage" in command) or (
+                handle_coverage == "always"
+            )
+            if coverage:
+                session.run(
+                    "ansible-test",
+                    "coverage",
+                    "xml",
+                    "--color",
+                    "-v",
+                    "--requirements",
+                    "--group-by",
+                    "command",
+                    "--group-by",
+                    "version",
+                )
+
+            copy_directory_tree_into(
+                prepared_collections.current_path / "tests" / "output",
+                cwd / "tests" / "output",
+            )
+
+    # Determine Python version(s)
+    core_info = get_ansible_core_info(parsed_ansible_core_version)
+    all_versions = get_installed_python_versions()
+
+    installed_versions = [
+        version
+        for version in core_info.controller_python_versions
+        if version in all_versions
+    ]
+    python = max(installed_versions or core_info.controller_python_versions)
+    python_versions = [python]
+
+    run_ansible_test.__doc__ = description
+    nox.session(
+        name=name,
+        default=default,
+        python=[str(python_version) for python_version in python_versions],
+    )(run_ansible_test)
+
+    if register_name:
+        data = {
+            "name": name,
+            "ansible-core": (
+                str(ansible_core_branch_name)
+                if ansible_core_branch_name is not None
+                else str(parsed_ansible_core_version)
+            ),
+            "python": " ".join(str(python) for python in python_versions),
+        }
+        if register_extra_data:
+            data.update(register_extra_data)
+        _register(register_name, data)
+
+
+def add_ansible_test_sanity_test_session(
+    *,
+    name: str,
+    description: str | None,
+    default: bool,
+    ansible_core_version: str | AnsibleCoreVersion,
+    ansible_core_source: t.Literal["git", "pypi"] = "git",
+    ansible_core_repo_name: str | None = None,
+    ansible_core_branch_name: str | None = None,
+) -> None:
+    """
+    Add generic ansible-test sanity test session.
+    """
+    add_ansible_test_session(
+        name=name,
+        description=description,
+        ansible_test_params=["sanity", "--docker", "-v", "--color"],
+        default=default,
+        ansible_core_version=ansible_core_version,
+        ansible_core_source=ansible_core_source,
+        ansible_core_repo_name=ansible_core_repo_name,
+        ansible_core_branch_name=ansible_core_branch_name,
+        register_name="sanity",
     )
 
 
+def _parse_min_max_except(
+    min_version: Version | str | None,
+    max_version: Version | str | None,
+    except_versions: list[AnsibleCoreVersion | str] | None,
+) -> tuple[Version | None, Version | None, tuple[AnsibleCoreVersion, ...] | None]:
+    if isinstance(min_version, str):
+        min_version = Version.parse(min_version)
+    if isinstance(max_version, str):
+        max_version = Version.parse(max_version)
+    if except_versions is None:
+        return min_version, max_version, None
+    evs = tuple(_parse_ansible_core_version(version) for version in except_versions)
+    return min_version, max_version, evs
+
+
+def add_all_ansible_test_sanity_test_sessions(
+    *,
+    default: bool = False,
+    include_devel: bool = False,
+    include_milestone: bool = False,
+    add_devel_like_branches: list[tuple[str | None, str]] | None = None,
+    min_version: Version | str | None = None,
+    max_version: Version | str | None = None,
+    except_versions: list[AnsibleCoreVersion | str] | None = None,
+) -> None:
+    """
+    Add ansible-test sanity test meta session that runs ansible-test sanity
+    for all supported ansible-core versions.
+    """
+    parsed_min_version, parsed_max_version, parsed_except_versions = (
+        _parse_min_max_except(min_version, max_version, except_versions)
+    )
+
+    sanity_sessions = []
+    for ansible_core_version in get_supported_core_versions(
+        include_devel=include_devel,
+        include_milestone=include_milestone,
+        min_version=parsed_min_version,
+        max_version=parsed_max_version,
+        except_versions=parsed_except_versions,
+    ):
+        name = f"ansible-test-sanity-{ansible_core_version}"
+        add_ansible_test_sanity_test_session(
+            name=name,
+            description=f"Run sanity tests from ansible-core {ansible_core_version}'s ansible-test",
+            ansible_core_version=ansible_core_version,
+            default=False,
+        )
+        sanity_sessions.append(name)
+    if add_devel_like_branches:
+        for repo_name, branch_name in add_devel_like_branches:
+            repo_prefix = (
+                f"{repo_name.replace('/', '-')}-" if repo_name is not None else ""
+            )
+            repo_postfix = f", {repo_name} repository" if repo_name is not None else ""
+            name = f"ansible-test-sanity-{repo_prefix}{branch_name.replace('/', '-')}"
+            add_ansible_test_sanity_test_session(
+                name=name,
+                description=(
+                    "Run sanity tests from ansible-test in ansible-core's"
+                    f" {branch_name} branch{repo_postfix}"
+                ),
+                ansible_core_version="devel",
+                ansible_core_repo_name=repo_name,
+                ansible_core_branch_name=branch_name,
+                default=False,
+            )
+            sanity_sessions.append(name)
+
+    def run_all_sanity_tests(
+        session: nox.Session,  # pylint: disable=unused-argument
+    ) -> None:
+        pass
+
+    run_all_sanity_tests.__doc__ = (
+        "Meta session for running all ansible-test-sanity-* sessions."
+    )
+    nox.session(
+        name="ansible-test-sanity",
+        default=default,
+        requires=sanity_sessions,
+    )(run_all_sanity_tests)
+
+
+def add_ansible_test_unit_test_session(
+    *,
+    name: str,
+    description: str | None,
+    default: bool,
+    ansible_core_version: str | AnsibleCoreVersion,
+    ansible_core_source: t.Literal["git", "pypi"] = "git",
+    ansible_core_repo_name: str | None = None,
+    ansible_core_branch_name: str | None = None,
+) -> None:
+    """
+    Add generic ansible-test unit test session.
+    """
+    add_ansible_test_session(
+        name=name,
+        description=description,
+        ansible_test_params=["units", "--docker", "-v", "--color"],
+        extra_deps_files=["tests/unit/requirements.yml"],
+        default=default,
+        ansible_core_version=ansible_core_version,
+        ansible_core_source=ansible_core_source,
+        ansible_core_repo_name=ansible_core_repo_name,
+        ansible_core_branch_name=ansible_core_branch_name,
+        register_name="units",
+    )
+
+
+def add_all_ansible_test_unit_test_sessions(
+    *,
+    default: bool = False,
+    include_devel: bool = False,
+    include_milestone: bool = False,
+    add_devel_like_branches: list[tuple[str | None, str]] | None = None,
+    min_version: Version | str | None = None,
+    max_version: Version | str | None = None,
+    except_versions: list[AnsibleCoreVersion | str] | None = None,
+) -> None:
+    """
+    Add ansible-test unit test meta session that runs ansible-test units
+    for all supported ansible-core versions.
+    """
+    parsed_min_version, parsed_max_version, parsed_except_versions = (
+        _parse_min_max_except(min_version, max_version, except_versions)
+    )
+
+    units_sessions = []
+    for ansible_core_version in get_supported_core_versions(
+        include_devel=include_devel,
+        include_milestone=include_milestone,
+        min_version=parsed_min_version,
+        max_version=parsed_max_version,
+        except_versions=parsed_except_versions,
+    ):
+        name = f"ansible-test-units-{ansible_core_version}"
+        add_ansible_test_unit_test_session(
+            name=name,
+            description=f"Run unit tests with ansible-core {ansible_core_version}'s ansible-test",
+            ansible_core_version=ansible_core_version,
+            default=False,
+        )
+        units_sessions.append(name)
+    if add_devel_like_branches:
+        for repo_name, branch_name in add_devel_like_branches:
+            repo_prefix = (
+                f"{repo_name.replace('/', '-')}-" if repo_name is not None else ""
+            )
+            repo_postfix = f", {repo_name} repository" if repo_name is not None else ""
+            name = f"ansible-test-units-{repo_prefix}{branch_name.replace('/', '-')}"
+            add_ansible_test_unit_test_session(
+                name=name,
+                description=(
+                    "Run unit tests from ansible-test in ansible-core's"
+                    f" {branch_name} branch{repo_postfix}"
+                ),
+                ansible_core_version="devel",
+                ansible_core_repo_name=repo_name,
+                ansible_core_branch_name=branch_name,
+                default=False,
+            )
+            units_sessions.append(name)
+
+    def run_all_unit_tests(
+        session: nox.Session,  # pylint: disable=unused-argument
+    ) -> None:
+        pass
+
+    run_all_unit_tests.__doc__ = (
+        "Meta session for running all ansible-test-units-* sessions."
+    )
+    nox.session(
+        name="ansible-test-units",
+        default=default,
+        requires=units_sessions,
+    )(run_all_unit_tests)
+
+
+def add_ansible_test_integration_sessions_default_container(
+    *,
+    include_devel: bool = False,
+    include_milestone: bool = False,
+    add_devel_like_branches: list[tuple[str | None, str]] | None = None,
+    min_version: Version | str | None = None,
+    max_version: Version | str | None = None,
+    except_versions: list[AnsibleCoreVersion | str] | None = None,
+    core_python_versions: (
+        dict[str | AnsibleCoreVersion, list[str | Version]] | None
+    ) = None,
+    controller_python_versions_only: bool = False,
+    default: bool = False,
+) -> None:
+    """
+    Add ansible-test integration tests using the default Docker container.
+
+    ``core_python_versions`` can be used to restrict the Python versions
+    to be used for a specific ansible-core version.
+
+    ``controller_python_versions_only`` can be used to only run against
+    controller Python versions.
+    """
+
+    def add_integration_tests(
+        ansible_core_version: AnsibleCoreVersion,
+        repo_name: str | None = None,
+        branch_name: str | None = None,
+    ) -> list[str]:
+        # Determine Python versions to run tests for
+        py_versions = (
+            (core_python_versions.get(branch_name) if branch_name is not None else None)
+            or core_python_versions.get(ansible_core_version)
+            or core_python_versions.get(str(ansible_core_version))
+            if core_python_versions
+            else None
+        )
+        if py_versions is None:
+            core_info = get_ansible_core_info(ansible_core_version)
+            py_versions = list(
+                core_info.controller_python_versions
+                if controller_python_versions_only
+                else core_info.remote_python_versions
+            )
+
+        # Add sessions
+        integration_sessions_core: list[str] = []
+        if branch_name is None:
+            base_name = f"ansible-test-integration-{ansible_core_version}-"
+        else:
+            repo_prefix = (
+                f"{repo_name.replace('/', '-')}-" if repo_name is not None else ""
+            )
+            base_name = f"ansible-test-integration-{repo_prefix}{branch_name.replace('/', '-')}-"
+        for py_version in py_versions:
+            name = f"{base_name}{py_version}"
+            if branch_name is None:
+                description = (
+                    f"Run integration tests from ansible-core {ansible_core_version}'s"
+                    f" ansible-test with Python {py_version}"
+                )
+            else:
+                repo_postfix = (
+                    f", {repo_name} repository" if repo_name is not None else ""
+                )
+                description = (
+                    f"Run integration tests from ansible-test in ansible-core's {branch_name}"
+                    f" branch{repo_postfix} with Python {py_version}"
+                )
+            add_ansible_test_session(
+                name=name,
+                description=description,
+                ansible_test_params=[
+                    "integration",
+                    "--docker",
+                    "default",
+                    "-v",
+                    "--color",
+                    "--python",
+                    str(py_version),
+                ],
+                extra_deps_files=["tests/integration/requirements.yml"],
+                ansible_core_version=ansible_core_version,
+                ansible_core_repo_name=repo_name,
+                ansible_core_branch_name=branch_name,
+                default=False,
+                register_name="integration",
+                register_extra_data={
+                    "test-container": "default",
+                    "test-python": str(py_version),
+                },
+            )
+            integration_sessions_core.append(name)
+        return integration_sessions_core
+
+    parsed_min_version, parsed_max_version, parsed_except_versions = (
+        _parse_min_max_except(min_version, max_version, except_versions)
+    )
+    integration_sessions: list[str] = []
+    for ansible_core_version in get_supported_core_versions(
+        include_devel=include_devel,
+        include_milestone=include_milestone,
+        min_version=parsed_min_version,
+        max_version=parsed_max_version,
+        except_versions=parsed_except_versions,
+    ):
+        integration_sessions_core = add_integration_tests(ansible_core_version)
+        if integration_sessions_core:
+            name = f"ansible-test-integration-{ansible_core_version}"
+            integration_sessions.append(name)
+
+            def run_integration_tests(
+                session: nox.Session,  # pylint: disable=unused-argument
+            ) -> None:
+                pass
+
+            run_integration_tests.__doc__ = (
+                f"Meta session for running all {name}-* sessions."
+            )
+            nox.session(
+                name=name,
+                requires=integration_sessions_core,
+                default=False,
+            )(run_integration_tests)
+    if add_devel_like_branches:
+        for repo_name, branch_name in add_devel_like_branches:
+            integration_sessions_core = add_integration_tests(
+                "devel", repo_name=repo_name, branch_name=branch_name
+            )
+            if integration_sessions_core:
+                repo_prefix = (
+                    f"{repo_name.replace('/', '-')}-" if repo_name is not None else ""
+                )
+                name = f"ansible-test-integration-{repo_prefix}{branch_name.replace('/', '-')}"
+                integration_sessions.append(name)
+
+                def run_integration_tests_for_branch(
+                    session: nox.Session,  # pylint: disable=unused-argument
+                ) -> None:
+                    pass
+
+                run_integration_tests_for_branch.__doc__ = (
+                    f"Meta session for running all {name}-* sessions."
+                )
+                nox.session(
+                    name=name,
+                    requires=integration_sessions_core,
+                    default=False,
+                )(run_integration_tests_for_branch)
+
+    def ansible_test_integration(
+        session: nox.Session,  # pylint: disable=unused-argument
+    ) -> None:
+        pass
+
+    ansible_test_integration.__doc__ = (
+        "Meta session for running all ansible-test-integration-* sessions."
+    )
+    nox.session(
+        name="ansible-test-integration",
+        requires=integration_sessions,
+        default=default,
+    )(ansible_test_integration)
+
+
+def add_ansible_lint(
+    *,
+    make_ansible_lint_default: bool = True,
+    ansible_lint_package: str = "ansible-lint",
+    strict: bool = False,
+) -> None:
+    """
+    Add a session that runs ansible-lint.
+    """
+
+    def compose_dependencies() -> list[str]:
+        return [ansible_lint_package]
+
+    def ansible_lint(session: nox.Session) -> None:
+        install(session, *compose_dependencies())
+        prepared_collections = prepare_collections(
+            session,
+            install_in_site_packages=False,
+            install_out_of_tree=True,
+            extra_deps_files=["tests/integration/requirements.yml"],
+        )
+        if not prepared_collections:
+            session.warn("Skipping ansible-lint...")
+            return
+        env = {"ANSIBLE_COLLECTIONS_PATH": f"{prepared_collections.current_place}"}
+        command = ["ansible-lint", "--offline"]
+        if strict:
+            command.append("--strict")
+        session.run(*command, env=env)
+
+    ansible_lint.__doc__ = "Run ansible-lint."
+    nox.session(
+        name="ansible-lint",
+        default=make_ansible_lint_default,
+    )(ansible_lint)
+
+
+def add_matrix_generator() -> None:
+    """
+    Add a session that generates matrixes for CI systems.
+    """
+
+    def matrix_generator(
+        session: nox.Session,  # pylint: disable=unused-argument
+    ) -> None:
+        json_output = os.environ.get("ANTSIBULL_NOX_MATRIX_JSON")
+        if json_output:
+            print(f"Writing JSON output to {json_output}...")
+            with open(json_output, "wt", encoding="utf-8") as f:
+                f.write(json.dumps(_SESSIONS))
+
+        github_output = os.environ.get("GITHUB_OUTPUT")
+        if github_output:
+            print(f"Writing GitHub output to {github_output}...")
+            with open(github_output, "at", encoding="utf-8") as f:
+                for name, sessions in _SESSIONS.items():
+                    f.write(f"{name}={json.dumps(sessions)}\n")
+
+        for name, sessions in sorted(_SESSIONS.items()):
+            print(f"{name} ({len(sessions)}):")
+            for session_data in sessions:
+                data = session_data.copy()
+                session_name = data.pop("name")
+                print(f"  {session_name}: {data}")
+
+    matrix_generator.__doc__ = "Generate matrix for CI systems."
+    nox.session(
+        name="matrix-generator",
+        python=False,
+        default=False,
+    )(matrix_generator)
+
+
 __all__ = [
     "ActionGroup",
     "add_build_import_check",
@@ -835,6 +1699,14 @@ __all__ = [
     "add_extra_checks",
     "add_license_check",
     "add_lint_sessions",
+    "add_ansible_test_session",
+    "add_ansible_test_sanity_test_session",
+    "add_all_ansible_test_sanity_test_sessions",
+    "add_ansible_test_unit_test_session",
+    "add_all_ansible_test_unit_test_sessions",
+    "add_ansible_test_integration_sessions_default_container",
+    "add_ansible_lint",
+    "add_matrix_generator",
     "install",
     "prepare_collections",
 ]