feat(toolchain): Python testing toolchain

Inspired by https://github.com/trybka/scraps/blob/master/cc_test.md

This PR extends Test Runner enviroment to provide a coveragerc
enviroment variable COVERAGE_RC, allowing user to provide
coverage resource in what ever format

Author: ewianda

examples/bzlmod/.coveragerc

@@ -0,0 +1,6 @@
+[report]
+include_namespace_packages=True
+skip_covered=True
+[run]
+relative_files=True
+branch=True

examples/bzlmod/BUILD.bazel

@@ -13,6 +13,8 @@ load("@rules_python//python:py_binary.bzl", "py_binary")
 load("@rules_python//python:py_library.bzl", "py_library")
 load("@rules_python//python:py_test.bzl", "py_test")
 
+exports_files([".coveragerc"])
+
 # This stanza calls a rule that generates targets for managing pip dependencies
 # with pip-compile for a particular python version.
 compile_pip_requirements_3_10(

examples/bzlmod/MODULE.bazel

@@ -104,6 +104,14 @@ python.single_version_platform_override(
 # rules based on the `python_version` arg values.
 use_repo(python, "python_3_10", "python_3_9", "python_versions", "pythons_hub")
 
+python_test = use_extension("@rules_python//python/extensions:python_test.bzl", "python_test")
+python_test.configure(
+    coveragerc = ".coveragerc",
+)
+use_repo(python_test, "py_test_toolchain")
+
+register_toolchains("@py_test_toolchain//:all")
+
 # EXPERIMENTAL: This is experimental and may be removed without notice
 uv = use_extension("@rules_python//python/uv:extensions.bzl", "uv")
 uv.toolchain(uv_version = "0.4.25")

examples/bzlmod/tests/BUILD.bazel

@@ -49,11 +49,9 @@ py_test(
 )
 
 py_test(
-    name = "my_lib_3_9_test",
-    srcs = ["my_lib_test.py"],
-    main = "my_lib_test.py",
-    python_version = "3.9",
-    deps = ["//libs/my_lib"],
+    name = "coverage_rc_is_set_test",
+    srcs = ["coverage_rc_is_set_test.py"],
+    main = "coverage_rc_is_set_test.py",
 )
 
 py_test(

examples/bzlmod/tests/coverage_rc_is_set_test.py

@@ -0,0 +1,49 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+import tempfile
+import unittest
+
+
+class TestEnvironmentVariables(unittest.TestCase):
+    def test_coverage_rc_file_exists(self):
+        # Assert that the environment variable is set and points to a valid file
+        coverage_rc_path = os.environ.get("COVERAGE_RC")
+        self.assertTrue(
+            os.path.isfile(coverage_rc_path),
+            "COVERAGE_RC does not point to a valid file",
+        )
+
+        # Read the content of the file and assert it matches the expected content
+        expected_content = (
+            "[report]\n"
+            "include_namespace_packages=True\n"
+            "skip_covered=True\n"
+            "[run]\n"
+            "relative_files=True\n"
+            "branch=True\n"
+        )
+
+        with open(coverage_rc_path, "r") as file:
+            file_content = file.read()
+
+        self.assertEqual(
+            file_content,
+            expected_content,
+            "COVERAGE_RC file content does not match the expected content",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

python/BUILD.bazel

@@ -363,3 +363,8 @@ exports_files([
 current_py_toolchain(
     name = "current_py_toolchain",
 )
+
+toolchain_type(
+    name = "py_test_toolchain_type",
+    visibility = ["//visibility:public"],
+)

python/extensions/python_test.bzl

@@ -0,0 +1,39 @@
+# Copyright 2023 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Python toolchain module extensions for use with bzlmod.
+
+::::{topic} Basic usage
+
+The simplest way to configure the toolchain with `rules_python` is as follows.
+
+```starlark
+python_test = use_extension("@rules_python//python/extensions:python_test.bzl", "python_test")
+python_test.configure(
+    coveragerc = ".coveragerc",
+)
+use_repo(python_test, "py_test_toolchain")
+register_toolchains("@py_test_toolchain//:all")
+```
+
+:::{seealso}
+For more in-depth documentation see the {obj}`python.toolchain`.
+:::
+::::
+
+"""
+
+load("//python/private:python_test.bzl", _python_test = "python_test")
+
+python_test = _python_test

python/private/py_executable.bzl

@@ -69,6 +69,7 @@ load(
 load(
     ":toolchain_types.bzl",
     "EXEC_TOOLS_TOOLCHAIN_TYPE",
+    "PY_TEST_TOOLCHAIN_TYPE",
     "TARGET_TOOLCHAIN_TYPE",
     TOOLCHAIN_TYPE = "TARGET_TOOLCHAIN_TYPE",
 )
@@ -1015,6 +1016,7 @@ def py_executable_base_impl(ctx, *, semantics, is_test, inherited_environment =
         inherited_environment = inherited_environment,
         semantics = semantics,
         output_groups = exec_result.output_groups,
+        is_test = is_test,
     )
 
 def _get_build_info(ctx, cc_toolchain):
@@ -1580,7 +1582,8 @@ def _create_providers(
         inherited_environment,
         runtime_details,
         output_groups,
-        semantics):
+        semantics,
+        is_test):
     """Creates the providers an executable should return.
 
     Args:
@@ -1614,21 +1617,32 @@ def _create_providers(
     Returns:
         A list of modern providers.
     """
+
+    default_runfiles = runfiles_details.default_runfiles
+    extra_test_env = {}
+
+    if is_test:
+        py_test_toolchain = ctx.exec_groups["test"].toolchains[PY_TEST_TOOLCHAIN_TYPE]
+        if py_test_toolchain:
+            coverage_rc = py_test_toolchain.py_test_info.coverage_rc
+            extra_test_env = {"COVERAGE_RC": coverage_rc.files.to_list()[0].path}
+            default_runfiles = default_runfiles.merge(ctx.runfiles(files = coverage_rc.files.to_list()))
+
     providers = [
         DefaultInfo(
             executable = executable,
             files = default_outputs,
             default_runfiles = _py_builtins.make_runfiles_respect_legacy_external_runfiles(
                 ctx,
-                runfiles_details.default_runfiles,
+                default_runfiles,
             ),
             data_runfiles = _py_builtins.make_runfiles_respect_legacy_external_runfiles(
                 ctx,
                 runfiles_details.data_runfiles,
             ),
         ),
         create_instrumented_files_info(ctx),
-        _create_run_environment_info(ctx, inherited_environment),
+        _create_run_environment_info(ctx, inherited_environment, extra_test_env),
         PyExecutableInfo(
             main = main_py,
             runfiles_without_exe = runfiles_details.runfiles_without_exe,
@@ -1701,7 +1715,7 @@ def _create_providers(
     providers.extend(extra_providers)
     return providers
 
-def _create_run_environment_info(ctx, inherited_environment):
+def _create_run_environment_info(ctx, inherited_environment, extra_test_env):
     expanded_env = {}
     for key, value in ctx.attr.env.items():
         expanded_env[key] = _py_builtins.expand_location_and_make_variables(
@@ -1710,6 +1724,7 @@ def _create_run_environment_info(ctx, inherited_environment):
             expression = value,
             targets = ctx.attr.data,
         )
+    expanded_env.update(extra_test_env)
     return RunEnvironmentInfo(
         environment = expanded_env,
         inherited_environment = inherited_environment,

python/private/py_test_rule.bzl

@@ -14,6 +14,7 @@
 """Implementation of py_test rule."""
 
 load("@bazel_skylib//lib:dicts.bzl", "dicts")
+load("//python/private:toolchain_types.bzl", "PY_TEST_TOOLCHAIN_TYPE")
 load(":attributes.bzl", "AGNOSTIC_TEST_ATTRS")
 load(":common.bzl", "maybe_add_test_execution_info")
 load(
@@ -52,4 +53,7 @@ py_test = create_executable_rule(
     implementation = _py_test_impl,
     attrs = dicts.add(AGNOSTIC_TEST_ATTRS, _BAZEL_PY_TEST_ATTRS),
     test = True,
+    exec_groups = {
+        "test": exec_group(toolchains = [config_common.toolchain_type(PY_TEST_TOOLCHAIN_TYPE, mandatory = False)]),
+    },
 )

python/private/py_test_toolchain.bzl

@@ -0,0 +1,108 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Simple toolchain which overrides env and exec requirements.
+"""
+
+load(":text_util.bzl", "render")
+load(
+    ":toolchain_types.bzl",
+    "PY_TEST_TOOLCHAIN_TYPE",
+)
+
+PytestProvider = provider(
+    fields = [
+        "coverage_rc",
+    ],
+)
+
+def _py_test_toolchain_impl(ctx):
+    return [
+        platform_common.ToolchainInfo(
+            py_test_info = PytestProvider(
+                coverage_rc = ctx.attr.coverage_rc,
+            ),
+        ),
+    ]
+
+py_test_toolchain = rule(
+    implementation = _py_test_toolchain_impl,
+    attrs = {
+        "coverage_rc": attr.label(
+            allow_single_file = True,
+        ),
+    },
+)
+
+_TOOLCHAIN_TEMPLATE = """
+load("@rules_python//python/private:py_test_toolchain.bzl", "py_test_toolchain_macro")
+py_test_toolchain_macro(
+     {kwargs}
+)
+"""
+
+def py_test_toolchain_macro(*, name, coverage_rc, toolchain_type):
+    """
+    Macro to create a py_test_toolchain rule and a native toolchain rule.
+    """
+    py_test_toolchain(
+        name = "{}_toolchain".format(name),
+        coverage_rc = coverage_rc,
+    )
+    native.toolchain(
+        name = name,
+        target_compatible_with = [],
+        exec_compatible_with = [],
+        toolchain = "{}_toolchain".format(name),
+        toolchain_type = toolchain_type,
+    )
+
+def _toolchains_repo_impl(repository_ctx):
+    kwargs = dict(
+        name = repository_ctx.name,
+        coverage_rc = str(repository_ctx.attr.coverage_rc),
+        toolchain_type = repository_ctx.attr.toolchain_type,
+    )
+
+    build_content = _TOOLCHAIN_TEMPLATE.format(
+        kwargs = render.indent("\n".join([
+            "{} = {},".format(k, render.str(v))
+            for k, v in kwargs.items()
+        ])),
+    )
+    repository_ctx.file("BUILD.bazel", build_content)
+
+py_test_toolchain_repo = repository_rule(
+    _toolchains_repo_impl,
+    doc = "Generates a toolchain hub repository",
+    attrs = {
+        "toolchain_type": attr.string(doc = "Toolchain type", mandatory = True),
+        "coverage_rc": attr.label(
+            allow_single_file = True,
+            doc = "The coverage rc file",
+            mandatory = True,
+        ),
+    },
+)
+
+def register_py_test_toolchain(coverage_rc, register_toolchains = True):
+    # Need to create a repository rule for this to work.
+    py_test_toolchain_repo(
+        name = "py_test_toolchain",
+        coverage_rc = coverage_rc,
+        toolchain_type = str(PY_TEST_TOOLCHAIN_TYPE),
+    )
+    if register_toolchains:
+        native.toolchain(name = "py_test_toolchain")