ScalaTest Release Notes

ScalaTest 1.8 is source (but not necessarily binary) compatible with previous releases. To upgrade from 1.7.1 or 1.7.2, you should only need to do a clean build.

This release includes the following enhancements, bug fixes, dependency changes, and deprecations:


  • Added trait path.FunSpec, a sister trait to org.scalatest.FunSpec that isolates tests by running each test in its own instance of the test class, and for each test, only executing the path leading to that test.
  • Added trait path.FreeSpec, a sister trait to org.scalatest.FreeSpec that isolates tests by running each test in its own instance of the test class, and for each test, only executing the path leading to that test.
  • Added trait ConfigMapWrapperSuite, a wrapper Suite that passes an instance of the config map to the constructor of the wrapped Suite when run is invoked.
  • Added trait Eventually, which provides an eventually construct that periodically retries executing a passed by-name parameter until it either succeeds or the configured timeout has been surpassed.
  • Added trait AsyncAssertions, which facilitates performing assertions outside the main test thread, such as assertions in callback methods that are invoked asynchronously. Trait AsyncAssertions provides a Waiter class that you can use to orchestrate the inter-thread communication required to perform assertions outside the main test thread, and means to configure it.
  • Added trait Timeouts, which provides a failAfter construct that allows you to specify a time limit for an operation passed as a by-name parameter, as well as a way to interrupt it if the operation exceeds its time limit.
  • Added trait TimeLimitedTests, which, when mixed into a suite class, establishes a time limit for its tests.
  • Added trait Interruptor, an abstract interface defining a strategy for interrupting an operation after a timeout expires (Interruptors are used by traits Timeouts and TimeLimitedTests.). Provided four built-in implementations: DoNotInterrupt, SelectorInterruptor, SocketInterruptor, ThreadInterruptor.
  • Added an org.scalatest.time package containing class Span, used to express time spans in ScalaTest (Span is used by several traits in org.scalatest.concurrent), trait SpanSugar, and several other supporting classes and objects.
  • Added trait ScaledTimeSpans, which provides a scaled method that will scale a Span larger or smaller by a Double factor taken from a sister method, spanScaleFactor. Added a -F argument to Runner for specifying the span scale factor (and corresponding commands for sbt and ant).
  • Added trait PatienceConfiguration, which provides methods and classes used to configure timeouts and, where relevant, the interval between retries.
  • Added trait IntegrationPatience, which overrides the implicit PatienceConfig object providing default values appropriate for unit testing (150 millisecond timeout and 15 millisecond interval) with one more appropriate for integration testing (15 second timeout and 150 millisecond interval).
  • Added trait Conductors, moved a copy of Conductor there, and made changes so that Conductor is configured in a manner consistent with Eventually and AsyncAssertions.
  • Moved most exception classes and traits to their own package, org.scalatest.exceptions, and left deprecated type aliases in place of their old names. This change was done to declutter their former homes, so it is easier for users to focus on the classes and traits they are more likely to use day to day.
  • Added class TestFailedDueToTimeoutException, a subclass of TestFailedException thrown by the failAfter method of trait Timeouts if it times out.
  • Added trait TimeoutField, a trait mixed into exceptions thrown as the result of a timeout.
  • Added trait PayloadField, a trait mixed into exceptions that can carry a payload (an arbitrary object that will be fired in the corresponding ScalaTest event, so it can be consumed by custom reporters). Had to add payload to the primary constructor of several existing exception types. Left the old form in place as an auxiliary constructor so existing code would continue to work.
  • Added trait ModifiablePayload, which indicates a PayloadField exception type can modify its payload.
  • Added trait Payloads, which facilitates the inclusion of a payload in a thrown ScalaTest exception, so that payload object can be included in a corresponding ScalaTest event and interpreted by custom reporters.
  • Added a second parameter to the apply method of trait Informer, to facilitate the inclusion of a payload in an InfoProvided event. The parameter has type Option[Any] with a default value of None, so old code will continute to work.
  • Gave the withClue construct in Assertions a result type, so it would pass through any value in case someone wanted that. Previously it was Unit.
  • Added trait AppendedClues, which provides an implicit conversion that places a withClue method on Any, enabling clue strings to be placed after a block of code that may throw an exception. This construct complements the withClue construct provided in trait Assertions that allows clue strings to be placed before a block of code.
  • Dropped explicit mention of java.awt.AWTError to facilitate running ScalaTest on Android. ScalaTest will continue to treat java.awt.AWTErrors in the same way: they cause the suite to abort rather than the test to fail, but checking is now done based on the string class name to avoid the explicit reference that caused problems on Android.
  • Reimplemented the run method in the org.scalatest package object as an apply method in an singleton object. The client code and behavior are the same, but this implementation enabled the addition of a main method as well that provides the "simple runner".
  • Added a simple runner implemented as a main method on the new singleton object. This application provides a better out-of-box experience for users getting started with ScalaTest, and an easier to remember way to run tests from the command line for experienced ScalaTest users.
  • Added support to ScalaTest for specifying chosen styles, to help enforce uniformity of testing styles on projects built by teams of developers. You can now specify chosen styles with -y argument to Runner. Added a new lifecycle method to Suite, styleName to support this feature. ScalaTest style traits override styleName and return their fully qualified name as a string. If chosen styles is defined, ScalaTest style traits that are not among the chosen list will abort with a message complaining that the style trait is not one of the chosen styles instead of running its tests. Chosen styles is also supported by the ScalaTest ant task and ScalaTestFramework (so accessible via sbt).
  • Added ability to specify suffixes to discover, which can speed up the discovery process on large projects. If you specify suffixes with -q, ScalaTest will only load and inspect class files whose name ends in the suffix to see if they are runnable Suites. Also added a -Q option to specify suffixes "Suite|Spec".
  • Added support for using they as an alternative to it in org.scalatest.FlatSpec and org.scalatest.fixture.FlatSpec, org.scalatest.FunSpec, org.scalatest.fixture.FunSpec, and org.scalatest.path.FunSpec. (This enhancement was inspired by a blog post by Christoph Henkelmann.)
  • Tweaked the algorithm used to clean up type names in the Scala interpreter, so users aren't pummeled with dollar signs. The old algorithm was broken when Scala changed its approach to naming in 2.9. Once again you'll see ExampleSpec rather than $read$$iw$$iw$$iw$$iw$ExampleSpec.
  • Renamed -c to -P, -r to -C, and -p to -R in Runner and ScalaTestAntTask, and deprecated the old usages. After the deprecation cycle, will deprecate the capital forms in favor of lower case forms. The goal is to have -p mean parallel execution (currently -c), -c mean custom reporter (currently -r), and -r mean runpath (currently -p). The new names will be more consistent and hopefully easier to remember.

Bug fixes

  • Fixed stack depth in several style trait methods for rare problems like TestRegistrationClosedException.
  • Discovered that GeneratorDrivenPropertyChecks were not reporting the given parameter names if they were specified in combination with explicit generators passed to forAll. Now they do.
  • Discovered PropertyCheckExceptions were not correctly modifying their message if used with withClue. Now they do.


  • Deprecated org.scalatest.concurrent.Conductor after moving a copy of it to trait Conductors. The purpose of this move was so that Conductor could be configured via PatienceConfiguration and scaled by ScaledTimeSpans, making it consistent with traits Eventually and AsyncAssertions.
  • Deprecated org.scalatest.concurrent.ConductorMultiFixture, which accidentally escaped deprecation in 1.5 when the other "multi fixture" traits (in org.scalatest.fixture) were deprecated.
  • Deprecated org.scalatest.DuplicateTestNameException, org.scalatest.ModifiableMessage, org.scalatest.NotAllowedException, org.scalatest.StackDepth, org.scalatest.StackDepthException, org.scalatest.TestFailedException, org.scalatest.TestPendingException, org.scalatest.TestRegistrationClosedException, org.scalatest.prop.DiscardedEvaluationException, org.scalatest.prop.GeneratorDrivenPropertyCheckFailedException, org.scalatest.prop.PropertyCheckFailedException, org.scalatest.prop.TableDrivenPropertyCheckFailedException. These deprecations were to support moving most exception types to the new org.scalatest.exceptions package. Old code using the old names will continue to work during the deprecation phase. An org.scalatest.prop package object was created to hold the deprecated type aliases for that package. This package object will also be removed at the end of the deprecation period (unless it acquires a new, non-deprecated member in the meantime).
  • Deprecated Runner arguments -r, -c, and -p (and corresponding ScalaTestAntTask syntax) in favor of their new names (see the previous Enhancements section). The old names will continue to work during the deprecation cycle.


  • REMOVED support in Runner for -t to run TestNG tests. This use of -t was deprecated in 1.7 and replaced by -b, because in ScalaTest 2.0 -t will be used to indicate a test name to run. To make sure the ground was clear for this new use in ScalaTest 2.0, -t will print an error message and abort the run in ScalaTest 1.8. If you haven't already, you'll have to change uses of -t to -b to upgrade to ScalaTest 1.8.
  • REMOVED the ability to directly instantiate org.scalatest.exceptions.PropertyCheckException by making it abstract. It was supposed to be abstract, but as an oversight was left concrete. This is a breaking change that likely will not affect any users.
  • REMOVED the ability to mix most ScalaTest style traits together in the same class by adding styleName method to AbstractSuite and overriding and making it final in many style traits. It was never intended that users would mix together core style traits, and likely it wouldn't compile in many cases anyway. But now for sure it won't compile in most cases.

ScalaTest is brought to you by Bill Venners and Artima.
ScalaTest is free, open-source software released under the Apache 2.0 license.

If your company loves ScalaTest, please consider sponsoring the project.

Copyright © 2009-2024 Artima, Inc. All Rights Reserved.