Runners

In this section we present the most important options for running specifications.

Via sbt

The most common way to run specs2 specifications is to use sbt.

Sbt recognizes specs2 as a “test framework”. This means that any class or object extending the Specification class can be executed by sbt. The test command will run all the specifications in your project provided you put them in the src/test/scala directory:

sbt> test

Most of the time however you will use the testOnly command, either because you want to run one specification only or because you want to pass arguments:

sbt> testOnly org.acme.secret.KillerAppSpec

Only show failed tests:

sbt> testOnly org.acme.secret.KillerAppSpec -- xonly

sbt options

Various sbt options can apply to the execution of tests in sbt but here are the ones which you are most likely to use:

• exclude some specifications: testOptions := Seq(Tests.Filter(s => Seq("Spec", "Unit").exists(s.endsWith)))

• execute specifications one after the other Test / parallelExecution := false

• pass specs2 arguments to all specifications Test / testOptions += Tests.Argument("exclude", "integration")

• display results as soon as they’ve been executed logBuffered := false

• restrict the parallel execution of specifications with custom tags. if you want to use sbt tags you will also need to pass the sbt.tags argument on the command-line

In a shell

A specification can be executed directly with the scala interpreter in a shell, provided that you can produce a classpath containing all the dependencies for your project. One way to do this is to use sbt:

sbt> export runtime:fullClasspath

Then, if you store the output of this command in an environment variable, $SCALA_PATH, you can run a specification with:

sh> scala -classpath $SCALA_PATH specs2.run org.acme.secret.KillerAppSpec

Output

When you run a specification, whatever environment you are in: sbt, shell, IDE,… you can specify different outputs for the results. For example, when you execute a specification with sbt, the results appear in the console. If you want JUnit XML files to be produced instead you need to pass the junitxml argument. Adding any “output” argument will deactivate the console (you will see no output in the console) but you can enable it again by passing the console argument. You can of course specify several outputs like html junitxml console.

Here is a list of all the existing Printers in specs2 with links to the corresponding section in the User Guide for more information.

Arguments

With the testOnly command arguments can be passed on the command line for selecting, executing or reporting a specification. Please consult the following sections for more information:

• Filtering to select only some example to run
• Execution to modify the execution parameters
• Console output, Html output, Custom output… for “reporting” arguments
• the arguments reference guide for a list of all arguments

Now learn how to...

And if you want to know more