From 23d45e8121573e3fd947ffd15e1716e4095b738c Mon Sep 17 00:00:00 2001 From: Gustavo Medori Date: Tue, 3 Feb 2026 22:27:35 -0700 Subject: [PATCH 1/4] Add documentation to Parallelization.md describing how the `.serialized` trait can be applied to a test suite across different files. Resolves #686 --- .../Testing/Testing.docc/Parallelization.md | 43 ++++++++++++++++++- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/Sources/Testing/Testing.docc/Parallelization.md b/Sources/Testing/Testing.docc/Parallelization.md index 7b3e4e2a1..82ca259d9 100644 --- a/Sources/Testing/Testing.docc/Parallelization.md +++ b/Sources/Testing/Testing.docc/Parallelization.md @@ -19,7 +19,7 @@ accomplished by the testing library using task groups, and tests generally all run in the same process. The number of tests that run concurrently is controlled by the Swift runtime. -## Disabling parallelization +## Disable Parallelization Parallelization can be disabled on a per-function or per-suite basis using the ``Trait/serialized`` trait: @@ -49,10 +49,49 @@ test function, this trait has no effect. When applied to a test suite, this trait causes that suite to run its contained test functions and sub-suites serially instead of in parallel. -This trait is recursively applied: if it is applied to a suite, any +The `.serialized` trait is recursively applied: if it is applied to a suite, any parameterized tests or test suites contained in that suite are also serialized (as are any tests contained in those suites, and so on.) This trait doesn't affect the execution of a test relative to its peers or to unrelated tests. This trait has no effect if test parallelization is globally disabled (by, for example, passing `--no-parallel` to the `swift test` command.) + +## Serialize Tests Across Multiple Files + +It may be desirable to organize tests across multiple files while preserving the +serialization of a test suite. For example, consider a scenario where you spin +up a live database for integration testing. You may want to have a large suite +of tests across many files use that same database, but concurrent access to the +database could cause test failures. To achieve this, you can mark a test suite +as `.serialized` and extend that type across your various files. Using the fact +that `.serialized` is recursively applied, you can even put your tests in +sub-suites. + +- `FoodTruckDatabaseTests.swift` + ```swift + @Suite(.serialized) struct FoodTruckDatabaseTests {} + ``` +- `FoodTruckDatabaseTests+Writing.swift` + ```swift + extension FoodTruckDatabaseTests { + @Test func insertOrder() { /* ... */ } + @Test func updateOrder() { /* ... */ } + @Test func deleteOrder() { /* ... */ } + } + ``` +- `FoodTruckDatabaseTests+Reading.swift` + ```swift + extension FoodTruckDatabaseTests { + @Suite struct ReadingTests { + @Test func fetchOrder() { /* ... */ } + @Test func fetchMenu() { /* ... */ } + @Test func fetchIngredients() { /* ... */ } + } + } + ``` + +In the example above, all the test functions in the +`FoodTruckDatabaseTests` extension and in `ReadingTests` will run +serially with respect to each other because they are eventually contained +within a test suite which is declared `.serialized`. From 8e282f11d71ae160b259db021a9dc519c5a7a019 Mon Sep 17 00:00:00 2001 From: Gustavo Medori Date: Wed, 4 Feb 2026 09:26:33 -0700 Subject: [PATCH 2/4] Fix casing in section headers of Parallelization.md --- Sources/Testing/Testing.docc/Parallelization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/Testing/Testing.docc/Parallelization.md b/Sources/Testing/Testing.docc/Parallelization.md index 82ca259d9..cdd78df9e 100644 --- a/Sources/Testing/Testing.docc/Parallelization.md +++ b/Sources/Testing/Testing.docc/Parallelization.md @@ -19,7 +19,7 @@ accomplished by the testing library using task groups, and tests generally all run in the same process. The number of tests that run concurrently is controlled by the Swift runtime. -## Disable Parallelization +## Disable parallelization Parallelization can be disabled on a per-function or per-suite basis using the ``Trait/serialized`` trait: @@ -57,7 +57,7 @@ This trait doesn't affect the execution of a test relative to its peers or to unrelated tests. This trait has no effect if test parallelization is globally disabled (by, for example, passing `--no-parallel` to the `swift test` command.) -## Serialize Tests Across Multiple Files +## Serialize tests across multiple files It may be desirable to organize tests across multiple files while preserving the serialization of a test suite. For example, consider a scenario where you spin From 0eb29f638fcd999a04ff22b45606998f01570369 Mon Sep 17 00:00:00 2001 From: Gustavo Medori Date: Wed, 4 Feb 2026 12:24:08 -0700 Subject: [PATCH 3/4] Improve voice to be more active and clear, and replace usages of `.serialized` with ``Trait/serialized`` --- .../Testing/Testing.docc/Parallelization.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Sources/Testing/Testing.docc/Parallelization.md b/Sources/Testing/Testing.docc/Parallelization.md index cdd78df9e..22c7a784c 100644 --- a/Sources/Testing/Testing.docc/Parallelization.md +++ b/Sources/Testing/Testing.docc/Parallelization.md @@ -49,9 +49,9 @@ test function, this trait has no effect. When applied to a test suite, this trait causes that suite to run its contained test functions and sub-suites serially instead of in parallel. -The `.serialized` trait is recursively applied: if it is applied to a suite, any -parameterized tests or test suites contained in that suite are also serialized -(as are any tests contained in those suites, and so on.) +The ``Trait/serialized`` trait is recursively applied: if it is applied to a +suite, any parameterized tests or test suites contained in that suite are also +serialized (as are any tests contained in those suites, and so on.) This trait doesn't affect the execution of a test relative to its peers or to unrelated tests. This trait has no effect if test parallelization is globally @@ -59,14 +59,14 @@ disabled (by, for example, passing `--no-parallel` to the `swift test` command.) ## Serialize tests across multiple files -It may be desirable to organize tests across multiple files while preserving the +You may want to organize tests across multiple files while preserving the serialization of a test suite. For example, consider a scenario where you spin up a live database for integration testing. You may want to have a large suite of tests across many files use that same database, but concurrent access to the database could cause test failures. To achieve this, you can mark a test suite -as `.serialized` and extend that type across your various files. Using the fact -that `.serialized` is recursively applied, you can even put your tests in -sub-suites. +as ``Trait/serialized`` and extend that type across your various files. +Furthermore, because ``Trait/serialized`` is applied recursively, you can even +put your tests in sub-suites. - `FoodTruckDatabaseTests.swift` ```swift @@ -91,7 +91,7 @@ sub-suites. } ``` -In the example above, all the test functions in the -`FoodTruckDatabaseTests` extension and in `ReadingTests` will run -serially with respect to each other because they are eventually contained -within a test suite which is declared `.serialized`. +In the example above, all the test functions in the `FoodTruckDatabaseTests` +extension and in `ReadingTests` will run serially with respect to each other +because they are eventually contained within a test suite which is declared +``Trait/serialized``. From 8d91678178a7eed7a514120efe24470fff2e9be6 Mon Sep 17 00:00:00 2001 From: Gustavo Medori Date: Wed, 4 Feb 2026 14:36:31 -0700 Subject: [PATCH 4/4] Add more active voice, replacing passive voice in Parallelization.md --- Sources/Testing/Testing.docc/Parallelization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/Testing/Testing.docc/Parallelization.md b/Sources/Testing/Testing.docc/Parallelization.md index 22c7a784c..ffdb45cf1 100644 --- a/Sources/Testing/Testing.docc/Parallelization.md +++ b/Sources/Testing/Testing.docc/Parallelization.md @@ -65,8 +65,8 @@ up a live database for integration testing. You may want to have a large suite of tests across many files use that same database, but concurrent access to the database could cause test failures. To achieve this, you can mark a test suite as ``Trait/serialized`` and extend that type across your various files. -Furthermore, because ``Trait/serialized`` is applied recursively, you can even -put your tests in sub-suites. +Because the testing library recursively applies `Trait/serialized` to all test +content within a suite, you can even put your tests in sub-suites. - `FoodTruckDatabaseTests.swift` ```swift