ScalaTest User Guide
Selecting testing styles
Defining base classes
Writing your first test
Tagging your tests
Running your tests
Testing with mock objects
Philosophy and design
Migrating to 3.0
Using ScalaTest with sbt
1. add this to your project file:
libraryDependencies += "org.scalactic" %% "scalactic" % "3.0.4" libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.4" % "test"
The dependency on Scalactic, ScalaTest's sister library focused on quality through types, is recommended but not required.
2. We also recommend you also include the SuperSafe Community Edition Scala compiler plugin, which will flag errors in your ScalaTest (and
Scalactic) code at compile time, by first adding this line to
resolvers += "Artima Maven Repository" at "http://repo.artima.com/releases"
3. Then adding the following line to
addSbtPlugin("com.artima.supersafe" % "sbtplugin" % "1.1.3")
By default, sbt buffers log output for each suite until all tests for that suite complete and causing "spurty" output. We recommend you disable sbt's log buffering so you can enjoy ScalaTest's built-in event buffering algorithm, which shows the events of one suite as they occur until that suite either completes or a timeout occurs, at which point ScalaTest switches a different suite's events. Just add this to your sbt build:
logBuffered in Test := false
Your test source files go into
If you want to run particular suites, you can use
> test-only org.acme.RedSuite org.acme.BlueSuite
Or you can specify a glob:
> test-only *RedSuite
To run only tests affected by your latest code changes, either in main or test, you can use
As with test-only, you can specify a space-separated list of fully qualified names and globs to further reduce the tests selected.
Running Suites in Parallel
With the proliferation of multi-core architectures, and the often parallelizable nature of tests, it is common to run tests in parallel. Sbt by default runs suites in parallel, using its own thread pool. In case you need to run your suites serially, you can add the following to your sbt build file:
parallelExecution in Test := false
ScalaTest uses its own thread pool to run
Pool Size = Available Processors x 2
Showing the Test Classpath
To see classpath that sbt uses to lookup for test classes, you can use the following command:
> show test:full-classpath
Specifying ScalaTest Arguments
You can pass arguments to ScalaTest by using
testOptions in Test += Tests.Argument(TestFrameworks.ScalaTest, "-oD")
> test-only org.acme.RedSuite -- -oD
You can use ScalaTest's reporters by specifying the passing the following arguments to ScalaTest:
Each reporter argument on the command line can include configuration characters. Configuration characters are specified immediately following the
A dropped event will not be delivered to the reporter at all. So the reporter will not know about it and therefore not present information about the event in its report. For example, if you specify
The following reporter configuration parameters may additionally be used on standard output (
If you specify a
Configuring a standard output, error, or file reporter with
Configuring a standard output, error, or file reporter with
By default, a standard output, error, or file reporter inserts ansi escape codes into the output printed to change and later reset terminal colors. Information printed as a result of run starting, completed, and stopped events is printed in cyan. Information printed as a result of ignored or pending test events is shown in yellow. Information printed as a result of test failed, suite aborted, or run aborted events is printed in red. All other information is printed in green. The purpose of these colors is to facilitate speedy reading of the output, especially the finding of failed tests, which can get lost in a sea of passing tests. Configuring a standard output, error, or file reporter into without-color mode (
For example, to run a suite using two reporters, the file reporter configured to present every reported event and a standard error reporter configured to present everything but test starting, test succeeded, test ignored, test pending, suite starting, suite completed, and info provided events, you would use the following in your sbt build file:
testOptions in Test += Tests.Argument(TestFrameworks.ScalaTest, "-f", "result.txt", "-eNDXEHLO")
Note that no white space is allowed between the reporter option and the initial configuration parameters. So "-e NDXEHLO" will not work, "-eNDXEHLO" will work.
Include and Exclude Tests with Tags
You can specify tag names of tests to include or exclude from a run. To specify tags to include, use
> test-only org.acme.* -- -n CheckinTests > test-only org.acme.* -- -n FunctionalTests -l org.scalatest.tags.Slow > test-only org.acme.* -- -n "CheckinTests FunctionalTests" -l "org.scalatest.tags.Slow org.scalatest.tags.Network"
Specifying Chosen Styles
You can optionally specify chosen styles for a ScalaTest run. ScalaTest supports different styles of testing so that different teams can use the style or styles that best suits their situation and culture. But in any one project, it is recommended you decide on one main style for unit testing, and consistently use only that style for unit testing throughout the project. If you also have integration tests in your project, you may wish to pick a different style for them than you are using for unit testing. You may want to allow certain styles to be used in special testing situations on a project, but in general, it is best to minimize the styles used in any given project to a few, or one.
To facilitate the communication and enforcement of a team's style choices for a project, you can specify the chosen styles in your project build. 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. The style name for each ScalaTest style trait is its fully qualified name. For example, to specify that
testOptions in Test += Tests.Argument(TestFrameworks.ScalaTest, "-y", "org.scalatest.FunSpec")
If you wanted
testOptions in Test += Tests.Argument(TestFrameworks.ScalaTest, "-y", "org.scalatest.FunSpec", "-y", "org.scalatest.PropSpec", "-y", "org.scalatest.FeatureSpec")
testOptions in Test += Tests.Argument(TestFrameworks.ScalaTest, "-y", "org.scalatest.FlatSpec", "-y", "org.scalatest.fixture.FlatSpec")
The style name for a suite is obtained by invoking its styleName method. Custom style traits can override this method so that a custom style can participate in the chosen styles list.
Because ScalaTest is so customizable, a determined programmer could circumvent the chosen styles check, but in practice
Specifying a span scale factor
If you specify a integer or floating point span scale factor with
You can request to receive periodic notifications of slowpokes, tests that have been running longer than a given amount of time, specified in seconds by the first integer after
testOptions in Test += Tests.Argument(TestFrameworks.ScalaTest, "-W", "120", "60")
Slowpoke notifications will be sent via
*** Test still running after 2 minutes, 13 seconds: suite name: ExampleSpec, test name: An egg timer should take 10 minutes.