TaskLocal test trait by mbrandonw · Pull Request #3329 · swiftlang/swift-evolution

mbrandonw · 2026-06-18T23:18:52Z

A proposal for a new .taskLocal test trait for overriding task locals in tests.

Corrected typos and improved clarity in the documentation regarding the task local test trait.

grynspan · 2026-06-18T23:31:38Z

+
+## Alternatives considered
+
+A more general name for this API could be used instead of `.taskLocal`:


I think the workgroup discussed a couple of other possible names for this trait; please include any you remember here. (I specifically mentioned withValue<T>(_: T, for taskLocal: TaskLocal<T>), and I think somebody else had at least one other suggestion but I don't recall offhand what it was.)

My suggestion was .binding(T, to: V). The verb "bind" has some precedence in the TaskLocal documentation.

grynspan

Minor comments only. Please make sure to update the proposal with any corresponding changes in the implementation PR!

Co-authored-by: Jonathan Grynspan <grynspan@me.com>

ktoso

This looks good to me, just a minor nitpick about avoiding the word override (we don't really use that term with task locals).

The naming .taskLocal(..., value) also sounds good to me

ktoso · 2026-06-19T00:40:53Z

+
+There are two primary motivations for adding this convenience:
+
+* Task locals are by far the [most common] reason to define custom `TestScoping` 


Suggested change

* Task locals are by far the [most common] reason to define custom `TestScoping`

* Task locals are by far the most common reason to define custom `TestScoping`

not sure why the [], just "the most common ..."

The brackets link just below to some context: https://github.com/search?q=testscoping+language%3ASwift+&type=code

We just found that a lot of the public TestScoping conformances are related to task locals.

Co-authored-by: Konrad `ktoso` Malawski <konrad.malawski@project13.pl>

Updated terminology from 'overriding' to 'binding' for clarity in the context of task locals. Adjusted related descriptions to reflect this change throughout the document.

stephencelis · 2026-06-19T06:13:42Z

@grynspan Requested changes applied! Let us know if there's anything else.

stmontgomery · 2026-06-19T13:08:20Z

+
+In [ST-0007], test scoping traits were introduced to allow wrapping the execution
+of tests so that code could be run before and after each test. The main
+motivation for this feature is overriding [`TaskLocal`s][SE-0311: TaskLocal] for tests, and the


Hmm, this still isn't showing the link in the rendered version of the document. Might be a markdown syntax quirk

This might work better as a standard markdown link instead of the brackets link.

stmontgomery · 2026-06-19T13:11:15Z

+/// A type that binds a task local value for the scope of a test.
+///
+/// To add this trait to a test, use ``Trait/taskLocal(_:_:)``.
+public struct TaskLocalTrait<Value: Sendable>: SuiteTrait, TestScoping, TestTrait {


Minor stylistic thing, but I'd list TestTrait before TestScoping—it's a trait type first and foremost

stmontgomery · 2026-06-19T13:22:41Z

+If Swift macros gain the ability to see symbols defined by other macros, we will be able to drop
+the restriction that task locals be defined outside the test target.


I understand where this comes from, but the phrasing of "…we will be able to drop the restriction…" could be a little confusing: the API itself isn't imposing any such restriction, it's a consequence of current language restrictions outside the scope of this proposal.

I'd suggest tweaking this by saying something like: if this macro limitation were resolved, then this proposed API would become usable in more contexts/situations. The thing I'm looking to clarify is that no further action or change to the API would be required; it would "only" require a change to the language or macro system.

Co-authored-by: Stuart Montgomery <smontgomery@apple.com>

Corrected references to TaskLocal in the motivation section and updated the link formatting.

mbrandonw and others added 2 commits June 18, 2026 09:59

Add '.taskLocal' test trait.

4481ab4

Fix typos and enhance documentation for task local trait

d9a994c

Corrected typos and improved clarity in the documentation regarding the task local test trait.

mbrandonw mentioned this pull request Jun 18, 2026

TaskLocal test trait swiftlang/swift-testing#1764

Open

2 tasks

grynspan reviewed Jun 18, 2026

View reviewed changes

Comment thread proposals/testing/NNNN-task-local-test-trait.md Outdated

grynspan reviewed Jun 18, 2026

View reviewed changes

Comment thread proposals/testing/NNNN-task-local-test-trait.md Outdated

ktoso self-requested a review June 18, 2026 23:21

grynspan reviewed Jun 18, 2026

View reviewed changes

grynspan requested changes Jun 18, 2026

View reviewed changes

grynspan assigned mbrandonw Jun 18, 2026

grynspan added workgroup: needs development This proposal needs to be developed further before it can be reviewed TWG Contains topics under the domain of the Testing Workgroup new proposal Adds a new proposal document labels Jun 18, 2026

stephencelis and others added 3 commits June 18, 2026 17:26

Update proposals/testing/NNNN-task-local-test-trait.md

1e023f2

Co-authored-by: Jonathan Grynspan <grynspan@me.com>

Update proposals/testing/NNNN-task-local-test-trait.md

f7ed72d

Co-authored-by: Jonathan Grynspan <grynspan@me.com>

Feedback

087d945

ktoso approved these changes Jun 19, 2026

View reviewed changes

ktoso reviewed Jun 19, 2026

View reviewed changes

Comment thread proposals/testing/NNNN-task-local-test-trait.md Outdated

stephencelis and others added 8 commits June 18, 2026 23:05

Update proposals/testing/NNNN-task-local-test-trait.md

e1e7c8d

Co-authored-by: Konrad `ktoso` Malawski <konrad.malawski@project13.pl>

Update proposals/testing/NNNN-task-local-test-trait.md

d11e8e1

Co-authored-by: Konrad `ktoso` Malawski <konrad.malawski@project13.pl>

Update proposals/testing/NNNN-task-local-test-trait.md

f749024

Co-authored-by: Konrad `ktoso` Malawski <konrad.malawski@project13.pl>

Update proposals/testing/NNNN-task-local-test-trait.md

612a21b

Co-authored-by: Konrad `ktoso` Malawski <konrad.malawski@project13.pl>

Update proposals/testing/NNNN-task-local-test-trait.md

8313095

Co-authored-by: Konrad `ktoso` Malawski <konrad.malawski@project13.pl>

Update proposals/testing/NNNN-task-local-test-trait.md

e2ae5ad

Co-authored-by: Konrad `ktoso` Malawski <konrad.malawski@project13.pl>

Clarify task local trait terminology in documentation

9cf7893

Updated terminology from 'overriding' to 'binding' for clarity in the context of task locals. Adjusted related descriptions to reflect this change throughout the document.

Fixes

2c20426

Update NNNN-task-local-test-trait.md

30b37ed

stmontgomery reviewed Jun 19, 2026

View reviewed changes

stmontgomery assigned stephencelis Jun 19, 2026

Update proposals/testing/NNNN-task-local-test-trait.md

fe9ba30

Co-authored-by: Stuart Montgomery <smontgomery@apple.com>

stephencelis and others added 11 commits June 19, 2026 14:04

Update proposals/testing/NNNN-task-local-test-trait.md

aa3ae4c

Co-authored-by: Stuart Montgomery <smontgomery@apple.com>

Update proposals/testing/NNNN-task-local-test-trait.md

883510e

Co-authored-by: Stuart Montgomery <smontgomery@apple.com>

Update proposals/testing/NNNN-task-local-test-trait.md

7c08931

Co-authored-by: Stuart Montgomery <smontgomery@apple.com>

Update proposals/testing/NNNN-task-local-test-trait.md

cf1ba5e

Co-authored-by: Stuart Montgomery <smontgomery@apple.com>

Update proposals/testing/NNNN-task-local-test-trait.md

92781aa

Co-authored-by: Stuart Montgomery <smontgomery@apple.com>

Update NNNN-task-local-test-trait.md

7e4f0b6

Fix TaskLocal references and link formatting

b0dff58

Corrected references to TaskLocal in the motivation section and updated the link formatting.

Update NNNN-task-local-test-trait.md

aca6e45

Update NNNN-task-local-test-trait.md

54fe282

Update NNNN-task-local-test-trait.md

5901b56

Update NNNN-task-local-test-trait.md

02bd8f5


		## Alternatives considered

		A more general name for this API could be used instead of `.taskLocal`:


		There are two primary motivations for adding this convenience:

		* Task locals are by far the [most common] reason to define custom `TestScoping`

	* Task locals are by far the [most common] reason to define custom `TestScoping`
	* Task locals are by far the most common reason to define custom `TestScoping`

		If Swift macros gain the ability to see symbols defined by other macros, we will be able to drop
		the restriction that task locals be defined outside the test target.

Uh oh!

Conversation

mbrandonw commented Jun 18, 2026 • edited by stmontgomery Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

grynspan left a comment

Choose a reason for hiding this comment

Uh oh!

ktoso left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stephencelis commented Jun 19, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

mbrandonw commented Jun 18, 2026 •

edited by stmontgomery

Loading