org.scalatest.time.SpanSugar.scala Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of scalatest_2.9.0 Show documentation
Show all versions of scalatest_2.9.0 Show documentation
ScalaTest is a free, open-source testing toolkit for Scala and Java
programmers.
/*
* Copyright 2001-2009 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.time
/**
* Trait providing four implicit conversions that allow you to specify spans of time
* by invoking "units" methods such as millis, seconds, and minutes
* on Int, Long, Float, and Double.
*
*
* This trait enables you to specify a span of time in a clear, boilerplate-free way when you
* need to provide an instance of Span. This
* can be used, for example, with the failAfter method of trait
* Timeouts or the timeLimit field of trait
* TimeLimitedTests. It can also be used to specify
* timeouts when using traits Eventually,
* Futures,
* Waiter. Here are examples of each unit enabled by this trait:
*
*
*
*
*
* Int
*
*
* Long
*
*
* Float
*
*
* Double
*
*
*
*
* 1 nanosecond
*
*
* 1L nanosecond
*
*
* 1.0F nanosecond
*
*
* 1.0 nanosecond
*
*
*
*
* 100 nanoseconds
*
*
* 100L nanoseconds
*
*
* 99.8F nanoseconds
*
*
* 99.8 nanoseconds
*
*
*
*
* 1 microsecond
*
*
* 1L microsecond
*
*
* 1.0F microsecond
*
*
* 1.0 microsecond
*
*
*
*
* 100 microseconds
*
*
* 100L microseconds
*
*
* 99.8F microseconds
*
*
* 99.8 microseconds
*
*
*
*
* 1 millisecond
*
*
* 1L millisecond
*
*
* 1.0F millisecond
*
*
* 1.0 millisecond
*
*
*
*
* 100 milliseconds
*
*
* 100L milliseconds
*
*
* 99.8F milliseconds
*
*
* 99.8 milliseconds
*
*
*
*
* 100 millis
*
*
* 100L millis
*
*
* 99.8F millis
*
*
* 99.8 millis
*
*
*
*
* 1 second
*
*
* 1L second
*
*
* 1.0F second
*
*
* 1.0 second
*
*
*
*
* 100 seconds
*
*
* 100L seconds
*
*
* 99.8F seconds
*
*
* 99.8 seconds
*
*
*
*
* 1 minute
*
*
* 1L minute
*
*
* 1.0F minute
*
*
* 1.0 minute
*
*
*
*
* 100 minutes
*
*
* 100L minutes
*
*
* 99.8F minutes
*
*
* 99.8 minutes
*
*
*
*
* 1 hour
*
*
* 1L hour
*
*
* 1.0F hour
*
*
* 1.0 hour
*
*
*
*
* 100 hours
*
*
* 100L hours
*
*
* 99.8F hours
*
*
* 99.8 hours
*
*
*
*
* 1 day
*
*
* 1L day
*
*
* 1.0F day
*
*
* 1.0 day
*
*
*
*
* 100 days
*
*
* 100L days
*
*
* 99.8F days
*
*
* 99.8 days
*
*
*
*
*
* This trait is not the default way to specify Spans for two reasons. First, it adds
* four implicits, which would give the compiler more work to do and may conflict with other implicits the
* user has in scope. Instead, Span provides a clear, concise default way to specify time
* spans that requires no implicits. Here's an example:
*
*
*
* Span(1, Second)
*
*
*
* If you already have implicit conversions in scope that provide a similar syntax sugar for expression
* time spans, you can use that by providing an implicit conversion from the result of those expressions
* to Span. For example, here's how you might use the Duration class from Akka:
*
*
*
* $ scala -cp scalatest-1.8-for-scala-2.9.jar:akka-actor-2.0.jar
* Welcome to Scala version 2.9.1.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_29).
* Type in expressions to have them evaluated.
* Type :help for more information.
*
* scala> import org.scalatest.time._
* import org.scalatest.time.time._
*
* scala> import org.scalatest.concurrent.Eventually._
* import org.scalatest.concurrent.Eventually._
* * scala> import org.scalatest.matchers.ShouldMatchers._
* import org.scalatest.matchers.ShouldMatchers._
*
* scala> import akka.util.Duration
* import akka.util.Duration
*
* scala> implicit def convertAkkaDuration(akkaDuration: Duration): Span =
* | if (akkaDuration.isFinite) Span(akkaDuration.toNanos, Nanoseconds) else Span.max
* convertAkkaDuration: (akkaDuration: akka.util.Duration)org.scalatest.time.Span
*
* scala> eventually(timeout(Duration(100, "millis"))) { 1 + 1 should equal (3) }
* org.scalatest.TestFailedException: The code passed to eventually never returned normally. Attempted 6 times, sleeping 10 milliseconds between each attempt. Last failure message: 2 did not equal 3.
* at org.scalatest.concurrent.Eventually$class.tryTryAgain$1(Eventually.scala:346)
* at org.scalatest.concurrent.Eventually$class.eventually(Eventually.scala:356)
* at org.scalatest.concurrent.Eventually$.eventually(Eventually.scala:396)
* ...
*
* scala> import akka.util.duration._ // Use Akka's syntax sugar for expressing time spans, not ScalaTest's
* import akka.util.duration._
*
* scala> eventually(timeout(100 millis)) { 1 + 1 should equal (3) }
* org.scalatest.TestFailedException: The code passed to eventually never returned normally. Attempted 7 times, sleeping 10 milliseconds between each attempt. Last failure message: 2 did not equal 3.
* at org.scalatest.concurrent.Eventually$class.tryTryAgain$1(Eventually.scala:346)
* at org.scalatest.concurrent.Eventually$class.eventually(Eventually.scala:356)
* at org.scalatest.concurrent.Eventually$.eventually(Eventually.scala:396)
* ...
*
*/
trait SpanSugar {
/**
* Class containing methods that return a Span time value calculated from the
* Long value passed to the GrainOfTime constructor.
*
* @param value the value to be converted
*/
class GrainOfTime(value: Long) {
/**
* A units method for one nanosecond.
*
* @return A Span representing the value passed to the constructor in nanoseconds
*/
def nanosecond: Span = Span(value, Nanosecond)
/**
* A units method for nanoseconds.
*
* @return A Span representing the value passed to the constructor in nanoseconds
*/
def nanoseconds: Span = Span(value, Nanoseconds)
/**
* A units method for one microsecond.
*
* @return A Span representing the value passed to the constructor in microseconds
*/
def microsecond: Span = Span(value, Microsecond)
/**
* A units method for microseconds.
*
* @return A Span representing the value passed to the constructor in microseconds
*/
def microseconds: Span = Span(value, Microseconds)
/**
* A units method for one millisecond.
*
* @return A Span representing the value passed to the constructor in milliseconds
*/
def millisecond: Span = Span(value, Millisecond)
/**
* A units method for milliseconds.
*
* @return A Span representing the value passed to the constructor in milliseconds
*/
def milliseconds: Span = Span(value, Milliseconds)
/**
* A shorter units method for milliseconds.
*
* @return A Span representing the value passed to the constructor in milliseconds
*/
def millis: Span = Span(value, Millis)
/**
* A units method for one second.
*
* @return A Span representing the value passed to the constructor in seconds
*/
def second: Span = Span(value, Second)
/**
* A units method for seconds.
*
* @return A Span representing the value passed to the constructor in seconds
*/
def seconds: Span = Span(value, Seconds)
/**
* A units method for one minute.
*
* @return A Span representing the value passed to the constructor in minutes
*/
def minute: Span = Span(value, Minute)
/**
* A units method for minutes.
*
* @return A Span representing the value passed to the constructor in minutes
*/
def minutes: Span = Span(value, Minutes)
/**
* A units method for one hour.
*
* @return A Span representing the value passed to the constructor in hours
*/
def hour: Span = Span(value, Hour)
/**
* A units method for hours.
*
* @return A Span representing the value passed to the constructor in hours
*/
def hours: Span = Span(value, Hours)
/**
* A units method for one day.
*
* @return A Span representing the value passed to the constructor in days
*/
def day: Span = Span(value, Day)
/**
* A units method for days.
*
* @return A Span representing the value passed to the constructor multiplied in days
*/
def days: Span = Span(value, Days)
}
/**
* Class containing methods that return a Span time value calculated from the
* Double value passed to the FloatingGrainOfTime constructor.
*
* @param value the value to be converted
*/
class FloatingGrainOfTime(value: Double) {
/**
* A units method for one nanosecond.
*
* @return A Span representing the value passed to the constructor in nanoseconds
*/
def nanosecond: Span = Span(value, Nanosecond)
/**
* A units method for nanoseconds.
*
* @return A Span representing the value passed to the constructor in nanoseconds
*/
def nanoseconds: Span = Span(value, Nanoseconds)
/**
* A units method for one microsecond.
*
* @return A Span representing the value passed to the constructor in microseconds
*/
def microsecond: Span = Span(value, Microsecond)
/**
* A units method for microseconds.
*
* @return A Span representing the value passed to the constructor in microseconds
*/
def microseconds: Span = Span(value, Microseconds)
/**
* A units method for one millisecond.
*
* @return A Span representing the value passed to the constructor in milliseconds
*/
def millisecond: Span = Span(value, Millisecond)
/**
* A units method for milliseconds.
*
* @return A Span representing the value passed to the constructor in milliseconds
*/
def milliseconds: Span = Span(value, Milliseconds)
/**
* A shorter units method for milliseconds.
*
* @return A Span representing the value passed to the constructor in milliseconds
*/
def millis: Span = Span(value, Millis)
/**
* A units method for one second.
*
* @return A Span representing the value passed to the constructor in seconds
*/
def second: Span = Span(value, Second)
/**
* A units method for seconds.
*
* @return A Span representing the value passed to the constructor in seconds
*/
def seconds: Span = Span(value, Seconds)
/**
* A units method for one minute.
*
* @return A Span representing the value passed to the constructor in minutes
*/
def minute: Span = Span(value, Minute)
/**
* A units method for minutes.
*
* @return A Span representing the value passed to the constructor in minutes
*/
def minutes: Span = Span(value, Minutes)
/**
* A units method for one hour.
*
* @return A Span representing the value passed to the constructor in hours
*/
def hour: Span = Span(value, Hour)
/**
* A units method for hours.
*
* @return A Span representing the value passed to the constructor in hours
*/
def hours: Span = Span(value, Hours)
/**
* A units method for one day.
*
* @return A Span representing the value passed to the constructor in days
*/
def day: Span = Span(value, Day)
/**
* A units method for days.
*
* @return A Span representing the value passed to the constructor multiplied in days
*/
def days: Span = Span(value, Days)
}
/**
* Implicit conversion that adds time units methods to Ints.
*
* @param i: the Int to which to add time units methods
* @return a GrainOfTime wrapping the passed Int
*/
implicit def convertIntToGrainOfTime(i: Int) = new GrainOfTime(i)
/**
* Implicit conversion that adds time units methods to Longs.
*
* @param i: the Long to which to add time units methods
* @return a GrainOfTime wrapping the passed Long
*/
implicit def convertLongToGrainOfTime(i: Long) = new GrainOfTime(i)
/**
* Implicit conversion that adds time units methods to Floats.
*
* @param f: the Float to which to add time units methods
* @return a FloatingGrainOfTime wrapping the passed Float
*/
implicit def convertFloatToGrainOfTime(f: Float) = new FloatingGrainOfTime(f)
/**
* Implicit conversion that adds time units methods to Doubles.
*
* @param d: the Double to which to add time units methods
* @return a FloatingGrainOfTime wrapping the passed Double
*/
implicit def convertDoubleToGrainOfTime(d: Double) = new FloatingGrainOfTime(d)
}
/**
* Companion object that facilitates the importing of SpanSugar members as
* an alternative to mixing it in. One use case is to import SpanSugar members so you can use
* them in the Scala interpreter:
*
*
* $scala -classpath scalatest.jar
* Welcome to Scala version 2.9.1.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_29).
* Type in expressions to have them evaluated.
* Type :help for more information.
*
* scala> import org.scalatest._
* import org.scalatest._
*
* scala> import concurrent.Timeouts._
* import org.scalatest.concurrent.Timeouts._
*
* scala> import time.SpanSugar._
* import org.scalatest.time.SpanSugar._
*
* scala> Thread.sleep(2 seconds) // TODO: Need a new example
*
*/
object SpanSugar extends SpanSugar