org.scalatest.CompleteLastly.scala Maven / Gradle / Ivy
/*
* Copyright 2001-2016 Artima, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.scalatest
import enablers.Futuristic
/**
* Trait that provides a complete-lastly construct, which ensures
* cleanup code in lastly is executed whether the code passed to complete
* completes abruptly with an exception or successfully results in a Future,
* FutureOutcome, or other type with an
* implicit Futuristic instance.
*
*
* This trait is mixed into ScalaTest's async testing styles, to make it easy to ensure
* cleanup code will execute whether code that produces a "futuristic" value (any type F
* for which a Futuristic[F] instance is implicitly available). ScalaTest provides
* implicit Futuristic instances for Future[T] for any type T
* and FutureOutcome.
*
*
*
* If the future-producing code passed to complete throws an
* exception, the cleanup code passed to lastly will be executed immediately, and the same exception will
* be rethrown, unless the code passed to lastly also completes abruptly with an exception. In that case,
* complete-lastly will complete abruptly with the exception thrown by the code passed to
* lastly (this mimics the behavior of finally).
*
*
*
* Otherwise, if the code passed to complete successfully returns a Future (or other "futuristic" type),
* complete-lastly
* will register the cleanup code to be performed once the future completes and return a new future that will complete
* once the original future completes and the subsequent cleanup code has completed execution. The future returned by
* complete-lastly will have the same result as the original future passed to complete,
* unless the cleanup code throws an exception. If the cleanup code passed to lastly throws
* an exception, the future returned by lastly will fail with that exception.
*
*
*
* The complete-lastly syntax is intended to be used to ensure cleanup code is executed
* in async testing styles like try-finally is used in traditional testing styles.
* Here's an example of complete-lastly
* used in withFixture in an async testing style:
*
*
*
* // Your implementation
* override def withFixture(test: NoArgAsyncTest) = {
*
* // Perform setup here
*
* complete {
* super.withFixture(test) // Invoke the test function
* } lastly {
* // Perform cleanup here
* }
* }
*
*/
trait CompleteLastly {
/**
* Class that provides the lastly method of the complete-lastly syntax.
*
* @param futuristicBlock a by-name that produces a futuristic type
* @param futuristic the futuristic typeclass instance
*/
class ResultOfCompleteInvocation[T](futuristicBlock: => T, futuristic: Futuristic[T]) {
/**
* Registers cleanup code to be executed immediately if the future-producing code passed
* to complete throws an exception, or otherwise asynchronously, when the future
* returned by the code passed to complete itself completes.
*
*
* See the main documentation for trait CompleteLastly for more detail.
*
*
* @param lastlyBlock cleanup code to execute whether the code passed to complete
* throws an exception or succesfully returns a futuristic value.
*/
def lastly(lastlyBlock: => Unit): T = {
val result: T =
try futuristicBlock // evaluate the by-name once
catch {
case ex: Throwable =>
lastlyBlock // execute the clean up
throw ex // rethrow the same exception
}
futuristic.withCleanup(result) { lastlyBlock }
}
/**
* Pretty string representation of this class.
*/
override def toString = "ResultOfCompleteInvocation"
}
/**
* Registers a block of code that produces any "futuristic" type (any type F for which
* an implicit Futuristic[F] instance is implicitly available), returning
* an object that offers a lastly method.
*
*
* See the main documentation for trait CompleteLastly for more detail.
*
*
* @param completeBlock cleanup code to execute whether the code passed to complete
* throws an exception or succesfully returns a futuristic value.
*/
def complete[T](completeBlock: => T)(implicit futuristic: Futuristic[T]): ResultOfCompleteInvocation[T] =
new ResultOfCompleteInvocation[T](completeBlock, futuristic)
}
/**
* Companion object that facilitates the importing of CompleteLastly members as
* an alternative to mixing it in.
*/
object CompleteLastly extends CompleteLastly