ScalaMock Documentation

Scalamock uses compile-time generation to create stubs and mocks. For any provided trait or class definition, Scalamock generates an implementation that stores state internally. This state is updated whenever an expectation is set or a method is invoked.

There are two primary internal approaches depending on the API used:

1. New Stubs: Uses a StubbedMethod[Args, Result] for each method. If a method has multiple arguments, they are internally handled as a tuple. To simplify generation, these are stored as StubbedMethod[Any, Any] and cast to the correct type at runtime.
2. Classic API: Uses specific function types based on the exact number of arguments (e.g., MockFunction1, MockFunction2, up to MockFunction22). This allows the public API to provide type-safe argument matching (e.g., expects(*, *)).

trait Foo:
  def oneArg(x: Int): Int
  def twoArgs(x: Int, y: String): String
  def curried(x: Int)(y: String): Int

val foo = stub[Foo]

ScalaMock provides different syntaxes for accessing StubbedMethod depending on your Scala version.

Given a stubbed trait:

trait Foo:
  def foo0: Int
  def foo(x: Int): Int
  def fooBar(bar: Boolean, baz: String): String

val foo = stub[Foo]

Scala 3 Syntax

Methods are accessed directly. For methods with multiple arguments, the argument type A is a tuple.

val foo0Stubbed: StubbedMethod[Unit, Int] = () => foo.foo0
val fooStubbed: StubbedMethod[Int, Int] = foo.foo
val fooBarStubbed: StubbedMethod[(Boolean, String), String] = foo.fooBar

Scala 2 Syntax

You must use the method reference syntax (_) to obtain the StubbedMethod.

val foo0Stubbed: StubbedMethod[Unit, Int] = () => foo.foo0
val fooStubbed: StubbedMethod[Int, Int] = foo.foo _
val fooBarStubbed: StubbedMethod[(Boolean, String), String] = foo.fooBar _

// Scala 3
foo.fooBar.returnsWith("value")

// Scala 2
(foo.fooBar _).returnsWith("value")

You can use zio.test.Assertion directly as a parameter matcher in ScalaMock expectations. This allows you to leverage the full power of ZIO Test assertions when validating arguments passed to mocked methods.

Default Behavior (Ordered)

By default, converting a zio.test.Assertion[A] to a MockParameter[A] uses argAssert internally. This means it is sensitive to call order and does not work with inAnyOrder.

Unordered Calls

If you need to use a ZIO assertion within an inAnyOrder expectation, you must use the allowAnyOrderSyntax extension. This provides the .allowUnorderedCalls method on your assertion.

Example Comparison

If you have a UserService with a getName method:

Using standard ZIO Assertion (Ordered):

(mock.getName _).expects(argAssert("request")(_.id shouldBe 4)).returnsZIO("Agent Smith")

Using ScalaMock Matcher (Equivalent):

(mock.getName _).expects(hasField("id", _.id, equalTo(4))).returnsZIO("Agent Smith")

// Using a ZIO assertion directly in an expectation
(mock.getName _).expects(assertion).returnsZIO("Agent Smith")

// For inAnyOrder, use allowUnorderedCalls
(mock.getName _).expects(assertion.allowUnorderedCalls).inAnyOrder.returnsZIO("Agent Smith")

When using ScalaMock with ZIO, you can use StubbedZIOMethod to configure stubbed behavior (results, failures, etc.) and inspect call statistics directly within a ZIO effect. This is useful for integrating stub configuration into your test suites that run within the ZIO runtime.

Key Capabilities

• Set Results: Define what a method returns based on arguments or call count using ZIO effects.
• Simulate Failures: Use failsWith or diesWith to simulate error scenarios.
• Inspect Calls: Retrieve the number of times a method was called (timesZIO) or the list of arguments used (callsZIO) as ZIO effects.

Scala 2 vs Scala 3 Syntax

In Scala 3, you can access stubbed methods directly via the stub object. In Scala 2, you must use the underscore syntax (_) to convert the method to a function/stubbed method.

// Scala 3 Example
for
  _ <- foo.bar.returnsZIO((x, y) => ZIO.succeed(1))
  _ <- foo.bar(1, "foo")
  calls <- foo.bar.callsZIO
yield calls == List((1, "foo"))

// Scala 2 Example
for {
  _ <- (foo.bar _).returnsZIO((x, y) => ZIO.succeed(1))
  _ <- (foo.bar _)(1, "foo")
  calls <- (foo.bar _).callsZIO
} yield calls == List((1, "foo"))

The StubbedMethod[A, R] trait allows you to define how a mocked method should behave when called. A represents the type of arguments (often a tuple for multiple arguments) and R represents the return type.

In Scala 3, you can access a StubbedMethod directly from the stubbed trait. In Scala 2, you typically use the underscore syntax (e.g., foo.bar _) to convert a method to a StubbedMethod.

Setting Return Values

• returns(f: A => R): Sets a function that determines the result based on the input arguments.
• returnsWith(value: => R): Sets a constant return value (evaluated lazily).
• returnsOnCall(f: Int => R): Sets a result based on the call count (starting from 1).

Verifying Calls

• times: Int: Returns the total number of times the method was executed.
• times(args: A): Int: Returns the number of times the method was executed with specific arguments.
• calls: List[A]: Returns a list of all arguments used in each call, in order of execution.
• isBefore(other): Returns true if this method was called before the other method.
• isAfter(other): Returns true if this method was called after the other method.

// Scala 3 usage
foo.fooBar.returns {
  case (true, "bar") => "true"
  case _ => "false"
}

// Scala 2 usage
(foo.fooBar _).returns {
  case (true, "bar") => "true"
  case _ => "false"
}

Use these methods to define what a stubbed method returns when it is called, specifically when the return type R is an IO type.

// Scala 3
for
  _ <- foo.bar.returnsIO((x, y) => IO(1)) // Using function
  _ <- foo.bar.returnsIOWith(IO(1))        // Using value
  _ <- foo.bar.succeedsWith(1)             // Using succeedsWith
  _ <- foo.bar.returnsIOOnCall {            // Using call number
    case 1 | 2 => IO(0)
    case _ => IO(1)
  }
yield ()