Add xctrunner and xctrunnertool

apple/BUILD

@@ -260,6 +260,12 @@ bzl_library(
     deps = ["//apple/internal:xcarchive"],
 )
 
+bzl_library(
+    name = "xctrunner",
+    srcs = ["xctrunner.bzl"],
+    deps = ["//apple/internal:xctrunner"],
+)
+
 bzl_library(
     name = "docc",
     srcs = ["docc.bzl"],

apple/internal/BUILD

@@ -816,6 +816,18 @@ bzl_library(
     ],
 )
 
+bzl_library(
+    name = "xctrunner",
+    srcs = ["xctrunner.bzl"],
+    visibility = [
+        "//apple:__subpackages__",
+    ],
+    deps = [
+        "//apple:providers",
+        "//apple/internal/providers:apple_debug_info",
+    ],
+)
+
 bzl_library(
     name = "docc",
     srcs = ["docc.bzl"],

apple/internal/xctrunner.bzl

@@ -0,0 +1,134 @@
+"""
+Rule for merging multiple test targets into a single XCTRunner.app bundle.
+"""
+
+load(
+    "//apple:providers.bzl",
+    "AppleBundleInfo",
+)
+
+_TestTargetInfo = provider(
+    "Test target info for tests that will be run.",
+    fields = {
+        "infoplists": "A `depset` of `File`s of `Info.plist` files.",
+        "xctests": "A `depset` of paths of XCTest bundles.",
+    },
+)
+
+def _test_target_info_aspect_impl(target, ctx):
+    rule_attr = ctx.rule.attr
+
+    if AppleBundleInfo in target:
+        info = target[AppleBundleInfo]
+        xctests = depset([info.archive])
+        infoplists = depset([info.infoplist])
+    else:
+        deps = getattr(rule_attr, "tests", [])
+        xctests = depset(
+            transitive = [
+                dep[_TestTargetInfo].xctests
+                for dep in deps
+            ],
+        )
+        infoplists = depset(
+            transitive = [
+                dep[_TestTargetInfo].infoplists
+                for dep in deps
+            ],
+        )
+
+    return [
+        _TestTargetInfo(
+            infoplists = infoplists,
+            xctests = xctests,
+        ),
+    ]
+
+test_target_info_aspect = aspect(
+    attr_aspects = ["tests"],
+    implementation = _test_target_info_aspect_impl,
+)
+
+def _xctrunner_impl(ctx):
+    # Get test target info
+    infos = [target[_TestTargetInfo] for target in ctx.attr.test_targets]
+    infoplists = depset(
+        transitive = [info.infoplists for info in infos],
+    )
+    xctests = depset(
+        transitive = [info.xctests for info in infos],
+    )
+    output = ctx.actions.declare_directory(ctx.label.name + ".app")
+
+    # Args for _make_xctrunner
+    arguments = ctx.actions.args()
+    arguments.add("--name", ctx.label.name)
+    arguments.add("--platform", ctx.attr.platform)
+
+    # absolute paths to xctest bundles
+    arguments.add_all(
+        xctests,
+        before_each = "--xctest",
+        expand_directories = False,
+    )
+
+    # app bundle output path
+    arguments.add("--output", output.path)
+
+    ctx.actions.run(
+        inputs = depset(transitive = [xctests, infoplists]),
+        outputs = [output],
+        executable = ctx.executable._make_xctrunner,
+        arguments = [arguments],
+        mnemonic = "MakeXCTRunner",
+    )
+
+    return DefaultInfo(files = depset([output]))
+
+xctrunner = rule(
+    implementation = _xctrunner_impl,
+    attrs = {
+        "platform": attr.string(
+            default = "iPhoneOS.platform",
+            mandatory = False,
+            doc = "Platform to bundle for. Default: iPhoneOS.platform",
+        ),
+        "test_targets": attr.label_list(
+            mandatory = True,
+            aspects = [test_target_info_aspect],
+            doc = "List of test targets and suites to include.",
+        ),
+        "_make_xctrunner": attr.label(
+            default = Label("//tools/xctrunnertool:run"),
+            executable = True,
+            cfg = "exec",
+            doc = "An executable binary that can merge separate xctest into a single XCTestRunner bundle.",
+        ),
+    },
+    doc = """\
+Packages one or more .xctest bundles into a XCTRunner.app.
+
+Note: Tests inside must be qualified with the test target
+name as `testTargetName/testClass/testCase` for device farm builds.
+
+Example:
+
+````starlark
+load("//apple:xctrunner.bzl", "xctrunner")
+
+ios_ui_test(
+    name = "HelloWorldSwiftUITests",
+    minimum_os_version = "15.0",
+    runner = "@build_bazel_rules_apple//apple/testing/default_runner:ios_xctestrun_ordered_runner",
+    test_host = ":HelloWorldSwift",
+    deps = [":UITests"],
+)
+
+xctrunner(
+    name = "HelloWorldSwiftXCTRunner",
+    test_targets = [":HelloWorldSwiftUITests"],
+    testonly = True,
+)
+````
+    """,
+)

apple/xctrunner.bzl

@@ -0,0 +1,24 @@
+# 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.
+
+"""
+Rule for creating a XCTRunner.app with one or more .xctest bundles.
+"""
+
+load(
+    "//apple/internal:xctrunner.bzl",
+    _xctrunner = "xctrunner",
+)
+
+xctrunner = _xctrunner

doc/BUILD.bazel

@@ -19,6 +19,7 @@ _RULES_DOC_SRCS = [
     "visionos.doc",
     "watchos.doc",
     "xcarchive",
+    "xctrunner",
 ]
 
 _DOC_SRCS = _PLAIN_DOC_SRCS + _RULES_DOC_SRCS

doc/README.md

@@ -144,6 +144,10 @@ below.
         <td valign="top"><code>@build_bazel_rules_apple//apple:versioning.bzl</code></td>
         <td valign="top"><code><a href="rules-versioning.md#apple_bundle_version">apple_bundle_version</a></code><br/></td>
       </tr>
+      <tr>
+        <td valign="top"><code>@build_bazel_rules_apple//apple:xctrunner.bzl</code></td>
+        <td valign="top"><code><a href="rules-xctrunner.md#xctrunner">xctrunner</a></code></td>
+      </tr>
     </tr>
     <tr>
       <th align="left" valign="top" rowspan="1">Resources</th>

doc/rules-xctrunner.md

@@ -0,0 +1,47 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Rule for creating a XCTRunner.app with one or more .xctest bundles.
+
+<a id="xctrunner"></a>
+
+## xctrunner
+
+<pre>
+xctrunner(<a href="#xctrunner-name">name</a>, <a href="#xctrunner-platform">platform</a>, <a href="#xctrunner-test_targets">test_targets</a>)
+</pre>
+
+Packages one or more .xctest bundles into a XCTRunner.app.
+
+Note: Tests inside must be qualified with the test target
+name as `testTargetName/testClass/testCase` for device farm builds.
+
+Example:
+
+````starlark
+load("//apple:xctrunner.bzl", "xctrunner")
+
+ios_ui_test(
+    name = "HelloWorldSwiftUITests",
+    minimum_os_version = "15.0",
+    runner = "@build_bazel_rules_apple//apple/testing/default_runner:ios_xctestrun_ordered_runner",
+    test_host = ":HelloWorldSwift",
+    deps = [":UITests"],
+)
+
+xctrunner(
+    name = "HelloWorldSwiftXCTRunner",
+    test_targets = [":HelloWorldSwiftUITests"],
+    testonly = True,
+)
+````
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="xctrunner-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="xctrunner-platform"></a>platform |  Platform to bundle for. Default: iPhoneOS.platform   | String | optional |  `"iPhoneOS.platform"`  |
+| <a id="xctrunner-test_targets"></a>test_targets |  List of test targets and suites to include.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | required |  |
+
+

examples/ios/HelloWorldSwift/BUILD

@@ -1,6 +1,7 @@
 load("@bazel_skylib//rules:build_test.bzl", "build_test")
 load("@build_bazel_rules_swift//swift:swift.bzl", "swift_library")
 load("//apple:docc.bzl", "docc_archive")
+load("//apple:xctrunner.bzl", "xctrunner")
 load("//apple:ios.bzl", "ios_application", "ios_ui_test", "ios_unit_test")
 
 licenses(["notice"])
@@ -103,3 +104,9 @@ docc_archive(
     fallback_display_name = "HelloWorldSwift",
     minimum_access_level = "internal",
 )
+
+xctrunner(
+    name = "HelloWorldSwiftXCTRunner",
+    test_targets = [":HelloWorldSwiftUITests"],
+    testonly = True,
+)