Skip to content

Testing dependency detail #9343

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

Open
heckj wants to merge 4 commits into
base: main
Choose a base branch
from
+10 −4
Open

Testing dependency detail #9343

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
addd138
moving adding dependencies into folder with other dependency content …
heckj Nov 5, 2025
b81497f
removing legacy note from main page of docs
heckj Nov 5, 2025
b5b7d14
cross linking into PackageDescription API docs for Products, Dependen…
heckj Nov 5, 2025
0a59b5a
extend Target documentation to provide caution around accidentally li…
heckj Nov 5, 2025
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
0 .../Documentation.docc/AddingDependencies.md → ...n.docc/Dependencies/AddingDependencies.md
View file
Open in desktop
File renamed without changes.
2 changes: 1 addition & 1 deletion Sources/PackageManagerDocs/Documentation.docc/Documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The Swift Package Manager lets you share your code as a package, depend on and u

### Essentials

- <doc:GettingStarted> <!-- tutorial or article based walk through -->
- <doc:GettingStarted>
- <doc:IntroducingPackages>
- <doc:PackageSecurity>

Expand Down
6 changes: 3 additions & 3 deletions Sources/PackageManagerDocs/Documentation.docc/IntroducingPackages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,17 @@ Learn to create and use a Swift package.
A package consists of a `Package.swift` manifest file along with source files, resources, and other assets.
The manifest file, or package manifest, defines the package's name and its contents using the [PackageDescription](https://developer.apple.com/documentation/packagedescription) module.

Each package declares `Products`, a list of what the package produces.
Each package declares [Products](https://docs.swift.org/swiftpm/documentation/packagedescription/product), a list of what the package produces.
Types of products include libraries, executables, and plugins:

- A library defines one or more modules that can be imported by other code.
- An executable is a program that can be run by the operating system.
- A plugin is executable code that the Swift Package Manager may use to provide additional commands or build capabilities.

A package may declare `Dependencies`, that provide products from other Swift packages.
A package may declare [Dependencies](https://docs.swift.org/swiftpm/documentation/packagedescription/package/dependency), that provide products from other Swift packages.
A dependency may also be defined to a system library or binary (non-source) artifact.

Each product is made up of one or more `Targets`, the basic building block of a Swift package.
Each product is made up of one or more [Targets](https://docs.swift.org/swiftpm/documentation/packagedescription/target), the basic building block of a Swift package.
Each target specifies an module, may declare one or more dependencies on other targets within the same package and on products vended by the package’s dependencies.
A target may define a library, a test suite, an executable, an macro, a binary file, and so on.

Expand Down
6 changes: 6 additions & 0 deletions Sources/Runtimes/PackageDescription/PackageDescription.docc/Curation/Target.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# ``PackageDescription/Target``

### Test Libraries Targets

Built-in testing libraries, such as Swift Testing and XCTest, are only available for use in certain runtime contexts.
While you can link to the them targets, in order to modularly provide additional testing capabilities, take care to only link them to test targets (``TargetType/test``).
Copy link

@jerryjrchen jerryjrchen Nov 6, 2025

Choose a reason for hiding this comment

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

While you can link to the them targets

I think there's a word or two missing here :)

Also, my impression is that most packages don't need to explicitly link testing libraries for test targets. Maybe this could be worded to highlight that typical use case: "typically, don't link Swift Testing or XCTest, either directly or transitively"?

Copy link

@iamleeg iamleeg Nov 6, 2025

Choose a reason for hiding this comment

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

Also there are situations where you do want to link these libraries to targets that aren't test targets: libraries or frameworks that are themselves imported by test targets. For example, if you create a property-based testing library that relies on swift-testing, you add Testing as a dependency to access its API.

Copy link
Contributor

@stmontgomery stmontgomery Dec 5, 2025

Choose a reason for hiding this comment

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

I don't think we should phrase this so strictly as to completely prohibit the use of Swift Testing or XCTest in non-.testTarget targets. Instead, I think this should explain that usage of these libraries should be confined, transitively, to only targets which are used in testing contexts.

One way to think about it is that the chain of dependencies should always terminate in a .testTarget, but along the way there can be regular .target's as intermediaries. And above all else, the guidance should be that targets which use Swift Testing or XCTest should never be distributed to end users. They should only ever be used in conjunction with the toolchain which was used to build the artifacts.

Copy link
Member Author

@heckj heckj Dec 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Thanks, let me rework this a smidge and fix the wording missed while im at it ;-)

Im afraid I lost track of this a bit with thanksgiving in there.

Including testing libraries, as direct or transitive dependencies, can cause clients to encounter linking issues.

## Topics

### Naming the Target
Expand Down