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.