Asserting equality

Weaver offers two approaches for asserting equality: expect.eql and expect.same.

expect.eql is the better approach, but you may need to write some extra code to use it.

expect.eql (recommended)

expect.eql(expected, found)

expect.eql asserts for strict equality.

If you accidentally compare the wrong types of data, your code will not compile:

expect.eql(1, "one")
// error: Could not find an implicit Comparison[Any]. Does Any have an associated cats.Eq[Any] instance?

The data types you compare must have an Eq typeclass instance. You can declare one, or derive one using kittens.

case class Pet(name: String)

// A cats.Eq instance is needed
import cats.Eq
implicit val petEq: Eq[Pet] = Eq.by(_.name)

object ExpectEqlSuite extends SimpleIOSuite {
  pureTest("Simple expectation") {
    expect.eql(Pet("Maru"), Pet("Fido"))
  }
}

Example report

repl.MdocSessionMdocAppExpectEqlSuite
- Simple expectation 31ms

*************FAILURES*************
repl.MdocSessionMdocAppExpectEqlSuite
- Simple expectation 31ms
  Values not equal: (asserting_equality.md:50)

  in expect.eql(- expected, + found)
   Pet(
  - name = "Maru"
  + name = "Fido"
    )

  asserting_equality.md:50
      expect.eql(Pet("Maru"), Pet("Fido"))
                ^

Total 1, Failed 1, Passed 0, Ignored 0

expect.same

expect.same(expected, found)

expect.same asserts using universal equality.

If you accidentally compare the wrong types of data, your code will compile. Your test will fail later, when it is run:

// This compiles
expect.same(1, "one")

expect.same doesn't require an Eq instance.

case class Dog(name: String) // No Eq instance defined

object ExpectSameSuite extends SimpleIOSuite {
  pureTest("Simple expectation") {
    expect.same(Dog("Maru"), Dog("Fido"))
  }
}

Example report

repl.MdocSessionMdocAppExpectSameSuite
- Simple expectation 2ms

*************FAILURES*************
repl.MdocSessionMdocAppExpectSameSuite
- Simple expectation 2ms
  Values not equal: (asserting_equality.md:79)

  in expect.same(- expected, + found)
   Dog(
  - name = "Maru"
  + name = "Fido"
    )

  asserting_equality.md:79
      expect.same(Dog("Maru"), Dog("Fido"))
                 ^

Total 1, Failed 1, Passed 0, Ignored 0

Do not use expect

You can assert for equality using expect.

expect(1 == 2)

This is discouraged because its failure messages are poorer than expect.eql or expect.same. It does not display a diff of the values on the left and right side of the equality.

Use expect along with clue when you have other assertions. For example to assert for >

expect(clue(x) > 2)

Should I use expect.same or expect.eql?

• Use expect.eql for Scala standard datatypes such as Int and String. These have Eq instances, so don't need any extra code.
• Use expect.eql for your own data types if you prefer compile time errors at the expense of extra code.
• Use expect.same for your own data types if you prefer runtime test failures instead of extra code.

These are described in the suite below.

Example suite

import weaver._

object ExpectationsSuite extends SimpleIOSuite {

  pureTest("expect.eql for standard data types") {
    expect.eql(1, 2)
  }
  
  import cats.Eq
  case class Pet(name: String)
  implicit val eqPet: Eq[Pet] = Eq.by[Pet, String](_.name)
  
  pureTest("expect.eql for user-defined data types") {
    expect.same(Pet("Maru"), Pet("Fido"))
  }

  // Note that we don't have an instance of Eq[Dog]
  // anywhere in scope
  case class Dog(name: String)

  pureTest("expect.same relaxed equality comparison") {
    expect.same(Dog("Maru"), Dog("Fido"))
  }
}

Example suite report

repl.MdocSessionMdocAppExpectationsSuite
- expect.eql for standard data types 4ms
- expect.eql for user-defined data types 2ms
- expect.same relaxed equality comparison 2ms

*************FAILURES*************
repl.MdocSessionMdocAppExpectationsSuite
- expect.eql for standard data types 4ms
  Values not equal: (asserting_equality.md:125)

  in expect.eql(- expected, + found)
  -1
  +2

  asserting_equality.md:125
      expect.eql(1, 2)
                ^
- expect.eql for user-defined data types 2ms
  Values not equal: (asserting_equality.md:133)

  in expect.same(- expected, + found)
   Pet(
  - name = "Maru"
  + name = "Fido"
    )

  asserting_equality.md:133
      expect.same(Pet("Maru"), Pet("Fido"))
                 ^
- expect.same relaxed equality comparison 2ms
  Values not equal: (asserting_equality.md:141)

  in expect.same(- expected, + found)
   Dog(
  - name = "Maru"
  + name = "Fido"
    )

  asserting_equality.md:141
      expect.same(Dog("Maru"), Dog("Fido"))
                 ^

Total 3, Failed 3, Passed 0, Ignored 0