ScalaTest

ScalaTest Release Notes

Changes in 1.1 and 1.2

Note: ScalaTest 1.1 and 1.2 basically have identical feature sets. The only difference is the Scala version they support. ScalaTest 1.1 works with Scala 2.7, and ScalaTest 1.2 with Scala 2.8. For a while we will support both 2.7 and 2.8 with new enhancements, with corresponding ScalaTest 1.1.x and 1.2.x releases. At some point we'll bump up to 1.3 and only support Scala 2.8 and beyond.

  • The main change from 1.0 to 1.1/1.2 is many changes to support Scala 2.8. Many of these changes went into both 1.1 and 1.2 codebases to simplify supporting both codebases in future releases. Some changes went just to the 1.2 branch. None of these should be visible to users of ScalaTest. In other words, the ScalaTest API did not need to change between Scala 2.7 and Scala 2.8, only its implementation.
  • Added dir attribute to ScalaTest ant task.
  • Renamed XML reporter to junitxml in the ScalaTest ant task.
  • Made Tag a concrete class (in earlier releases it was abstract), and added a Tag companion object with an apply method. The abstract Tag class enabled users to define tags with object SlowTest extends Tag("SlowTest"). This enhancements allows tags to also be created on the fly, for example, with Tag("SlowTest").
  • Added ScalaTestFramework to support sbt.
  • Fixed "smiley-face" bug in XML reporter, an extra few characters that caused the XML to be invalid.
  • When running failed or ignored tests in WordSpec, print the "should" verb in the GUI report, which was missing.

Changes in 1.0

  • Dropped ImpSuite, which had been deprecated for two releases
  • Changed JUnit3Suite so it delegates to JUnit 4's JUnitCore class to run the tests. Before it was simulating JUnit execution without actually using JUnit.
  • Dropped two forms of intercept, which had been deprecated for two releases
  • Made Distributor into a function (breaking change).
  • Made Stopper into a function (breaking change).
  • Renamed Rerunnable into Rerunner and made it a function. Deprecated Rerunnable (breaking change).
  • Renamed main execute method (the one with many parameters) in Suite to run. Changed its signature (breaking change).
  • Added two more final execute methods to Suite that each take a configMap
  • Added a sealed hierarcy of Event classes.
  • Refactored Reporter so that instead of having one method per event type, it has one apply method, which takes an Event (breaking change).
  • Added ResourcefulReporter, which models a Reporter that holds finite, non-memory resources.
  • Added Ordinal. Every Event class includes an Ordinal so that the events of parallel runs can be sorted in sequential order. Made changes to all Suite traits to ensure they fire events with proper Ordinals.
  • Added Tracker to support the inclusion of good Ordinals in fired Events.
  • Added Filter, which changes how tags to include and exclude are handled. Previously the two include and exclude sets were passed into Suite methods, and it was the responsibility of those methods to filter tests correctly. Now the two include and exclude sets are passed to a Filter, and the Filter is passed to the Suite methods, which can delegate to Filter to do the filtering.
  • Renamed groups to tags (deprecated groups)
  • Greatly improved JUnit integration. Added JUnitSuite, JUnitRunner, JUnitWrapperSuite, AssertionsForJUnit, ShouldMatchersForJUnit, MustMatchersForJUnit, JUnitTestFailedError
  • Added -j option to Runner to run JUnit tests with the JUnitWrapperSuite
  • Changed the configuration parameters for Reporters. The old ones will be accepted but have no effect for a two-release deprecation cycle, after which they will cause Runner to halt with an error message.
  • Added optional color output to standard out, standard error, and file reporters.
  • Added Reporter configuration parameters for turning off color, showing durations, and showing full stack traces.
  • Added a jvmargs option to the Ant task, which makes it possible to pass args to the underlying JVM (important if you need more memory)
  • Added a fork option to the Ant task, which makes it possible to run ScalaTest in a separate JVM from Ant (also useful for dealing with memory problems).
  • Renamed goodies to configMap.
  • Renamed the Ant task from ScalaTestTask to ScalaTestAntTask. Deprecated ScalaTestTask.
  • Added ability to specify the number of threads to use when running tests in parallel, in both Runner and the Ant task.
  • Enhanced Runner so that it treats a backslash followed by a space as a literal space in a runpath element, rather than a space separating two runpath elements. This was necessary to allow people to include pathnames in the runpath that included spaces.
  • Added two new forms to matchers DSL: result should be === 7 and evaluating { "hi".charAt(-1) } should produce [StringIndexOutOfBoundsException].
  • Added support for pending tests.
  • Added pendingUntilFixed method to Suite.
  • Deprecated Report and SpecReport. These are no longer used, as they were made obsolete by the Reporter refactor. Instead of SpecReport, the Formatter and its two subclasses, MotionToSuppress and IndentedText are used to format specification-style output.
  • Added the org.scalatest.concurrent package, which includes Conductor, ConductorFixture, ConductorMultiFixture, and ConductorMethods.
  • Added the org.scalatest.mock package, which includes EasyMockSugar, JMockCycle, JMockCycleFixture, JMockExpectations, and MockitoSugar.
  • Added three new BDD traits: WordSpec, FlatSpec, and FeatureSpec.
  • Added the org.scalatest.fixture package, which includes FixtureSuite, FixtureFunSuite, FixtureSpec, FixtureWordSpec, FixtureFlatSpec, FixtureFeatureSpec, ConfigMapFixture, MultipleFixtureFunSuite, MultipleFixtureSpec, MultipleFixtureWordSpec, MultipleFixtureFlatSpec, and MultipleFixtureFeatureSpec.
  • Added the org.scalatest.verb package to support FlatSpec and WordSpec.
  • Split the BeforeAndAfter trait into BeforeAndAfterEach and BeforeAndAfterAll. Deprecated BeforeAndAfter.
  • Added trait GivenWhenThen.
  • Renamed Group to Tag. Deprecated Group. Also renamed groups method to tags in Suite, and deprecated groups.
  • Added TagAnnotation to serve as base class for tag annotations for Suite, however, won't enforce for a two-release deprecation cycle that tag annotations used on Suite test methods need to extend TagAnnotation.
  • Dropped the apply method that takes a Report (which is no longer used) from Informer, and also dropped the nameForReport method (breaking changes).
  • Added the OneInstancePerTest trait.
  • Added the ParallelTestExecution trait.
  • Added the SequentialNestedSuiteExecution trait.
  • Refactored TestFailedException so that it extends StackDepthException, which mixes in StackDepth. Added other StackDepthExceptions so that other errors in test code beyond just assertion failures will be reported with stack depths: DuplicateTestNameException, NotAllowedException, and TestRegistrationClosedException. Set aside StackDepth as a separate trait to support JUnitTestFailedError.
  • Renamed ExecuteAndRun to AbstractSuite, and added more methods to it, to facilitate the stackable trait pattern (breaking change).

Changes in 0.9.5

  • Added ShouldMatchers and MustMatchers traits, plus many supporting classes and traits.
  • Added support for SpecReport in the GUI, so that SpecReports get displayed in a specification style. This makes org.scalatest.Spec output look nicer in the GUI, and also makes it possible for org.specs.Specification to send SpecReports that will look nice in the ScalaTest GUI.
  • Enhanced the GUI to automatically select the first error, if there is one. This saves users a bit of time each error.
  • Added a TestFailedException, which allows a stack trace depth to be sent along with test failures. This allows reports to highlight the exactly filename and line number at which a test failed. This makes it quicker for users to find the cause of the problem. Enhanced everything to send TestFailedExceptions where possible.
  • Formatted the details area of the GUI so that it is easier to read, including making bold the most important part of the report, the report message and filename and line number, if it exists.
  • Made sure the entire stack trace is printed in the GUI's detail area. Previously it might say things like 37 more...
  • Made the GUI report list scroll during a rerun, to make it easier to find the reports of the rerun.
  • Filled in the name in run completed reports, which was missing.
  • Fixed a bug that prevented suites from being automatically discovered inside JAR files.
  • Added the exception that caused a ScalaCheck failure as the cause in the TestFailedException, which was not being propagated to the reporters before.
  • Display more nicely the information, arguments and labels, provided with a failed ScalaCheck property check.
  • In some cases, FunSuite and Spec were not sending Rerunnables in reports even though they could, which made rerunning not work in some cases in the GUI. They now send a Rerunnable whenever they can.
  • Removed SpecDasher from the API, which also is no longer mixed in by Spec. The only reason this was included in 0.9.4 was that it was demonstrated in Programming in Scala. It still works and can be used, so if you liked it, you can just grab it from 0.9.4 and mix it in yourself as a local mix in.

Changes in 0.9.4

  • Renamed trait ImpSuite to BeforeAndAfter. ImpSuite remains for now but is marked as deprecated. In a future release of ScalaTest ImpSuite will be dropped, so please rename your uses of ImpSuite to BeforeAndAfter as soon as convenient. The reason this was changed is that the "Imp" stood for imperative, because the trait facilitates an imperative style of testing. Also "imp" in English means "little devil," which projected a good attitude, because one goal of ScalaTest is to encourage users to adopt a more functional style for fixture "setup" and "teardown." But it's a bit too cute and its meaning not obvious enough from its name. Plus mixing an ImpSuite into a Spec felt like mixing metaphors.
  • Pulled the triple equals operator mechanism and the expect and intercept constructs from Suite into their own trait, named Assertions. Suite now mixes in this trait, so that it has the same functionality as before. The main reason this was done was so that these constructs could more easily be used outside of ScalaTest Suites, and also so the trait could be extended by ScalaTest's matchers. (ScalaTest's matchers are not yet released, but will probably make their debut in ScalaTest version 0.9.5.) This allows ScalaTest's matchers to assume these constructs exist, and makes it easier to use ScalaTest matchers independently from ScalaTest Suites.
  • Added a version of intercept that takes an implicit Manifest, so that you need not explicitly pass a class instance anymore. Thus, instead of saying this:
    intercept(classOf[StringIndexOutOfBoundsException]) {
      "hi".charAt(-1)
    }
    
    You can write:
    intercept[StringIndexOutOfBoundsException] {
      "hi".charAt(-1)
    }
    
    The old style that requires an explicit class instance are still in the API, but they are deprecated. They will be removed in some future release of ScalaTest, so please start migrating to the new style. There are a few corner cases where the new form can't be used, which are caused by overloading ambiguities with the old style. The two corners are passing an explicit null to intercept and throwing an explicit exception such that the inferred type of the by-name parameter is Nothing. It is unlikely anyone would do that anyway, and these two issues will resolve themselves once the deprecated old-style intercept methods are removed.
  • Added Spec. This trait is inspired by Ruby's RSpec BDD tool.
  • Renamed PropSuite to FunSuite in org.scalatest.prop. This was done because it made sense to add the extra ScalaCheck methods to Spec as well, so it seemed more reasonable to just have traits with the same name in two different packages. So there would be a FunSuite and Spec in both org.scalatest and org.scalatest.prop. The latter batch would already mix in Checkers and offer the extra ScalaCheck property-taking methods, and of course, have a dependency on ScalaCheck. Thus, PropSuite was deprecated, but it is left in the API for the time being to avoid client code breakage. PropSuite will go away in a future release. Later, the traits that had the extra property-taking methods were judged not worth their weight, so ScalaTest 0.9.4 does not include a Spec in package org.scalatest.prop. However because an example using org.scalatest.prop.FunSuite was included in Programming in Scala, it was included in 0.9.4, already deprecated. Both PropSuite and FunSuite will be removed from the org.scalatest.prop package in a future ScalaTest release, so please start migrating to use org.scalatest.FunSuite, mixing in Checkers and passing properties to ScalaCheck with check, as shown in this example.
  • Released SpecDasher trait. This may or may not be a good idea, but an example of the "dashes" style it enables was shown in Programming in Scala, so it was included in 0.9.4, but deprecated. It may stay or go in a future release, depending on user feedback. Currently, Spec already mixes SpecDasher in by default, but if it ends up staying in the API, this connection will almost certainly be severed so that users must explicitly mix it in to get the "dashes" style. So use it with caution, but even if it is removed, if you like it you can always just add the code for it to your own project and use it that way.
  • Added SpecReport, a subclass of Report. Specs emit SpecReports when they run, and the print reporters (standard out, err, file, etc.) recognize them and generate specification-like output. In this release the graphic reporter does not handle SpecReport's specially, so the output looks like regular test output. In a future release the graphic reporter will generate a specification-like output. One use case for SpecReports is integration with Eric Torreborre's specs tool, however one piece still remains for that integration. Specs (and JUnit and TestNG) generate nested test output, whereas ScalaTest's model is flat. In a future version ScalaTest's Report class will be enhanced to support nested reports. This will enable specs tests run through ScalaTest to provide nice nested, specification-like reports.
  • Created an ExecuteAndRun trait. The purpose of this trait is to pull out abstract method signatures for execute and runTest (and later if it turns out to be useful, runNestedSuites and runTests) so they can be called by traits that have Suite as their self type, but extend ExecuteAndRun not Suite, such as BeforeAndAfter. This makes such traits stackable behaviors that can be mixed into a Suite while not being a Suite themselves.
  • Removed testWithInformer and ignoreWithInformer methods from FunSuite, because they were simply too ugly to live. Unfortunately these were not deprecated, so if you used them you'll need to already make an adjustment to upgrade to 0.9.4. What replaced them is an imperative approach, which while more error prone will work fine unless abused, and makes for much nicer client code. There's a new method named info in FunSuite, which returns an Informer. So where before you said:
    testWithInformer("test name") {
      info => {
        info("send info to the reporter")
      }
    }
    
    Now you'll just say:
    test("test name") {
      info("send info to the reporter")
    }
    
    During suite execution, the info method returns an Informer that immediately forwards information passed to its apply methods to the reporter. During construction of the object, the info method returns an Informer that saves the information passed to its apply methods for later sending to the reporter when the suite is executed. At any other time, the info method will return an Informer that throws an exception.

Changes in 0.9.3

  • Moved FunSuite from the org.scalatest.fun to org.scalatest package.
  • Dropped FunSuite1 through FunSuite9, which were also in the org.scalatest.fun package, because the surface area they added to the API didn't seem worth the small savings in code size over creating "with" methods with meaningful names and explicitly calling them.
  • Added an ImpSuite, which can be mixed into another suite to gain methods that will run before and after each suite and test.
  • Updated the portions of Scaladoc comments for Suite and FunSuite that discuss mutable fixtures. Dropped the suggestion to override runTest, which still works but is verbose, and instead recommended defining and explicitly calling "create" methods or "with" methods from tests that need the mutable fixtures, or mixing in ImpSuite and using beforeEach, afterEach, etc.
  • Added an Informer trait, which provides a simpler way to send information to the infoProvided method of a Reporter.
  • Changed Suite such that instead of being able to define test methods that take a Reporter, you can define test methods that take an Informer. Replaced the section of scaladoc for Suite that used to explain how to use a passed-in Reporter to now show how to use an Informer.
  • Changed FunSuite such that instead of being able to register tests whose function values take a Reporter, you can register tests whose function values take an Informer. Changed the names of the registration methods from test/ignoreWithReporter to test/ignoreWithInformer. Replaced the section of scaladoc for FunSuite that used to explain how to use a Reporter passed in to a test function to now show how to use an Informer.
  • Moved org.scalatest.scalacheck.CheckSuite to org.scalatest.prop.Checkers, and renamed its checkProperty methods to plain old check.
  • Added PropSuite, a subtrait of FunSuite, which offers methods that register tests composed of a single property check.
  • Improved the messages generated by the assert(... === ...) and expect(...){...} methods. Strings are now reported surrounded by double quotes, with ends truncated where matching if very long, and with square brackets surrounding the portions that differ. Characters are reported surrounded by single quotes, integer and floating point numbers as is, and any other object's toString result surrounded by angle brackets.
  • Removed dollar signs and non-essential text from suite and test names in reports when running from the interpreter.
  • Improved the look of the output generated by the build-in reporters that print to the standard out, error, or to files.
  • Added a section to Suite's scaladoc that describes using external assertions, such as JUnit's assertions, Hamcrest matchers, or specs matchers, in ScalaTest tests.
  • Improved the failure message when a ScalaCheck property check fails.
  • Renamed user-defined properties to "goodies," because the term "properties" was overloaded to mean both key-value pairs that can be passed to suites and ScalaCheck-like properties. "Goodies" is not a very obvious name, so suggestions for improvement are welcome.

Changes in 0.9.2

  • Moved Runner from org.scalatest to org.scalatest.tools package.
  • Added JUnit integration classes in package org.scalatest.junit.
  • Added TestNG integration classes in package org.scalatest.testng.
  • Added ScalaCheck integration classes in package org.scalatest.scalacheck.
  • Added FunSuite family of traits in package org.scalatest.fun.
  • Added an Ant task.

Changes in 0.9.1

  • Changed testGroups method name to groups.
  • Changed operand names of ===, from expected === actual to left === right.
  • Changed message generated from 2 === 1, from "Expected 1, but got 2" to "2 did not equal 1".
  • Changed expect method name to intercept.
  • Dropped expectNPE and expectIAE methods.
  • Added a different expect method, which takes an expected and actual value. expect(1) {2} would generate the error message "Expected 1, but got 2.
  • Made versions of expect and intercept that take a message.
  • Implemented a Suite discovery mechanism in Runner, accessed via -m or -w command-line arguments.
  • Dropped !== method from the great Equalizer.

Known issues

  1. Reloading classes from JAR files between runs in the GUI doesn't work, because URLClassLoader uses a JAR cache. For now, you'll have to restart the app to pick up new classes in JAR files. But a better alternative is to simply point ScalaTest to the build directory containing .class files produced by the Scala and Java compiler. URLClassLoader will not cache these files, so changes to them will be picked up each time you press the Run or Rerun buttons.

ScalaTest is brought to you by Bill Venners, with contributions from several other folks. It is sponsored by Artima, Inc.
ScalaTest is free, open-source software released under the Apache 2.0 license.

Copyright © 2009 Artima, Inc. All Rights Reserved.

artima