Replace expecty with clue

[zainab-ali]

This PR replaces expecty with an munit-like clue function.

It uses macros to generate clues. Unlike munit, clues are stored locally to the expect call. This avoids the need for a global lock, and means tests can run concurrently, and add clues, without relying on any extra concurrency primitives.

It assumes that the code within an expect call is synchronous.

The behaviour is identical for Scala 2 and 3, but the macros are implemented differently.

Note that the signatures for expect aren't identical for Scala 2 and 3. The Scala 3 expect functions use context functions.

Behaviour

A user can write:

val x = 1
val y = 2
expect(clue(x) == clue(y))

and will see the following on test failure:

Clues {
  x: Int = 1
  y: Int = 2
}

They can also nest calls to clue:

val x = 1
val y = 2
expect(clue(List(clue(x))) == clue(List(clue(y))))

Scala 2 implementation

The Scala 2 implementation has a couple of macros:

• The ClueMacro generates a clue for a value expression. This is identical to munit's clue macro.
• The ExpectMacro constructs a local collection of Clues. Calls to the clue function are rewritten to call the addClue function of the local collection.

Scala 3 implementation

In Scala 3, we can use context functions to provide the Clues collection. It still has a couple of macros:

• The ClueMacro generates a clue for a value expression using simpler logic for obtaining the source code and type.
• The ExpectMacro gets the source location to ensure that the tracing behaviour of expect is the same as it was previously. Calls to clue don't need to be rewritten.

[Baccata]

👍

[Baccata]

👍

[Baccata]

I'm curious about this transformation here. Can you explain ?

[zainab-ali]

Of course!

For context, the user writes clue(x) where clue refers to ClueHelpers.clue. There's an implicit conversion from x to a Clue. Explicitly, this is written as clue(Clue.generateClue(x)) .

The transformation replaces ClueHelpers.clue with addClue on a clues collection. In other words, it replaces:
clue(Clue.generateClue(x)) with clues.addClue(Clue.generateClue(x)).

The clues collection is generated as part of the overall expect macro. For example:

expect(clue(List(x, clue(y))))

becomes

expect {
  val clues = new Clues()
  clues.addClue(List(x, clues.addClue(y)))
}

[Baccata]

oh gotcha, hadn't thought of nested clues, but it makes sense 👍

[Baccata]

This is great ! Thank you so much for taking that on !🥇

I just have a minor question, but I'm happy with the code, tests, and documentation.