Html output

specs2 can be used to produce HTML documentation to either:

If Markdown notation is used in the specification text and you have Pandoc installed on the command line then it will rendered in the final output.

Create Html files

When you execute a specification with the html command-line argument an HTML report is created in the target/specs2-reports directory. It will show the status of examples (success, failure,…) and stack traces if there are any errors.

You can use the following arguments to change the HTML generation:

Name Default value Description
all false execute and report linked specifications
html.outdir target/specs2-reports output directory
html.template target/specs2-reports/templates/specs2.html copied from the resources/templates directory
html.variables Map[String, String]() those variables will be replaced during template evaluation
html.nostats false if true no stats are displayed
html.search false add a search box to the generated files
html.toc false add a table of contents to the generated files
html.toc.entrymaxsize 18 maximum number of characters for an entry in the table of contents
html.warn.missingrefs true report “see” references which do not correspond to any generated file

Use Pandoc for Markdown

Markdown text is supported if Pandoc is available on the command line and if the !pandoc boolean flag is not set.

NOTE!!!: the currently supported version of Pandoc is 2.3.

Name Default value Description
pandoc true set to false by passing !pandoc
pandoc.exec pandoc path to the Pandoc executable
pandoc.inputformat markdown+pipe_tables+auto_identifiers+header_attributes+inline_code_attributes pandoc arguments (see the Pandoc user guide)
pandoc.outputformat html

Use a different template

You can change the overall structure of the html page for a specification by providing a different template with the html.template variable. When using your custom template the following variables will be replaced:

Name Description
$title$ specification title
$issues$ true if there are issues in the specification
$body$ the specification body

You can also pass your own variables by passing a map name1=value1,name2=value2,... to the html.variables argument. Those variables can then be used in the template:

$if(issues)$
<h1>Failed! $title$
$else$
<h1>$title$</h1>
$endif$

Use other CSS/Javascript files

Custom CSS and JavaScript files can be used without changing the template. In order to do this just put your own specs2-user.css file in src/test/resources/css or your own specs2-user.js file in src/test/resources/javascript.

Create an index

Here is something you can do to automatically create an index page for your specifications:

import org.specs2.*
import specification.core.*
import runner.SpecificationsFinder.default.*

class index extends Specification:
  def is =
    examplesLinks("Example specifications")

  // see the SpecificationsFinder trait for the parameters of the 'specifications' method
  def examplesLinks(t: String) =
    t.title ^
      Fragments.foreach(specifications())(s => link(s) ^ br)

The specification above creates an index.html file in the target/specs2-reports directory. The specifications method creates specifications using the following parameters:

Name Default Description
glob **/*.scala glob pattern to filter specification files
pattern .*Spec pattern to use when trying to retrieve the specification names from the source files
filter (name: String) => true function to keep only some specifications depending on their name
basePath src/test/scala the path where to start the search
verbose false boolean indicating if information about finding files and specifications must be printed
classLoader Thread.currentThread.getContextClassLoader classloader used to load the specification classes
filePathReader org.specs2.io.FileSystem object used to read source files