Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the messaging around the use of deinit for teardown #551

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Update the messaging around the use of deinit for teardown #551

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cd0a058
Update the messaging around the use of deinit for teardown
medreisbach Jul 18, 2024
e1ae848
Remove "quick" from deinit.
medreisbach Jul 18, 2024
21923ea
Update Sources/Testing/Testing.docc/MigratingFromXCTest.md
medreisbach Jul 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 11 additions & 7 deletions Sources/Testing/Testing.docc/MigratingFromXCTest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,11 +94,11 @@ For more information about suites and how to declare and customize them, see

### Convert setup and teardown functions

In XCTest, code can be scheduled to run before and after a test using the
In XCTest, you can schedule code to run before a test using the
[`setUp()`](https://developer.apple.com/documentation/xctest/xctest/3856481-setup)
and [`tearDown()`](https://developer.apple.com/documentation/xctest/xctest/3856482-teardown)
family of functions. When writing tests using the testing library, implement
`init()` and/or `deinit` instead:
family of functions. When writing tests using the testing library, you can use
`init()` for setup. Your suite's initializer can be `async`, `throws`, or
actor-isolated if necessary.

@Row {
@Column {
Expand Down Expand Up @@ -127,9 +127,13 @@ family of functions. When writing tests using the testing library, implement
}
}

The use of `async` and `throws` is optional. If teardown is needed, declare your
test suite as a `final` class or as an actor rather than as a structure and
implement `deinit`:
In XCTest, you can also schedule work to run after a test using the [`tearDown()`](https://developer.apple.com/documentation/xctest/xctest/3856482-teardown)
family of functions. When writing tests using the testing library, adopt structured
[concurrency](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/)
and take advantage of Swift to handle cleanup for you where possible rather
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you clarify what feature(s) of Swift concurrency, or which APIs, you mean here which assist with cleanup? I can think of defer, but I would consider that a basic language feature rather than a concurrency feature.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think what we should aim to push people towards is using with style methods e.g. try await withNetworkConnection { connection in ... }. This is the pattern that recommend to people to have guaranteed lifetimes with structured concurrency.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's something they have to write themselves, and explaining how to write one would get us into the weeds a bit.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is precedent for describing how testing helps you design nicer APIs and vice versa, and it's something Apple has already published in the Xcode documentation: https://developer.apple.com/documentation/xcode/updating-your-existing-codebase-to-accommodate-unit-tests

So maybe we could take a similar approach here, where we show a with… function as an example of designing API+test together, but (as a separate task) create another doc that shows the thinking behind that design?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would this be an appropriate place to use a snippet?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think an example here would be extremely helpful for users trying to migrate

than relying on a dedicated teardown method. If teardown is necessary, declare
your test suite as a class or actor, and implement `deinit` with operations
that are synchronous and non-throwing.

@Row {
@Column {
Expand Down