ScalaTest 1.0
|
|
org/scalatest/Assertions.scala
]
trait
Assertions
extends
AnyRef
You can use the assertions provided by this trait in any ScalaTest Suite
, because Suite
mixes 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 the Assertions
companion object.
In any Scala program, you can write assertions by invoking assert
and passing in a Boolean
expression,
such as:
val left = 2 val right = 1 assert(left == right)
If the passed expression is true
, assert
will return normally. If false
,
assert
will complete abruptly with an AssertionError
. This behavior is provided by
the assert
method defined in object Predef
, whose members are implicitly imported into every
Scala source file. This Assertions
traits defines another assert
method that hides the
one in Predef
. It behaves the same, except that if false
is passed it throws
TestFailedException
instead of AssertionError
. The reason it throws TestFailedException
is because TestFailedException
carries 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 Boolean
expression, left == right
to assert
in a ScalaTest test, a failure
will be reported, but without reporting the left and right values. You can alternatively encode these values in a String
passed as
a second argument to assert
, like this:
val left = 2 val right = 1 assert(left == right, left + " did not equal " + right)
Using this form of assert
, the failure report will include the left and right values, thereby
helping you debug the problem. However, ScalaTest provides the ===
operator to make this easier.
You use it like this:
val left = 2 val right = 1 assert(left === right)
Because you use ===
here instead of ==
, the failure report will include the left
and right values. For example, the detail message in the thrown TestFailedException
from the assert
shown previously will include, "2 did not equal 1".
From this message you will know that the operand on the left had the value 2, and the operand on the right had the value 1.
If you're familiar with JUnit, you would use ===
in a ScalaTest Suite
where you'd use assertEquals
in a JUnit TestCase
.
The ===
operator is made possible by an implicit conversion from Any
to Equalizer
. If you're curious to understand the mechanics, see the documentation for
Equalizer
and the convertToEqualizer
method.
Expected results
Although===
provides a natural, readable extension to Scala's assert
mechanism,
as the operands become lengthy, the code becomes less readable. In addition, the ===
comparison
doesn't distinguish between actual and expected values. The operands are just called left
and right
,
because if one were named expected
and the other actual
, it would be difficult for people to
remember which was which. To help with these limitations of assertions, Suite
includes a method called expect
that
can be used as an alternative to assert
with ===
. To use expect
, you place
the expected value in parentheses after expect
, followed by curly braces containing code
that should result in the expected value. For example:
val a = 5 val b = 2 expect(2) { a - b }
In this case, the expected value is 2
, and the code being tested is a - b
. This expectation will fail, and
the detail message in the TestFailedException
will read, "Expected 2, but got 3."
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:
val s = "hi" try { s.charAt(-1) fail() } catch { case _: IndexOutOfBoundsException => // Expected, so continue }
If charAt
throws IndexOutOfBoundsException
as expected, control will transfer
to the catch case, which does nothing. If, however, charAt
fails to throw an exception,
the next statement, fail()
, will be run. The fail
method always completes abruptly with
a TestFailedException
, thereby signaling a failed test.
To make this common use case easier to express and read, ScalaTest provides an intercept
method. You use it like this:
val s = "hi" intercept[IndexOutOfBoundsException] { s.charAt(-1) }
This code behaves much like the previous example. If charAt
throws an instance of IndexOutOfBoundsException
,
intercept
will return that exception. But if charAt
completes normally, or throws a different
exception, intercept
will complete abruptly with a TestFailedException
. intercept
returns 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.
Method Summary | |
def
|
assert
(condition : Boolean, clue : Any) : Unit
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 the
String obtained by invoking toString on the
specified message as the exception's detail message. |
def
|
assert
(o : scala.Option[java.lang.String]) : Unit
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. |
def
|
assert
(condition : Boolean) : Unit
Assert that a boolean condition is true.
If the condition is
true , this method returns normally.
Else, it throws TestFailedException . |
def
|
assert
(o : scala.Option[java.lang.String], clue : Any) : Unit
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 message ,
included in the TestFailedException 's detail message. |
implicit def
|
convertToEqualizer
(left : Any) : Equalizer
Implicit conversion from
Any to Equalizer , used to enable
assertions with === comparisons. |
def
|
expect
(expected : Any)(actual : Any) : Unit
Expect that the value passed as
expected equals the value passed as actual .
If the actual value equals the expected value
(as determined by == ), expect returns
normally. Else, expect throws an
TestFailedException whose detail message includes the expected and actual values. |
def
|
expect
(expected : Any, clue : Any)(actual : Any) : Unit
Expect that the value passed as
expected equals the value passed as actual .
If the actual equals the expected
(as determined by == ), expect returns
normally. Else, if actual is not equal to expected , expect throws an
TestFailedException whose detail message includes the expected and actual values, as well as the String
obtained by invoking toString on the passed message . |
def
|
fail
: Nothing
Throws
TestFailedException to indicate a test failed. |
def
|
fail
(message : java.lang.String) : Nothing
Throws
TestFailedException , with the passed
String message as the exception's detail
message, to indicate a test failed. |
def
|
fail
(message : java.lang.String, cause : java.lang.Throwable) : Nothing
Throws
TestFailedException , with the passed
String message as the exception's detail
message and Throwable cause, to indicate a test failed. |
def
|
fail
(cause : java.lang.Throwable) : Nothing
Throws
TestFailedException , with the passed
Throwable cause, to indicate a test failed.
The getMessage method of the thrown TestFailedException
will return cause.toString() . |
def
|
intercept
[T <: AnyRef](f : => Any)(implicit manifest : scala.reflect.Manifest[T]) : T
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 . |
Methods inherited from AnyRef | |
getClass, hashCode, equals, clone, toString, notify, notifyAll, wait, wait, wait, finalize, ==, !=, eq, ne, synchronized |
Methods inherited from Any | |
==, !=, isInstanceOf, asInstanceOf |
Class Summary | |
final class
|
Equalizer
(left : Any) extends AnyRef
Class used via an implicit conversion to enable any two objects to be compared with
=== in assertions in tests. For example:
assert(a === b) |
Method Details |
true
, this method returns normally.
Else, it throws TestFailedException
.condition -
the boolean condition to assertTestFailedException -
if the condition is false
.String
message
, is true.
If the condition is true
, this method returns normally.
Else, it throws TestFailedException
with the
String
obtained by invoking toString
on the
specified message
as the exception's detail message.condition -
the boolean condition to assertclue -
An objects whose toString
method returns a message to include in a failure report.TestFailedException -
if the condition is false
.NullPointerException -
if message
is null
.
def
assert(o : scala.Option[java.lang.String], clue : Any) : Unit
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 message
,
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
.
o -
the Option[String]
to assertclue -
An objects whose toString
method returns a message to include in a failure report.TestFailedException -
if the Option[String]
is Some
.NullPointerException -
if message
is null
.
def
assert(o : scala.Option[java.lang.String]) : Unit
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
.
o -
the Option[String]
to assertTestFailedException -
if the Option[String]
is Some
.Any
to Equalizer
, used to enable
assertions with ===
comparisons.
For more information on this mechanism, see the documentation for Equalizer.
Because trait Suite
mixes in Assertions
, this implicit conversion will always be
available by default in ScalaTest Suite
s. This is the only implicit conversion that is in scope by default in every
ScalaTest Suite
. Other implicit conversions offered by ScalaTest, such as those that support the matchers DSL
or invokePrivate
, must be explicitly invited into your test code, either by mixing in a trait or importing the
members of its companion object. The reason ScalaTest requires you to invite in implicit conversions (with the exception of the
implicit conversion for ===
operator) is because if one of ScalaTest's implicit conversions clashes with an
implicit conversion used in the code you are trying to test, your program won't compile. Thus there is a chance that if you
are ever trying to use a library or test some code that also offers an implicit conversion involving a ===
operator,
you could run into the problem of a compiler error due to an ambiguous implicit conversion. If that happens, you can turn off
the implicit conversion offered by this convertToEqualizer
method simply by overriding the method in your
Suite
subclass, but not marking it as implicit:
// In your Suite subclass override def convertToEqualizer(left: Any) = new Equalizer(left)
left -
the object whose type to convert to Equalizer
.NullPointerException -
if left
is null
.
def
intercept[T <: AnyRef](f : => Any)(implicit
manifest : scala.reflect.Manifest[T]) : T
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
.
f -
the function value that should throw the expected exceptionmanifest -
an implicit Manifest
representing the type of the specified type parameter.TestFailedException -
if the passed function does not complete abruptly with an exception that's an instance of the specified type
passed expected
value.expected
equals the value passed as actual
.
If the actual
equals the expected
(as determined by ==
), expect
returns
normally. Else, if actual
is not equal to expected
, expect
throws an
TestFailedException
whose detail message includes the expected and actual values, as well as the String
obtained by invoking toString
on the passed message
.expected -
the expected valueclue -
An object whose toString
method returns a message to include in a failure report.actual -
the actual value, which should equal the passed expected
valueTestFailedException -
if the passed actual
value does not equal the passed expected
value.expected
equals the value passed as actual
.
If the actual
value equals the expected
value
(as determined by ==
), expect
returns
normally. Else, expect
throws an
TestFailedException
whose detail message includes the expected and actual values.expected -
the expected valueactual -
the actual value, which should equal the passed expected
valueTestFailedException -
if the passed actual
value does not equal the passed expected
value.
def
fail : Nothing
TestFailedException
to indicate a test failed.
def
fail(message : java.lang.String) : Nothing
TestFailedException
, with the passed
String
message
as the exception's detail
message, to indicate a test failed.message -
A message describing the failure.NullPointerException -
if message
is null
def
fail(message : java.lang.String, cause : java.lang.Throwable) : Nothing
TestFailedException
, with the passed
String
message
as the exception's detail
message and Throwable
cause, to indicate a test failed.message -
A message describing the failure.cause -
A Throwable
that indicates the cause of the failure.NullPointerException -
if message
or cause
is null
def
fail(cause : java.lang.Throwable) : Nothing
TestFailedException
, with the passed
Throwable
cause, to indicate a test failed.
The getMessage
method of the thrown TestFailedException
will return cause.toString()
.cause -
a Throwable
that indicates the cause of the failure.NullPointerException -
if cause
is null
ScalaTest 1.0
|
|