ScalaTest 3.0.1 - org.scalatest.exceptions

class DiscardedEvaluationException extends RuntimeException

Exception that indicates an evaluation of a property should be discarded, because a condition required by a property was not met by the passed values.

This exception is thrown by the whenever method defined in trait Whenever when the given condition is false. The forAll methods defined in trait PropertyChecks catch the DiscardedEvaluationException and ignore it, moving on to try the next set of parameter values it is checking th property against.

class DuplicateTestNameException extends StackDepthException

Exception that indicates an attempt was made to register a test that had the same name as a test already registered in the same suite.

Exception that indicates an attempt was made to register a test that had the same name as a test already registered in the same suite. The purpose of this exception is to encapsulate information about the stack depth at which the line of code that made this attempt resides, so that information can be presented to the user that makes it quick to find the problem line of code. (In other words, the user need not scan through the stack trace to find the correct filename and line number of the offending code.)

Exceptions thrown: NullArgumentException if testName is null

class GeneratorDrivenPropertyCheckFailedException extends PropertyCheckFailedException

Exception that indicates a ScalaCheck property check failed.

Exceptions thrown: NullArgumentException if any parameter is null or Some(null).

trait ModifiableMessage [T <: Throwable] extends AnyRef

Trait implemented by exception types that can modify their detail message.

This trait facilitates the withClue construct provided by trait Assertions. This construct enables extra information (or "clues") to be included in the detail message of a thrown exception. Although both assert and expect provide a way for a clue to be included directly, assertThrows, intercept, and ScalaTest matcher expressions do not. Here's an example of clues provided directly in assert:

assert(1 + 1 === 3, "this is a clue")

and in expect:

expect(3, "this is a clue") { 1 + 1 }

The exceptions thrown by the previous two statements will include the clue string, "this is a clue", in the exceptions detail message. To get the same clue in the detail message of an exception thrown by a failed assertThrows call requires using withClue:

withClue("this is a clue") {
  assertThrows[IndexOutOfBoundsException] {
    "hi".charAt(-1)
  }
}

Similarly, to get a clue in the exception resulting from an exception arising out of a ScalaTest matcher expression, you need to use withClue. Here's an example:

withClue("this is a clue") {
  1 + 1 should === (3)
}

Exception types that mix in this trait have a modifyMessage method, which returns an exception identical to itself, except with the detail message option replaced with the result of invoking the passed function, supplying the current detail message option as the lone String parameter.

trait ModifiablePayload [T <: Throwable] extends AnyRef

Trait implemented by PayloadField exception types that can modify their payload.

This trait facilitates the withPayload construct provided by trait Payloads. This construct enables a payload object (or modified payload object) to be included as the payload of a thrown exception. The payload can then be included in the ScalaTest event that results from that exception. For example, the payload included in a TestFailedException will be included as the payload of the resulting TestFailed event. Here's an example in which a GUI snapshot is included as a payload when a test fails:

withPayload(generateGUISnapshot()) {
  1 + 1 should === (3)
}

Exception types that mix in this trait have a modifyPayload method, which returns an exception identical to itself, except with the payload option replaced with the result of invoking the passed function, supplying the current payload option as the lone Option[Any] parameter.

class NotAllowedException extends StackDepthException

Exception that indicates something was attempted in test code that is not allowed.

Exception that indicates something was attempted in test code that is not allowed. For example, in a FeatureSpec, it is not allowed to nest a feature clause inside another feature clause. If this is attempted, the construction of that suite will fail with a NotAllowedException.

Exceptions thrown: NullArgumentException if either message or failedCodeStackDepthFun is null

trait PayloadField extends AnyRef

Trait implemented by exception types that carry an optional payload.

Many ScalaTest events include an optional "payload" field that can be used to pass information to a custom reporter. This trait facilitates such customization, by allowing test code to include a payload in an exception (such as TestFailedException). ScalaTest looks for this trait and fires any payloads it finds in the relevant ScalaTest event stimulated by the exception, such as a TestFailed event stimulated by a TestFailedException. (Although in its initial release there is only two subclasses of PayloadField in ScalaTest, TestFailedException and TestCanceledException, in future version of ScalaTest, there could be more)

For an example of how payloads could be used, see the documentation for trait Payloads.

abstract class PropertyCheckFailedException extends TestFailedException

Exception that indicates a property check failed.

Exceptions thrown: NullArgumentException if any parameter is null or Some(null).

trait StackDepth extends AnyRef

Trait that encapsulates the information required of an exception thrown by ScalaTest's assertions and matchers, which includes a stack depth at which the failing line of test code resides.

This trait exists so that it can be mixed into two exception superclasses, StackDepthException, from which extend several exceptions that do not depend on JUnit, and JUnitTestFailedError, which does depend on JUnit. The latter, which requires JUnit be in the classpath, ensures failed ScalaTest assertions are reported as "failures," not "errors," by JUnit.

abstract class StackDepthException extends RuntimeException with StackDepth

Exception class that encapsulates information about the stack depth at which the line of code that failed resides, so that information can be presented to the user that makes it quick to find the failing line of code.

Exception class that encapsulates information about the stack depth at which the line of code that failed resides, so that information can be presented to the user that makes it quick to find the failing line of code. (In other words, the user need not scan through the stack trace to find the correct filename and line number of the problem code.) Having a stack depth is more useful in a testing environment in which test failures are implemented as thrown exceptions, as is the case in ScalaTest's built-in suite traits.

Exceptions thrown: NullArgumentException if either messageFun, cause or failedCodeStackDepthFun is null, or Some(null).

class TableDrivenPropertyCheckFailedException extends PropertyCheckFailedException

Exception that indicates a table-driven property check failed.

For an introduction to using tables, see the documentation for trait TableDrivenPropertyChecks.

Exceptions thrown: NullArgumentException if any parameter is null or Some(null).

class TestCanceledException extends StackDepthException with ModifiableMessage[TestCanceledException] with PayloadField with ModifiablePayload[TestCanceledException]

Exception thrown to indicate a test has been canceled.

A canceled test is one that is unable to run because a needed dependency, such as an external database, is missing.

Canceled tests are ones that complete abruptly with a TestCanceledException after starting.

class TestFailedDueToTimeoutException extends TestFailedException with TimeoutField

Subclass of TestFailedException representing tests that failed because of a timeout.

This exception is thrown by the failAfter method of trait Timeouts, the eventually method of trait Eventually, and the await methods of trait AsyncAssertions.

Exceptions thrown: NullArgumentException if either messageFun, cause or failedCodeStackDepthFun is null, or Some(null).

class TestFailedException extends StackDepthException with ModifiableMessage[TestFailedException] with PayloadField with ModifiablePayload[TestFailedException]

Exception that indicates a test failed.

One purpose of this exception is to encapsulate information about the stack depth at which the line of test code that failed resides, so that information can be presented to the user that makes it quick to find the failing line of test code. (In other words, the user need not scan through the stack trace to find the correct filename and line number of the failing test.)

Another purpose of this exception is to encapsulate a payload, an object to be included in a TestFailed event as its payload, so it can be consumed by a custom reporter that understands the payload. For example, tests could take a screen shot image of a GUI when a test fails, and include that as a payload. A custom reporter could listen for such payloads and display the screen shots to the user.

Exceptions thrown: NullArgumentException if either messageFun, cause or failedCodeStackDepthFun is null, or Some(null).

class TestPendingException extends RuntimeException

Exception thrown to indicate a test is pending.

A pending test is one that has been given a name but is not yet implemented. The purpose of pending tests is to facilitate a style of testing in which documentation of behavior is sketched out before tests are written to verify that behavior (and often, the before the behavior of the system being tested is itself implemented). Such sketches form a kind of specification of what tests and functionality to implement later.

To support this style of testing, a test can be given a name that specifies one bit of behavior required by the system being tested. The test can also include some code that sends more information about the behavior to the reporter when the tests run. At the end of the test, it can call method pending, which will cause it to complete abruptly with TestPendingException. Because tests in ScalaTest can be designated as pending with TestPendingException, both the test name and any information sent to the reporter when running the test can appear in the report of a test run. (In other words, the code of a pending test is executed just like any other test.) However, because the test completes abruptly with TestPendingException, the test will be reported as pending, to indicate the actual test, and possibly the functionality, has not yet been implemented.

class TestRegistrationClosedException extends StackDepthException

Exception that indicates an action that is only allowed during a suite's test registration phase, such as registering a test to run or ignore, was attempted after registration had already closed.

In suites that register tests as functions, such as FunSuite and FunSpec, tests are normally registered during construction. Although it is not the usual approach, tests can also be registered after construction by invoking methods that register tests on the already constructed suite so long as run has not been invoked on that suite. As soon as run is invoked for the first time, registration of tests is "closed," meaning that any further attempts to register a test will fail (and result in an instance of this exception class being thrown). This can happen, for example, if an attempt is made to nest tests, such as in a FunSuite:

test("this test is fine") {
  test("but this nested test is not allowed") {
  }
}

This exception encapsulates information about the stack depth at which the line of code that made this attempt resides, so that information can be presented to the user that makes it quick to find the problem line of code. (In other words, the user need not scan through the stack trace to find the correct filename and line number of the offending code.)

Exceptions thrown: NullArgumentException if either message or failedCodeStackDepthFun is null

trait TimeoutField extends AnyRef

Trait mixed into exceptions thrown due to a timeout, which offers a timeout field providing a Span representing the timeout that expired.

This trait is used by trait TimeLimitedTests to detect exceptions thrown because of timeouts, and for such exceptions, to modify the message to more clearly indicate a test timed out. (Although in its initial release there is only one subclass of TimeoutField in ScalaTest, TestFailedDueToTimeoutException, in future version of ScalaTest, there could be more)

Packages

exceptions

package exceptions

Type Members

Ungrouped

Packages

exceptions 

package exceptions

Type Members

Ungrouped

exceptions