ScalaTest User Guide

Getting started

Selecting testing styles

Defining base classes

Writing your first test

Using assertions

Tagging your tests

Running your tests

Sharing fixtures

Sharing tests

Using matchers

Testing with mock objects

Property-based testing

Asynchronous testing

Using Scala-js

Using Inside

Using OptionValues

Using EitherValues

Using PartialFunctionValues

Using PrivateMethodTester

Using WrapWith

Philosophy and design

Migrating to 3.0

Invoking execute

The core design of ScalaTest is that you can ask a suite of tests to run itself, enabling easy customization. You do this by invoking run on Suite. The run method takes several parameters, making run inconvenient to call from the Scala interpreter. For this purpose, ScalaTest provides an alternative to run called execute. You can invoke execute on any Suite.

The execute method invokes run on the same Suite, passing in values that can be configured via the parameters to execute, all of which have default values. Here's a summary of this method's parameters:

  • testName - an optional string name of a test to run
  • configMap - a possibly empty map of configuration objects
  • color - boolean indicating whether output should be printed with ANSI colors
  • durations - boolean indicating whether to print durations for tests and suites (i.e., how long they took to run)
  • shortstacks - boolean indicating whether to print durations short (truncated) stack traces for errors
  • fullstacks - boolean indicating whether to print durations full stack traces for errors
  • stats - boolean indicating whether to print statistics before and after the run

Here are the details on these parameters:

The testName parameter

If you leave testName at its default value (of null), this method will pass None to the testName parameter of run, and as a result all the tests in this suite will be executed. If you specify a testName, this method will pass Some(testName) to run, and only that test will be run. Thus to run all tests in a suite from the Scala interpreter, you can write:

scala> (new ExampleSuite).execute()

To run just the test named "my favorite test" in a suite from the Scala interpreter, you would write:

scala> (new ExampleSuite).execute("my favorite test")

Or:

scala> (new ExampleSuite).execute(testName = "my favorite test")

The configMap parameter

If you provide a value for the configMap parameter, this method will pass it to run. If not, the default value of an empty Map will be passed. For more information on how to use a config map to configure your test suites, see the config map section in the main documentation for trait Suite. Here's an example in which you configure a run with the name of an input file:

scala> (new ExampleSuite).execute(configMap = Map("inputFileName" -> "in.txt")

The color parameter

If you leave the color parameter unspecified, this method will configure the reporter it passes to run to print to the standard output in color (via ansi escape characters). If you don't want color output, specify false for color, like this:

scala> (new ExampleSuite).execute(color = false)

The durations parameter

If you leave the durations parameter unspecified, this method will configure the reporter it passes to run to not print durations for tests and suites to the standard output. If you want durations printed, specify true for durations, like this:

scala> (new ExampleSuite).execute(durations = true)

The shortstacks and fullstacks parameters

If you leave both the shortstacks and fullstacks parameters unspecified, this method will configure the reporter it passes to run to not print stack traces for failed tests if it has a stack depth that identifies the offending line of test code. If you prefer a short stack trace (10 to 15 stack frames) to be printed with any test failure, specify true for shortstacks:

scala> (new ExampleSuite).execute(shortstacks = true)

For full stack traces, set fullstacks to true:

scala> (new ExampleSuite).execute(fullstacks = true)

If you specify true for both shortstacks and fullstacks, you'll get full stack traces.

The stats parameter

If you leave the stats parameter unspecified, this method will not fire RunStarting and either RunCompleted or RunAborted events to the reporter it passes to run. If you specify true for stats, this method will fire the run events to the reporter, and the reporter will print the expected test count before the run, and various statistics after, including the number of suites completed and number of tests that succeeded, failed, were ignored or marked pending. Here's how you get the stats:

scala> (new ExampleSuite).execute(stats = true)

Note: In ScalaTest, the terms "execute" and "run" basically mean the same thing and can be used interchangably. The reason this method isn't named run is that it takes advantage of default arguments, and you can't mix overloaded methods and default arguments in Scala. (If named run, this method would have the same name but different arguments than the main run method that takes seven arguments. Thus it would overload and couldn't be used with default argument values.)

Design note: This method has two "features" that may seem unidiomatic. First, the default value of testName is null. Normally in Scala the type of testName would be Option[String] and the default value would be None, as it is in this trait's run method. The null value is used here for two reasons. First, in ScalaTest 1.5, execute was changed from four overloaded methods to one method with default values, taking advantage of the default and named parameters feature introduced in Scala 2.8. To not break existing source code, testName needed to have type String, as it did in two of the overloaded execute methods prior to 1.5. The other reason is that execute has always been designed to be called primarily from an interpreter environment, such as the Scala REPL (Read-Evaluate-Print-Loop). In an interpreter environment, minimizing keystrokes is king. A String type with a null default value lets users type suite.execute("my test name") rather than suite.execute(Some("my test name")), saving several keystrokes.

The second non-idiomatic feature is that shortstacks and fullstacks are all lower case rather than camel case. This is done to be consistent with the Shell, which also uses those forms. The reason lower case is used in the Shell is to save keystrokes in an interpreter environment. Most Unix commands, for example, are all lower case, making them easier and quicker to type. In the ScalaTest Shell, methods like shortstacks, fullstacks, and nostats, etc., are designed to be all lower case so they feel more like shell commands than methods.

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.

artima