Testing dependency detail

[heckj]

adds warning about accidentally linking testing frameworks, even through transitive dependencies, into executables.

resolves #9291

Motivation:

Due to the way that the runtime handles testing libraries, the test libraries appear to resolve without issue but can cause issues if accidentally linked, even through transitive dependencies, to executable targets.

Modifications:

Revise the primary documentation to link to PackageDescription.
Add in the detail around testing within the Target description.

[heckj]

@swift-ci please test

[heckj]

@stmontgomery , @grynspan - I was at a bit of a loss on where to effectively hook in this information, as we don't (currently) have anything in our guides that talk to creating libraries more generally where this caution could also be added. I fear that the additional detail on Target will be easily missed, so while this technically resolves the heart of #9291, I don't think it does it sufficient justice.

Please chime in with opinions or thoughts on additional ways to present this information within what's currently presented - I'd like to see a place where this could be more solidly represented (and frankly have a better chance of being seen by someone who's in the process of adding or creating their own testing library or related modules.

[jerryjrchen]

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"?

[iamleeg]

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.

[stmontgomery]

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.

[heckj]

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.

[grynspan]

We'd actually like to introduce a separate .testLibrary target type that encapsulates this stuff, FWIW.