Distribute large integration test files across workers (#10761)

Add a --dist option to scripts/ci/run-tests and run the integration
tests with --dist loadgroup. Tests are grouped per file as before,
except the large offline skeleton tests, which are distributed per
test, and the S3 plugin tests, which are distributed per class.

Author: GarrettBeatty

scripts/ci/run-integ-tests

@@ -31,4 +31,6 @@ def run(command):
 
 if __name__ == "__main__":
     with cd(os.path.join(REPO_ROOT, "tests")):
-        run(f"{REPO_ROOT}/scripts/ci/run-tests integration")
+        # Tests are grouped per file (see tests/integration/conftest.py) except for
+        # large offline test files, which are distributed per test.
+        run(f"{REPO_ROOT}/scripts/ci/run-tests --dist loadgroup integration")

scripts/ci/run-tests

@@ -59,10 +59,10 @@ def process_args(args):
     elif os.getenv('GITHUB_ACTIONS', 'false') == 'true':
         # Limiting parallelism in GitHub, to avoid the
         # 'Error: The operation was canceled.' issues in 2026
-        max_processes=3
+        max_processes = 3
     else:
-        max_processes=4
-    test_args += f'--numprocesses=auto --dist=loadfile --maxprocesses={max_processes} '
+        max_processes = 4
+    test_args += f'--numprocesses=auto --dist={args.dist} --maxprocesses={max_processes} '
     dirs = " ".join(args.test_dirs)
 
     return runner, test_args, dirs
@@ -106,6 +106,14 @@ if __name__ == "__main__":
         default=[],
         help=("Ignore a test subdirectory. Can be specified multiple times."),
     )
+    parser.add_argument(
+        "--dist",
+        default="loadfile",
+        help=(
+            "The pytest-xdist distribution mode to use. Defaults to "
+            "loadfile, which runs all tests in a file on the same worker."
+        ),
+    )
     parser.add_argument(
         "--tests-path",
         default=None,

tests/integration/conftest.py

@@ -0,0 +1,47 @@
+# Copyright 2026 Amazon.com, Inc. or its affiliates. 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. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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 pytest
+
+# These files only exercise local service models (no AWS calls) and are
+# parametrized over every CLI command or operation, so they contain most of
+# the integration tests. They are distributed across workers per test
+# instead of running every test in the file on a single worker.
+_DISTRIBUTE_PER_TEST = (
+    'integration/customizations/test_generatecliskeleton.py',
+    'integration/botocore/test_utils.py',
+)
+
+# These files contain many slow, independent test classes, so they are
+# distributed across workers per class instead of per file. Their shared
+# fixtures (e.g. S3 buckets) are package scoped, so each worker creates its
+# own.
+_DISTRIBUTE_PER_CLASS = ('integration/customizations/s3/test_plugin.py',)
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_collection_modifyitems(items):
+    # With ``--dist loadgroup``, tests in the same ``xdist_group`` run on the
+    # same worker and ungrouped tests are distributed individually. Grouping
+    # the remaining tests by file preserves the ``--dist loadfile`` behavior
+    # they rely on, such as sharing module and class scoped fixtures that
+    # create AWS resources.
+    for item in items:
+        parts = item.nodeid.split('::')
+        path = parts[0]
+        if path.endswith(_DISTRIBUTE_PER_TEST):
+            continue
+        if path.endswith(_DISTRIBUTE_PER_CLASS) and len(parts) > 2:
+            group = '::'.join(parts[:2])
+        else:
+            group = path
+        item.add_marker(pytest.mark.xdist_group(group))