Note: Eventually this will be the home for the 3.0.0 final release notes. These release notes are written from the perspective of the final release, but with 3.0.0 replaced with 3.0.0-RC1, the current release candidate version.
Version 3.0.0-RC1 is a major upgrade to ScalaTest and Scalactic, the culmination of over a year of effort. Although it includes many enhancements, we kept a close eye on compatibility with existing ScalaTest/Scalactic 2.x code. We also tried hard to preserve what people liked about both ScalaTest and Scalactic: that it is simple, the code is clean and clear, it's fully documented, and because of very thorough testing, it “just works.”
The most significant enhancement to ScalaTest and Scalactic in the 3.0.0-RC1 release is that they now fully support Scala.js. The advent of Scala.js represented a major, completely unforeseen change in requirements for ScalaTest. As a result, Scala.js support required a very large number of changes to the ScalaTest's eight-year old codebase. Fortunately, the changes were mostly internal to ScalaTest, so little existing ScalaTest user code (i.e., for Scala on the JVM) should break because of the addition of Scala.js support.
ScalaTest and Scalactic 3.0.0-RC1 include a few changes that could in theory break 2.2.x user code, but we expect the number of users and amount of code affected to be small in practice. However, because features that have been deprecated for at least a year (primarily features that were deprecated in October 2013, when 2.0.0 was released) have been removed, we recommend you clear any deprecation warnings given by ScalaTest and Scalactic version 2.2.6 prior to upgrading. For many users, upgrading to ScalaTest and/or Scalactic 3.0.0-RC1 should require only a clean build with the new version. ScalaTest 3.0.0-RC1 does include several new deprecations as well as the deprecation expirations. For more detail, see the breaking changes, new deprecations, and the expired deprecations sections below.
Here's a list of the main enhancements in Scalactic 3.0.0-RC1:
org.scalactic.exceptions.NullArgumentException, and changed all places in ScalaTest and Scalactic that threw
NullPointerExceptionin earlier releases to throw
NullArgumentException. Although throwing
NullPointerExceptionis the tradition in Java APIs, Scala.js does not support a
NullPointerException. To make the behavior consistent on both the JVM and Scala.js, the change to throwing
NullArgumentExceptionwas made throughout the ScalaTest and Scalactic, including the
requireNonNullmethod of trait
PosFloat, etc., have been added in package
CompileTimeAssertions, which you can help you create your own restricted value
CanEqualand made a deprecated type alias for any user code currently referring to
Listinstead of an
AnyRef. Dropped its inheritance relationship with
Nothingfor that now missing type parameter when extending
Or. This is a breaking change, but one which hopefully won't affect much client code in practice.
TrySugar, and added
FutureSugaralso with a
validatingmethod. Also added
ValidationFailedExceptionto support these
validatingmethods as well.
Positionthat supports capturing of caller's source code position through macro.
Here's a list of the main enhancements in ScalaTest 3.0.0-RC1:
org.scalatest.Assertionas a type alias for the singleton type,
org.scalatest.compatible.Assertionto serve as the actual type required by test bodies in the new async styles. Eventually this will be released as a separate Java artifact, just a simple marker interface, so third-party libraries can provide assertions that ScalaTest will recognize as valid assertions without requiring the third party libraries depend on a version of ScalaTest. They will only need to depend on a version of the scalatest-compat.jar Java artifact, which will be very stable.
Anyso that users who compile with
-Ywarn-value-discardwill not get warnings for tests that end in an assertion or matcher expression, which no longer has a
AsyncFeatureSpec—in which the result type of tests is
Future[Assertion]. All asynchronous style traits mixed in
recoverToExceptionIffor asynchronous use case for
recoverToSucceededIffor asynchronous use case for
existssucceeds if at least one row of the table satisfies the assertion block.
forEveryrequires that all rows of the table satisfy the assertion block, like
forAll, but reports information about all rows that fail the assertion block (where
forAlljust reports the first row that fails and short circuits).
inOrderElementsOfsyntax, all of which must follow
BeforeAndAfterso that it will interact properly and consistently when mixed in either before and after
Matchers, and other classes that produce error messages. This makes it easy to customize the string representation of a type in an error message, for example, to reduce the size of string representations of large collections.
Matchers, and other classes that produce error messages. This allowed us to replace the JVM-specific technique we used previously to determine the file name and line number of the offending line of test code prior to 3.0, which involved inspecting the stack. This technique did not work at all when running Scala.js tests on Node.js or Phantom.js, and allows us on the JVM to access an additional piece of information that wasn't available when inspecting the stack: the full path to the source file. The full path was desired for Ensime and will eventually make it out to the reporters (we didn't have time to get it to the reporters in 3.0.0-RC1). This also makes it very simple for users to define custom assertions and get the right stack depth (really, the right filename and line number). We've wanted to solve that problem for a very long time, and users have occasionally requested it. For example, it was requested for the scalaz-scalatest library that created custom ScalaTest assertions for Scalaz.
1) The one breaking change in Scalactic in 3.0.0-RC1 is that we dropped an unnecessary type parameter in
Nothing for that now missing type parameter
Or. There should be no breaking
changes in ScalaTest 3.0.0-RC1 other than expired deprecations.
2) In ScalaTest, one potentially breaking change is in
TimeLimitedTests, which now uses an implicit
of an implicit
Interruptor. Whereas the default
TimeLimitedTests prior to 3.0 was
ThreadInterruptor, the default signaler is
DoNotSignal. This default makes more sense with the advent of
ScalaTest 3.0's support for Scala.js and async testing styles. If you were relying on the default behavior of interrupting a thread on
the JVM in ScalaTest 2.2.x, you'll need to define an implicit
val referring to a
ThreadSignaler. If you had alreday overriden
Interuptor (referenced from
defaultInterruptor) you'll need to define a corresponding
(unless you had defined the
Interruptor to be
DoNotInterrupt, in which case you can just remove the
defaultInterruptor override entirely and enjoy the default
3) Lastly, in ScalaTest we changed the signature of the
whenCompleted method of trait
Status changed. Where it previously
took a function of type
Boolean => Unit, it now takes a function of type
Try[Boolean] => Unit. This
breaking change should affect very few users.
ConversionCheckedTripleEquals, because code that is using it can still compile but mean something quite different if it is removed.
Suite. Please use the empty parens version instead:
withGoodmethod on the
org.scalactic.Accumulationobject that takes one
Orand one transformation function. Please call
Orand pass in the same function instead.
Or, because its main use case is now obsolete, since
Or. You can simply remove
asOrinvocation from such expressions, or if used elsewhere, replace it with a widening type annotation, such as:
(hasTypeGood: Int Or ErrorMessage).
org.scalactic.Constraint. Please change any occurrences to its new name,
Constraintshould appear explicitly in user code only very rarely if at all, as normally it will be used only implicitly.)
Filtercompanion object because the inheritance relationship between
Function2[Set[String], Map[String, Set[String]], List[(String, Boolean)]]was removed.
PropertyCheckConfigin favor of
org.scalatest.prop.Configuration. The new class uses
org.scalactic.anyvalsand instead of an absolute
maxDiscardedvalue, calculates that value by multiplying a
BeforeAndAfterEach(deprecated in ScalaTest 2.0) in favor of
org.scalatest.FailureOf(deprecated in ScalaTest 2.0) in favor of
expectResult(deprecated in ScalaTest 2.0) in
Assertionsin favor of
Suiteas a style trait (deprecated in ScalaTest 2.0) in favor of
Spec(which itself was deprecated in 3.0.0-RC1 and renamed
Option[String](deprecated in ScalaTest 2.0) in favor of
assumemacros that return
plusOrMinus(deprecated in ScalaTest 2.0) operator used with
Matchersin favor of the
ShouldMatchers(deprecated in ScalaTest 2.0) and
MustMatchers(deprecated in ScalaTest 1.9.2), both members of package
org.scalatest.matchers, in favor of
MustMatchers, which resides in package
afterAllmethods of trait
BeforeAndAfterAllthat take a config map (deprecated in ScalaTest 2.0) in favor of
andmethods of trait
GivenWhenThen(deprecated in ScalaTest 2.0) in favor of capitalized forms,
thenwas deprecated as an identifier in Scala 2.10.
Filter(deprecated in ScalaTest 2.0), in favor of two new ones added in ScalaTest 2.0 that take an additional
AbstractSuite(deprecated in ScalaTest 2.0) in favor of trait
SuiteMixin, which since 2.0 has served as the base class for stackable traits that can be mixed into
Distributor(deprecated in ScalaTest 2.0) in favor of the
applymethod added in 2.0 that takes a