Add macros for enhanced output in Swift Testing

[ZevEisenberg]

I didn't see a discussion or ticket for this already, which surprised me. I just found myself suggesting this change in a code review:

-expectNoDifference(tables.contains("someTableName"), true)
+#expect(tables.contains("someTableName"))

My justification was that, for simple values, the advanced diff output of expectNoDifference is not as meaningful (although still nice), and the tradeoff is that the #expect macro will include the contents of the failing expression (tables.contains("someTableName")) in the failure message in the Xcode console, sidebar, CI, etc.

But it's a drag to have to think about which one to use. I'd rather just use expectNoDifference and get the best of both worlds.

What about something like #expectNoDifference(foo, bar) or maybe #customDumpExpect(foo == bar) and #customDumpExpect(foo != bar)? The naming is up for debate, but the idea is that it means you could always use it instead of #expect without having to think about which is which. Maybe it could even support all the other operators like > from #expect, just as a passthrough, or even wrap #expect for non-== cases, and then a project could use a linter to enforce that it always uses the one from this library.

[stephencelis]

We've wondered about this a little but couldn't really figure out if it would work or not, and given the cost of macros, we decided to spare this library unless we could make a worthwhile case.

If you explore the problem a bit more, e.g. some motivating examples and improved outputs, and share your findings, we'd love to hear them!

[ZevEisenberg]

I hear the bottom is about to fall out of the macros market 😉

[turbolent]

+1 on better diff output for Swift Testing. I had asked about this in the forum https://forums.swift.org/t/customize-difference-output/81455

I'm not sure if this is necessarily something that should be done in this library, it might be better to make Swift Testing more customizable and allow the usage of libraries like this one.

[mbrandonw]

Hi @turbolent, what exactly would you like improved over the current display of test failure messages, and how do you think macros will help with that?

[turbolent]

Sorry for not explaining myself better. The diff output from swift-custom-dump is fantastic, and needs no improvement.

I was referring to the diff output of Swift Testing, where e.g. output for #expect(... == ...) is not very useful at the moment, especially for larger data structures. It would be great if Swift Testing would have similar output as swift-custom-dump, or at least there was a way to integrate the two better. Ideally it would be nice to keep using #expect, but hook it up to e.g. swift-custom-dump to report the diff.

[ZevEisenberg]

Rereading this after some time, I actually would like to get slightly tweaked output from swift-custom-dump, specifically around showing the literal text of the code of the things you're comparing. I would like if #customDumpExpect(foo == bar) would show foo == bar in the output. That said, I agree with the Point-Free folks' advice to come up with some concrete use cases before we go too deep here. For example, I often use expectNoDifference with giant struct literals, and I don't necessarily want those cluttering up my code.

[stephencelis]

@ZevEisenberg I think what would be helpful is to consider what #customDumpExpect expands the code to, and what that would unlock. A full example, including test failure output, might help motivate things.