One of the features of swift-testing is a test traits system that allows associating metadata with a test suite or test function. One trait in particular, .bug(), has the potential for integration with development tools but needs some refinement before integration would be practical.
Read the full proposal here.
Thank you @grynspan for this proposal!
There has not been much feedback either for or against this proposal, and the maintainers of swift-testing collectively agree this is a good enhancement to the Bug API. This proposal is accepted.
The proposal doesn't seem to be accessible
/// A URL linking to more information about the bug, if available. /// /// The value of this property represents a URL conforming to /// [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt). public var url: String?
I would advise not documenting any particular URL standard. In particular, RFC-3986 has been made obsolete by the WHATWG URL standard:
Goals
The URL standard takes the following approach towards making URLs fully interoperable:
- Align RFC 3986 and RFC 3987 with contemporary implementations and obsolete the RFCs in the process. (E.g., spaces, other "illegal" code points, query encoding, equality, canonicalization, are all concepts not entirely shared, or defined.)
I think keeping this as a String is totally fine (and probably even the best design).
If you want to do some kind of validation of these strings, my WebURL library implements the WHATWG standard in pure Swift. The WHATWG parsing algorithm performs a lot of repairs on URLs to clean up potential ambiguities, so if you did want to perform such a check, I'd advise checking that the parser's output matches the input and asking users to rewrite their URLs in that form:
func validateURL(_ input: String) throws {
guard let parsed = WebURL(input) else {
throw InvalidURLError.cannotParse
}
if input != parsed.serialized {
throw MalformedURLError(suggestion: parsed.serialized)
}
}
validateURL("HTTP://0x7F.1:80\foo\bar")
// MalformedURLError:
// This URL is interpreted as "http://127.0.0.1/foo/bar"
// Please rewrite it in this form.
IDNA support requires Foundation (because that's currently the only practical way to get Unicode normalisation -- ICU is too much hassle), but I could add a build condition to omit IDNA support if you did wanted to use the library without any Foundation dependency.
That said, I think it's also fine to just not validate the URL string. It's for external tooling, and that external tooling can parse/validate it if it needs to.
Oh, and there is some precedent to the idea of declining to document a particular URL standard:
When W3C produced the HTML5 recommendation [9], the normative
reference to the WHATWG URL standard was a gating issue, and an
unusual compromised was reached [10], where the [URL] reference is
given a descriptive paragraph rather than a single document
reference.
URL Problem Statement and Directions
I love the idea that the best we can do is a rough description of what a URL looks like, but I like absurdist humour, so...
I've updated the link to the proposal.
Thanks for your feedback! We specifically call out RFC 3986 because that's what Foundation's URL parsing is based on, and our expectation is that a tool written in Swift and using swift-testing's Swift interfaces would most likely reach for URL to parse the string.
It does now, but that's a very recent change. It didn't in the past, and, by similar logic, may not in the future.
Is it really expected that Swift tools parse the string? Like, do they really care about the URL's internal structural components? They can, of course, but I think it's much more likely they'll just forward it to a web browser or system resolver.
Easiest thing to do is drop the reference to this specific obsolete standard and any validation. It's just some string which the user intends to be interpreted as a URL. Maybe the tool has an interest in parsing it and can parse it, or maybe it can't - that's between the user and the tool, it's not the testing framework's problem IMO.
Thanks for the feedback. We work closely with the Foundation team and if they change the URL standard they use for parsing, we can make accommodations at that time.
You may be understanding "parse" here to mean that a tool extracts specific components from a URL, but we're using the term a bit more broadly. Just the act of verifying that a string represents a valid URL requires parsing it. A tool that wants to e.g. provide clickable links in its UI derived from this property would need to parse it first to determine if that is an appropriate action.