Helper class used by code generated by the assert macro.
Class used via an implicit conversion to enable two objects to be compared with
=== and !== with a Boolean result and an enforced type constraint between
two object types.
Class used via an implicit conversion to enable any two objects to be compared with
=== and !== with a Boolean result and no enforced type constraint between
two object types.
Class used via an implicit conversion to enable any two objects to be compared with
=== and !== with an Option[String] result and an enforced type constraint between
two object types.
Class used via an implicit conversion to enable any two objects to be compared with
=== and !== with an Option[String] result and no enforced type constraint between
two object types.
Returns a TripleEqualsInvocationOnSpread[T], given an Spread[T], to facilitate
the “<left> should !== (<pivot> +- <tolerance>)”
syntax of Matchers.
Returns a TripleEqualsInvocationOnSpread[T], given an Spread[T], to facilitate
the “<left> should !== (<pivot> +- <tolerance>)”
syntax of Matchers.
the Spread[T] against which to compare the left-hand value
a TripleEqualsInvocationOnSpread wrapping the passed Spread[T] value, with
expectingEqual set to false.
Returns a TripleEqualsInvocation[Null], given a null reference, to facilitate
the “<left> should !== null” syntax
of Matchers.
Returns a TripleEqualsInvocation[Null], given a null reference, to facilitate
the “<left> should !== null” syntax
of Matchers.
a null reference
a TripleEqualsInvocation wrapping the passed null value, with expectingEqual
set to false.
Returns a TripleEqualsInvocation[T], given an object of type T, to facilitate
the “<left> should !== <right>” syntax
of Matchers.
Returns a TripleEqualsInvocation[T], given an object of type T, to facilitate
the “<left> should !== <right>” syntax
of Matchers.
the right-hand side value for an equality assertion
a TripleEqualsInvocation wrapping the passed right value, with expectingEqual
set to false.
Returns a TripleEqualsInvocationOnSpread[T], given an Spread[T], to facilitate
the “<left> should === (<pivot> +- <tolerance>)”
syntax of Matchers.
Returns a TripleEqualsInvocationOnSpread[T], given an Spread[T], to facilitate
the “<left> should === (<pivot> +- <tolerance>)”
syntax of Matchers.
the Spread[T] against which to compare the left-hand value
a TripleEqualsInvocationOnSpread wrapping the passed Spread[T] value, with
expectingEqual set to true.
Returns a TripleEqualsInvocation[Null], given a null reference, to facilitate
the “<left> should === null” syntax
of Matchers.
Returns a TripleEqualsInvocation[Null], given a null reference, to facilitate
the “<left> should === null” syntax
of Matchers.
a null reference
a TripleEqualsInvocation wrapping the passed null value, with expectingEqual
set to true.
Returns a TripleEqualsInvocation[T], given an object of type T, to facilitate
the “<left> should === <right>” syntax
of Matchers.
Returns a TripleEqualsInvocation[T], given an object of type T, to facilitate
the “<left> should === <right>” syntax
of Matchers.
the right-hand side value for an equality assertion
a TripleEqualsInvocation wrapping the passed right value, with expectingEqual
set to true.
Assert that a boolean condition, described in String
message, is true.
Assert that a boolean condition, described in String
message, is true.
If the condition is true, this method returns normally.
Else, it throws TestFailedException with a helpful error message
appended with the String obtained by invoking toString on the
specified clue as the exception's detail message.
This method is implemented in terms of a Scala macro that will generate a more helpful error message for expressions of this form:
At this time, any other form of expression will just get a TestFailedException with message saying the given
expression was false. In the future, we will enhance this macro to give helpful error messages in more situations.
In ScalaTest 2.0, however, this behavior was sufficient to allow the === that returns Boolean,
not Option[String] to be the default in tests. This makes === consistent between tests and production
code. If you have pre-existing code you wrote under ScalaTest 1.x, in which you are expecting=== to return an
Option[String], use can get that behavior back by mixing in trait LegacyTripleEquals.
the boolean condition to assert
An objects whose toString method returns a message to include in a failure report.
if message is null.
if the condition is false.
Assert that a boolean condition is true.
Assert that a boolean condition is true.
If the condition is true, this method returns normally.
Else, it throws TestFailedException.
This method is implemented in terms of a Scala macro that will generate a more helpful error message for expressions of this form:
At this time, any other form of expression will get a TestFailedException with message saying the given
expression was false. In the future, we will enhance this macro to give helpful error messages in more situations.
In ScalaTest 2.0, however, this behavior was sufficient to allow the === that returns Boolean,
not Option[String] to be the default in tests. This makes === consistent between tests and production
code. If you have pre-existing code you wrote under ScalaTest 1.x, in which you are expecting=== to return an
Option[String], use can get that behavior back by mixing in trait LegacyTripleEquals.
the boolean condition to assert
if the condition is false.
Asserts that a given string snippet of code passes both the Scala parser and type checker.
Asserts that a given string snippet of code passes both the Scala parser and type checker.
You can use this to make sure a snippet of code compiles:
assertCompiles("val a: Int = 1")
Although assertCompiles is implemented with a macro that determines at compile time whether
the snippet of code represented by the passed string compiles, errors (i.e.,
snippets of code that do not compile) are reported as test failures at runtime.
the snippet of code that should compile
Asserts that a given string snippet of code does not pass either the Scala parser or type checker.
Asserts that a given string snippet of code does not pass either the Scala parser or type checker.
Often when creating libraries you may wish to ensure that certain arrangements of code that
represent potential “user errors” do not compile, so that your library is more error resistant.
ScalaTest's Assertions trait includes the following syntax for that purpose:
assertDoesNotCompile("val a: String = \"a string")
Although assertDoesNotCompile is implemented with a macro that determines at compile time whether
the snippet of code represented by the passed string doesn't compile, errors (i.e.,
snippets of code that do compile) are reported as test failures at runtime.
Note that the difference between assertTypeError and assertDoesNotCompile is
that assertDoesNotCompile will succeed if the given code does not compile for any reason,
whereas assertTypeError will only succeed if the given code does not compile because of
a type error. If the given code does not compile because of a syntax error, for example, assertDoesNotCompile
will return normally but assertTypeError will throw a TestFailedException.
the snippet of code that should not type check
Assert that the value passed as expected equals the value passed as actual.
Assert that the value passed as expected equals the value passed as actual.
If the actual value equals the expected value
(as determined by ==), assertResult returns
normally. Else, assertResult throws a
TestFailedException whose detail message includes the expected and actual values.
the expected value
the actual value, which should equal the passed expected value
if the passed actual value does not equal the passed expected value.
Assert that the value passed as expected equals the value passed as actual.
Assert that the value passed as expected equals the value passed as actual.
If the actual equals the expected
(as determined by ==), assertResult returns
normally. Else, if actual is not equal to expected, assertResult throws a
TestFailedException whose detail message includes the expected and actual values, as well as the String
obtained by invoking toString on the passed clue.
the expected value
An object whose toString method returns a message to include in a failure report.
the actual value, which should equal the passed expected value
if the passed actual value does not equal the passed expected value.
Asserts that a given string snippet of code does not pass the Scala type checker, failing if the given snippet does not pass the Scala parser.
Asserts that a given string snippet of code does not pass the Scala type checker, failing if the given snippet does not pass the Scala parser.
Often when creating libraries you may wish to ensure that certain arrangements of code that
represent potential “user errors” do not compile, so that your library is more error resistant.
ScalaTest's Assertions trait includes the following syntax for that purpose:
assertTypeError("val a: String = 1")
Although assertTypeError is implemented with a macro that determines at compile time whether
the snippet of code represented by the passed string type checks, errors (i.e.,
snippets of code that do type check) are reported as test failures at runtime.
Note that the difference between assertTypeError and assertDoesNotCompile is
that assertDoesNotCompile will succeed if the given code does not compile for any reason,
whereas assertTypeError will only succeed if the given code does not compile because of
a type error. If the given code does not compile because of a syntax error, for example, assertDoesNotCompile
will return normally but assertTypeError will throw a TestFailedException.
the snippet of code that should not type check
Helper instance used by code generated by macro assertion.
Assume that a boolean condition, described in String
message, is true.
Assume that a boolean condition, described in String
message, is true.
If the condition is true, this method returns normally.
Else, it throws TestCanceledException with a helpful error message
appended with String obtained by invoking toString on the
specified clue as the exception's detail message.
This method is implemented in terms of a Scala macro that will generate a more helpful error message for expressions of this form:
At this time, any other form of expression will just get a TestCanceledException with message saying the given
expression was false. In the future, we will enhance this macro to give helpful error messages in more situations.
In ScalaTest 2.0, however, this behavior was sufficient to allow the === that returns Boolean,
not Option[String] to be the default in tests. This makes === consistent between tests and production
code. If you have pre-existing code you wrote under ScalaTest 1.x, in which you are expecting=== to return an
Option[String], use can get that behavior back by mixing in trait LegacyTripleEquals.
the boolean condition to assume
An objects whose toString method returns a message to include in a failure report.
if message is null.
if the condition is false.
Assume that a boolean condition is true.
Assume that a boolean condition is true.
If the condition is true, this method returns normally.
Else, it throws TestCanceledException.
This method is implemented in terms of a Scala macro that will generate a more helpful error message for expressions of this form:
At this time, any other form of expression will just get a TestCanceledException with message saying the given
expression was false. In the future, we will enhance this macro to give helpful error messages in more situations.
In ScalaTest 2.0, however, this behavior was sufficient to allow the === that returns Boolean,
not Option[String] to be the default in tests. This makes === consistent between tests and production
code. If you have pre-existing code you wrote under ScalaTest 1.x, in which you are expecting=== to return an
Option[String], use can get that behavior back by mixing in trait LegacyTripleEquals.
the boolean condition to assume
if the condition is false.
Throws TestCanceledException, with the passed
Throwable cause, to indicate a test failed.
Throws TestCanceledException, with the passed
Throwable cause, to indicate a test failed.
The getMessage method of the thrown TestCanceledException
will return cause.toString.
a Throwable that indicates the cause of the cancellation.
if cause is null
Throws TestCanceledException, with the passed
String message as the exception's detail
message and Throwable cause, to indicate a test failed.
Throws TestCanceledException, with the passed
String message as the exception's detail
message and Throwable cause, to indicate a test failed.
A message describing the failure.
A Throwable that indicates the cause of the failure.
if message or cause is null
Throws TestCanceledException, with the passed
String message as the exception's detail
message, to indicate a test was canceled.
Throws TestCanceledException, with the passed
String message as the exception's detail
message, to indicate a test was canceled.
A message describing the cancellation.
if message is null
Throws TestCanceledException to indicate a test was canceled.
Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that B is
implicitly convertible to A, given an implicit Equivalence[A].
Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that B is
implicitly convertible to A, given an implicit Equivalence[A].
The returned Constraint's areEqual method uses the implicitly passed Equivalence[A]'s
areEquivalent method to determine equality.
This method is overridden and made implicit by subtraits
ConversionCheckedTripleEquals) and
ConversionCheckedLegacyTripleEquals, and
overriden as non-implicit by the other subtraits in this package.
an Equivalence[A] type class to which the Constraint.areEqual method will delegate to determine equality.
an implicit conversion from B to A
a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
the passed Equivalence[A].
Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
that A must be a subtype of B, given an explicit Equivalence[B].
Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
that A must be a subtype of B, given an explicit Equivalence[B].
This method is used to enable the Explicitly DSL for
TypeCheckedTripleEquals by requiring an explicit Equivalance[B], but
taking an implicit function that provides evidence that A is a subtype of B.
The returned Constraint's areEqual method uses the implicitly passed Equivalence[B]'s
areEquivalent method to determine equality.
This method is overridden and made implicit by subtraits
LowPriorityTypeCheckedConstraint (extended by
TypeCheckedTripleEquals), and
LowPriorityTypeCheckedLegacyConstraint (extended by
TypeCheckedLegacyTripleEquals), and
overriden as non-implicit by the other subtraits in this package.
an Equivalence[B] type class to which the Constraint.areEqual method
will delegate to determine equality.
evidence that A is a subype of B
a Constraint[A, B] whose areEqual method delegates to the
areEquivalent method of the passed Equivalence[B].
Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that A is
implicitly convertible to B, given an explicit Equivalence[B].
Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that A is
implicitly convertible to B, given an explicit Equivalence[B].
This method is used to enable the Explicitly DSL for
ConversionCheckedTripleEquals by requiring an explicit Equivalance[B], but
taking an implicit function that converts from A to B.
The returned Constraint's areEqual method uses the implicitly passed Equivalence[B]'s
areEquivalent method to determine equality.
This method is overridden and made implicit by subtraits
LowPriorityConversionCheckedConstraint (extended by
ConversionCheckedTripleEquals), and
LowPriorityConversionCheckedLegacyConstraint (extended by
ConversionCheckedLegacyTripleEquals), and
overriden as non-implicit by the other subtraits in this package.
a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
the passed Equivalence[B].
Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
that B must be a subtype of A, given an explicit Equivalence[A].
Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
that B must be a subtype of A, given an explicit Equivalence[A].
This method is used to enable the Explicitly DSL for
TypeCheckedTripleEquals by requiring an explicit Equivalance[B], but
taking an implicit function that provides evidence that A is a subtype of B. For example, under TypeCheckedTripleEquals,
this method (as an implicit method), would be used to compile this statement:
def closeEnoughTo1(num: Double): Boolean = (num === 1.0)(decided by forgivingEquality)
The returned Constraint's areEqual method uses the implicitly passed Equivalence[A]'s
areEquivalent method to determine equality.
This method is overridden and made implicit by subtraits
TypeCheckedTripleEquals) and
TypeCheckedLegacyTripleEquals, and
overriden as non-implicit by the other subtraits in this package.
evidence that B is a subype of A
a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
the passed Equivalence[A].
Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that B is
implicitly convertible to A, given an explicit Equivalence[A].
Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that B is
implicitly convertible to A, given an explicit Equivalence[A].
This method is used to enable the Explicitly DSL for
ConversionCheckedTripleEquals by requiring an explicit Equivalance[A], but
taking an implicit function that converts from B to A. For example, under ConversionCheckedTripleEquals,
this method (as an implicit method), would be used to compile this statement:
def closeEnoughTo1(num: Double): Boolean = (num === 1.0)(decided by forgivingEquality)
The returned Constraint's areEqual method uses the implicitly passed Equivalence[A]'s
areEquivalent method to determine equality.
This method is overridden and made implicit by subtraits
ConversionCheckedTripleEquals) and
ConversionCheckedLegacyTripleEquals, and
overriden as non-implicit by the other subtraits in this package.
an Equivalence[A] type class to which the Constraint.areEqual method will delegate to determine equality.
a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
the passed Equivalence[A].
Converts to an CheckingEqualizer that provides === and !== operators
that result in Boolean and enforce a type constraint.
Converts to an CheckingEqualizer that provides === and !== operators
that result in Boolean and enforce a type constraint.
This method is overridden and made implicit by subtraits TypeCheckedTripleEquals and
ConversionCheckedTripleEquals, and overriden as
non-implicit by the other subtraits in this package.
the object whose type to convert to CheckingEqualizer.
if left is null.
Converts to an Equalizer that provides === and !== operators that
result in Boolean and enforce no type constraint.
Converts to an Equalizer that provides === and !== operators that
result in Boolean and enforce no type constraint.
This method is overridden and made implicit by subtrait TripleEquals and overriden as non-implicit by the other
subtraits in this package.
the object whose type to convert to Equalizer.
if left is null.
Converts to a LegacyCheckingEqualizer that provides === and !== operators
that result in Option[String] and enforce a type constraint.
Converts to a LegacyCheckingEqualizer that provides === and !== operators
that result in Option[String] and enforce a type constraint.
This method is overridden and made implicit by subtraits TypeCheckedLegacyTripleEquals
and ConversionCheckedLegacyTripleEquals, and
overriden as non-implicit by the other subtraits in this package.
the object whose type to convert to LegacyCheckingEqualizer.
if left is null.
Converts to a LegacyEqualizer that provides === and !== operators that
result in Option[String] and enforce no type constraint.
Converts to a LegacyEqualizer that provides === and !== operators that
result in Option[String] and enforce no type constraint.
This method is overridden and made implicit by subtrait LegacyTripleEquals and overriden as non-implicit
by the other subtraits in this package.
the object whose type to convert to LegacyEqualizer.
if left is null.
Returns an Equality[A] for any type A that determines equality
by first calling .deep on any Array (on either the left or right side),
then comparing the resulting objects with ==.
Returns an Equality[A] for any type A that determines equality
by first calling .deep on any Array (on either the left or right side),
then comparing the resulting objects with ==.
a default Equality for type A
Throws TestFailedException, with the passed
Throwable cause, to indicate a test failed.
Throws TestFailedException, with the passed
Throwable cause, to indicate a test failed.
The getMessage method of the thrown TestFailedException
will return cause.toString.
a Throwable that indicates the cause of the failure.
if cause is null
Throws TestFailedException, with the passed
String message as the exception's detail
message and Throwable cause, to indicate a test failed.
Throws TestFailedException, with the passed
String message as the exception's detail
message and Throwable cause, to indicate a test failed.
A message describing the failure.
A Throwable that indicates the cause of the failure.
if message or cause is null
Throws TestFailedException, with the passed
String message as the exception's detail
message, to indicate a test failed.
Throws TestFailedException, with the passed
String message as the exception's detail
message, to indicate a test failed.
A message describing the failure.
if message is null
Throws TestFailedException to indicate a test failed.
Intercept and return an exception that's expected to be thrown by the passed function value.
Intercept and return an exception that's expected to
be thrown by the passed function value. The thrown exception must be an instance of the
type specified by the type parameter of this method. This method invokes the passed
function. If the function throws an exception that's an instance of the specified type,
this method returns that exception. Else, whether the passed function returns normally
or completes abruptly with a different exception, this method throws TestFailedException.
Note that the type specified as this method's type parameter may represent any subtype of
AnyRef, not just Throwable or one of its subclasses. In
Scala, exceptions can be caught based on traits they implement, so it may at times make sense
to specify a trait that the intercepted exception's class must mix in. If a class instance is
passed for a type that could not possibly be used to catch an exception (such as String,
for example), this method will complete abruptly with a TestFailedException.
the function value that should throw the expected exception
an implicit Manifest representing the type of the specified
type parameter.
the intercepted exception, if it is of the expected type
if the passed function does not complete abruptly with an exception
that's an instance of the specified type
passed expected value.
Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that A is
implicitly convertible to B, given an implicit Equivalence[B].
Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that A is
implicitly convertible to B, given an implicit Equivalence[B].
The returned Constraint's areEqual method uses the implicitly passed Equivalence[B]'s
areEquivalent method to determine equality.
This method is overridden and made implicit by subtraits
LowPriorityConversionCheckedConstraint (extended by
ConversionCheckedTripleEquals), and
LowPriorityConversionCheckedLegacyConstraint (extended by
ConversionCheckedLegacyTripleEquals), and
overriden as non-implicit by the other subtraits in this package.
an implicit conversion from A to B
a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
the passed Equivalence[B].
Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
that A must be a subtype of B, given an implicit Equivalence[B].
Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
that A must be a subtype of B, given an implicit Equivalence[B].
The returned Constraint's areEqual method uses the implicitly passed Equivalence[A]'s
areEquivalent method to determine equality.
This method is overridden and made implicit by subtraits
LowPriorityTypeCheckedConstraint (extended by
TypeCheckedTripleEquals), and
LowPriorityTypeCheckedLegacyConstraint (extended by
TypeCheckedLegacyTripleEquals), and
overriden as non-implicit by the other subtraits in this package.
an Equivalence[B] type class to which the Constraint.areEqual method
will delegate to determine equality.
evidence that A is a subype of B
a Constraint[A, B] whose areEqual method delegates to the
areEquivalent method of the passed Equivalence[B].
Trap and return any thrown exception that would normally cause a ScalaTest test to fail, or create and return a new RuntimeException
indicating no exception is thrown.
Trap and return any thrown exception that would normally cause a ScalaTest test to fail, or create and return a new RuntimeException
indicating no exception is thrown.
This method is intended to be used in the Scala interpreter to eliminate large stack traces when trying out ScalaTest assertions and
matcher expressions. It is not intended to be used in regular test code. If you want to ensure that a bit of code throws an expected
exception, use intercept, not trap. Here's an example interpreter session without trap:
scala> import org.scalatest._ import org.scalatest._scala> import Matchers._ import Matchers._
scala> val x = 12 a: Int = 12
scala> x shouldEqual 13 org.scalatest.exceptions.TestFailedException: 12 did not equal 13 at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:449) at org.scalatest.Assertions$.newAssertionFailedException(Assertions.scala:1203) at org.scalatest.Assertions$AssertionsHelper.macroAssertTrue(Assertions.scala:417) at .<init>(<console>:15) at .<clinit>(<console>) at .<init>(<console>:7) at .<clinit>(<console>) at $print(<console>) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) at java.lang.reflect.Method.invoke(Method.java:597) at scala.tools.nsc.interpreter.IMain$ReadEvalPrint.call(IMain.scala:731) at scala.tools.nsc.interpreter.IMain$Request.loadAndRun(IMain.scala:980) at scala.tools.nsc.interpreter.IMain.loadAndRunReq$1(IMain.scala:570) at scala.tools.nsc.interpreter.IMain.interpret(IMain.scala:601) at scala.tools.nsc.interpreter.IMain.interpret(IMain.scala:565) at scala.tools.nsc.interpreter.ILoop.reallyInterpret$1(ILoop.scala:745) at scala.tools.nsc.interpreter.ILoop.interpretStartingWith(ILoop.scala:790) at scala.tools.nsc.interpreter.ILoop.command(ILoop.scala:702) at scala.tools.nsc.interpreter.ILoop.processLine$1(ILoop.scala:566) at scala.tools.nsc.interpreter.ILoop.innerLoop$1(ILoop.scala:573) at scala.tools.nsc.interpreter.ILoop.loop(ILoop.scala:576) at scala.tools.nsc.interpreter.ILoop$$anonfun$process$1.apply$mcZ$sp(ILoop.scala:867) at scala.tools.nsc.interpreter.ILoop$$anonfun$process$1.apply(ILoop.scala:822) at scala.tools.nsc.interpreter.ILoop$$anonfun$process$1.apply(ILoop.scala:822) at scala.tools.nsc.util.ScalaClassLoader$.savingContextLoader(ScalaClassLoader.scala:135) at scala.tools.nsc.interpreter.ILoop.process(ILoop.scala:822) at scala.tools.nsc.MainGenericRunner.runTarget$1(MainGenericRunner.scala:83) at scala.tools.nsc.MainGenericRunner.process(MainGenericRunner.scala:96) at scala.tools.nsc.MainGenericRunner$.main(MainGenericRunner.scala:105) at scala.tools.nsc.MainGenericRunner.main(MainGenericRunner.scala)
That's a pretty tall stack trace. Here's what it looks like when you use trap:
scala> trap { x shouldEqual 13 }
res1: Throwable = org.scalatest.exceptions.TestFailedException: 12 did not equal 13
Much less clutter. Bear in mind, however, that if no exception is thrown by the
passed block of code, the trap method will create a new NormalResult
(a subclass of Throwable made for this purpose only) and return that. If the result was the Unit value, it
will simply say that no exception was thrown:
scala> trap { x shouldEqual 12 }
res2: Throwable = No exception was thrown.
If the passed block of code results in a value other than Unit, the NormalResult's toString will print the value:
scala> trap { "Dude!" }
res3: Throwable = No exception was thrown. Instead, result was: "Dude!"
Although you can access the result value from the NormalResult, its type is Any and therefore not
very convenient to use. It is not intended that trap be used in test code. The sole intended use case for trap is decluttering
Scala interpreter sessions by eliminating stack traces when executing assertion and matcher expressions.
Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
that B must be a subtype of A, given an implicit Equivalence[A].
Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
that B must be a subtype of A, given an implicit Equivalence[A].
The returned Constraint's areEqual method uses the implicitly passed Equivalence[A]'s
areEquivalent method to determine equality.
This method is overridden and made implicit by subtraits
TypeCheckedTripleEquals) and
TypeCheckedLegacyTripleEquals, and
overriden as non-implicit by the other subtraits in this package.
evidence that B is a subype of A
a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
the passed Equivalence[A].
Provides a Constraint[A, B] class for any two types A and B, with no type constraint enforced, given an
implicit Equality[A].
Provides a Constraint[A, B] class for any two types A and B, with no type constraint enforced, given an
implicit Equality[A].
The returned Constraint's areEqual method uses the implicitly passed Equality[A]'s
areEqual method to determine equality.
This method is overridden and made implicit by subtraits TripleEquals and
LegacyTripleEquals, and
overriden as non-implicit by the other subtraits in this package.
an Equality[A] type class to which the Constraint.areEqual method will delegate to determine equality.
a Constraint[A, B] whose areEqual method delegates to the areEqual method of
the passed Equality[A].
Executes the block of code passed as the second parameter, and, if it
completes abruptly with a ModifiableMessage exception,
prepends the "clue" string passed as the first parameter to the beginning of the detail message
of that thrown exception, then rethrows it.
Executes the block of code passed as the second parameter, and, if it
completes abruptly with a ModifiableMessage exception,
prepends the "clue" string passed as the first parameter to the beginning of the detail message
of that thrown exception, then rethrows it. If clue does not end in a white space
character, one space will be added
between it and the existing detail message (unless the detail message is
not defined).
This method allows you to add more information about what went wrong that will be reported when a test fails. Here's an example:
withClue("(Employee's name was: " + employee.name + ")") { intercept[IllegalArgumentException] { employee.getTask(-1) } }
If an invocation of intercept completed abruptly with an exception, the resulting message would be something like:
(Employee's name was Bob Jones) Expected IllegalArgumentException to be thrown, but no exception was thrown
if the passed clue is null
Assert that an Option[String] is None.
Assert that an Option[String] is None.
If the condition is None, this method returns normally.
Else, it throws TestFailedException with the String
value of the Some included in the TestFailedException's
detail message.
This form of assert is usually called in conjunction with an
implicit conversion to Equalizer, using a === comparison, as in:
assert(a === b)
For more information on how this mechanism works, see the documentation for
Equalizer.
the Option[String] to assert
This method has been deprecated in favor of macro assertion and will be removed in a future version of ScalaTest. If you need this, please copy the source code into your own trait instead.
if the Option[String] is Some.
Assert that an Option[String] is None.
Assert that an Option[String] is None.
If the condition is None, this method returns normally.
Else, it throws TestFailedException with the String
value of the Some, as well as the
String obtained by invoking toString on the
specified clue,
included in the TestFailedException's detail message.
This form of assert is usually called in conjunction with an
implicit conversion to Equalizer, using a === comparison, as in:
assert(a === b, "extra info reported if assertion fails")
For more information on how this mechanism works, see the documentation for
Equalizer.
the Option[String] to assert
An object whose toString method returns a message to include in a failure report.
This method has been deprecated in favor of macro assertion and will be removed in a future version of ScalaTest. If you need this, please copy the source code into your own trait instead.
if message is null.
if the Option[String] is Some.
Assume that an Option[String] is None.
Assume that an Option[String] is None.
If the condition is None, this method returns normally.
Else, it throws TestCanceledException with the String
value of the Some included in the TestCanceledException's
detail message.
This form of assume is usually called in conjunction with an
implicit conversion to Equalizer, using a === comparison, as in:
assume(a === b)
For more information on how this mechanism works, see the documentation for
Equalizer.
the Option[String] to assert
This method has been deprecated in favor of macro assumption and will be removed in a future version of ScalaTest. If you need this, please copy the source code into your own trait instead.
if the Option[String] is Some.
Assume that an Option[String] is None.
Assume that an Option[String] is None.
If the condition is None, this method returns normally.
Else, it throws TestCanceledException with the String
value of the Some, as well as the
String obtained by invoking toString on the
specified clue,
included in the TestCanceledException's detail message.
This form of assume is usually called in conjunction with an
implicit conversion to Equalizer, using a === comparison, as in:
assume(a === b, "extra info reported if assertion fails")
For more information on how this mechanism works, see the documentation for
Equalizer.
the Option[String] to assert
An object whose toString method returns a message to include in a failure report.
This method has been deprecated in favor of macro assumption and will be removed in a future version of ScalaTest. If you need this, please copy the source code into your own trait instead.
if message is null.
if the Option[String] is Some.
This expect method has been deprecated; Please use assertResult instead.
This expect method has been deprecated; Please use assertResult instead.
To get rid of the deprecation warning, simply replace expect with
assertResult. The name expect will be used for a different purposes in
a future version of ScalaTest.
This expect method has been deprecated. Please replace all invocations of expect with an identical invocation of assertResult instead.
This expect method has been deprecated; Please use assertResult instead.
This expect method has been deprecated; Please use assertResult instead.
To get rid of the deprecation warning, simply replace expect with
assertResult. The name expect will be used for a different purposes in
a future version of ScalaTest.
This expect method has been deprecated. Please replace all invocations of expect with an identical invocation of assertResult instead.
This expectResult method has been deprecated; Please use assertResult instead.
This expectResult method has been deprecated; Please use assertResult instead.
To get rid of the deprecation warning, simply replace expectResult with
assertResult. The name expectResult will be used for a different purposes in
a future version of ScalaTest.
This expectResult method has been deprecated. Please replace all invocations of expectResult with an identical invocation of assertResult instead.
This expectResult method has been deprecated; Please use assertResult instead.
This expectResult method has been deprecated; Please use assertResult instead.
To get rid of the deprecation warning, simply replace expectResult with
assertResult. The name expectResult will be used for a different purposes in
a future version of ScalaTest.
This expectResult method has been deprecated. Please replace all invocations of expectResult with an identical invocation of assertResult instead.
Trait that contains ScalaTest's basic assertion methods.
You can use the assertions provided by this trait in any ScalaTest
Suite, becauseSuitemixes in this trait. This trait is designed to be used independently of anything else in ScalaTest, though, so you can mix it into anything. (You can alternatively import the methods defined in this trait. For details, see the documentation for theAssertionscompanion object.In any Scala program, you can write assertions by invoking
assertand passing in aBooleanexpression, such as:If the passed expression is
true,assertwill return normally. Iffalse, Scala'sassertwill complete abruptly with anAssertionError. This behavior is provided by theassertmethod defined in objectPredef, whose members are implicitly imported into every Scala source file. ThisAssertionstrait defines anotherassertmethod that hides the one inPredef. It behaves the same, except that iffalseis passed it throwsTestFailedExceptioninstead ofAssertionError. Why? Because unlikeAssertionError,TestFailedExceptioncarries information about exactly which item in the stack trace represents the line of test code that failed, which can help users more quickly find an offending line of code in a failing test.If you pass the previous
Booleanexpression,left == righttoassertin a ScalaTest test, a failure will be reported that, becauseassertis implemented as a macro, includes reporting the left and right values.For example, given the same code as above but using ScalaTest assertions:
The detail message in the thrown
TestFailedExceptionfrom thisassertwill be: "2 did not equal 1".ScalaTest's
assertmacro works by recognizing patterns in the AST of the expression passed toassertand, for a finite set of common expressions, giving an error message that an equivalent ScalaTest matcher expression would give. Here are some examples, whereais 1,bis 2,cis 3,dis 4,xsisList(a, b, c), andnumis 1.0:For expressions that are not recognized, the macro currently prints out a string representation of the (desugared) AST and adds
"was false". Here are some examples of error messages for unrecognized expressions:You can augment the standard error message by providing a
Stringas a second argument toassert, like this:Using this form of
assert, the failure report will be more specific to your problem domain, thereby helping you debug the problem. ThisAssertionstrait also mixes in theTripleEquals, which gives you a===operator that allows you to customizeEquality, perform equality checks with numericTolerance, and enforce type constraints at compile time with sibling traitsTypeCheckedTripleEqualsandConversionCheckedTripleEquals.Expected results
Although the
assertmacro provides a natural, readable extension to Scala'sassertmechanism that provides good error messages, as the operands become lengthy, the code becomes less readable. In addition, the error messages generated for==and===comparisons don't distinguish between actual and expected values. The operands are just calledleftandright, because if one were namedexpectedand the otheractual, it would be difficult for people to remember which was which. To help with these limitations of assertions,Suiteincludes a method calledassertResultthat can be used as an alternative toassert. To useassertResult, you place the expected value in parentheses afterassertResult, followed by curly braces containing code that should result in the expected value. For example:In this case, the expected value is
2, and the code being tested isa - b. This assertion will fail, and the detail message in theTestFailedExceptionwill read, "Expected 2, but got 3."Forcing failures
If you just need the test to fail, you can write:
Or, if you want the test to fail with a message, write:
fail("I've got a bad feeling about this")Intercepted exceptions
Sometimes you need to test whether a method throws an expected exception under certain circumstances, such as when invalid arguments are passed to the method. You can do this in the JUnit 3 style, like this:
If
charAtthrowsIndexOutOfBoundsExceptionas expected, control will transfer to the catch case, which does nothing. If, however,charAtfails to throw an exception, the next statement,fail(), will be run. Thefailmethod always completes abruptly with aTestFailedException, thereby signaling a failed test.To make this common use case easier to express and read, ScalaTest provides an
interceptmethod. You use it like this:This code behaves much like the previous example. If
charAtthrows an instance ofIndexOutOfBoundsException,interceptwill return that exception. But ifcharAtcompletes normally, or throws a different exception,interceptwill complete abruptly with aTestFailedException.interceptreturns the caught exception so that you can inspect it further if you wish, for example, to ensure that data contained inside the exception has the expected values.Checking that a snippet of code does or does not compile
Often when creating libraries you may wish to ensure that certain arrangements of code that represent potential “user errors” do not compile, so that your library is more error resistant. ScalaTest's
Assertionstrait includes the following syntax for that purpose:assertDoesNotCompile("val a: String = 1")If you want to ensure that a snippet of code does not compile because of a type error (as opposed to a syntax error), use:
assertTypeError("val a: String = 1")Note that the
assertTypeErrorcall will only succeed if the given snippet of code does not compile because of a type error. A syntax error will still result on a thrownTestFailedException.If you want to state that a snippet of code does compile, you can make that more obvious with:
assertCompiles("val a: Int = 1")Although the previous three constructs are implemented with macros that determine at compile time whether the snippet of code represented by the string does or does not compile, errors are reported as test failures at runtime.
Assumptions
Trait
Assertionsalso provides methods that allow you to cancel a test. You would cancel a test if a resource required by the test was unavailable. For example, if a test requires an external database to be online, and it isn't, the test could be canceled to indicate it was unable to run because of the missing database. Such a test assumes a database is available, and you can use theassumemethod to indicate this at the beginning of the test, like this:For each overloaded
assertmethod, traitAssertionsprovides an overloadedassumemethod with an identical signature and behavior, except theassumemethods throwTestCanceledExceptionwhereas theassertmethods throwTestFailedException. As withassert,assumehides a Scala method inPredefthat performs a similar function, but throwsAssertionError. And just as you can withassert, you will get an error message extracted by a macro from the AST passed toassume, and can optionally provide a clue string to augment this error message. Here are some examples:Forcing cancelations
For each overloaded
failmethod, there's a correspondingcancelmethod with an identical signature and behavior, except thecancelmethods throwTestCanceledExceptionwhereas thefailmethods throwTestFailedException. Thus if you just need to cancel a test, you can write:If you want to cancel the test with a message, just place the message in the parentheses:
cancel("Can't run the test because no internet connection was found")Getting a clue
If you want more information that is provided by default by the methods if this trait, you can supply a "clue" string in one of several ways. The extra information (or "clues") you provide will be included in the detail message of the thrown exception. Both
assertandassertResultprovide a way for a clue to be included directly,interceptdoes not. Here's an example of clues provided directly inassert:and in
assertResult:The exceptions thrown by the previous two statements will include the clue string,
"this is a clue", in the exception's detail message. To get the same clue in the detail message of an exception thrown by a failedinterceptcall requires usingwithClue:The
withCluemethod will only prepend the clue string to the detail message of exception types that mix in theModifiableMessagetrait. See the documentation forModifiableMessagefor more information. If you wish to place a clue string after a block of code, see the documentation forAppendedClues.Note: ScalaTest's
assertTypeErrorconstruct is in part inspired by theillTypedmacro of shapeless.