tomwadeson / sbt-doctest

Doctest for scala

sbt-doctest

Plugin for sbt that generates tests from examples in ScalaDoc.

Install

To use this plugin, add it to your project/plugins.sbt.

addSbtPlugin("com.github.tkawachi" % "sbt-doctest" % "0.8.0")

It's automatically enabled for JVM projects. Scala.js is currently not supported (See #52).

Using ScalaTest

If you are using ScalaTest, add the following lines to your build.sbt:

libraryDependencies ++= Seq(
  "org.scalatest"  %% "scalatest"  % "3.0.5"  % Test,
  "org.scalacheck" %% "scalacheck" % "1.14.0" % Test
)

doctestTestFramework := DoctestTestFramework.ScalaTest

Using ScalaCheck

If you are using ScalaCheck, add the following lines to your build.sbt:

libraryDependencies ++= Seq(
  "org.scalacheck" %% "scalacheck" % "1.14.0" % Test
)

doctestTestFramework := DoctestTestFramework.ScalaCheck

Using Specs2

If you are using Specs2, add the following lines to your build.sbt:

libraryDependencies ++= Seq(
  "org.specs2" %% "specs2-core"       % "4.3.2" % Test,
  "org.specs2" %% "specs2-scalacheck" % "4.3.2" % Test
)

doctestTestFramework := DoctestTestFramework.Specs2

Using Minitest

If you are using Minitest, add the following lines to your build.sbt:

libraryDependencies ++= Seq(
  ""io.monix"" %% "minitest" % "2.1.1" % Test,
  ""io.monix"" %% "minitest-laws" % "2.1.1" % Test
)

doctestTestFramework := DoctestTestFramework.Minitest

Using µTest

If you are using µTest, add the following lines to your build.sbt:

libraryDependencies ++= Seq(
  "com.lihaoyi" %% "utest" % "0.6.4" % Test
)

doctestTestFramework := DoctestTestFramework.MicroTest

In case you are configuring µTest or using a custom test framework, you can do something like this below in your build.sbt:

testFrameworks -= new TestFramework("utest.runner.Framework")
testFrameworks += new TestFramework("test.utest.MyCustomFramework")

which means that you are removing utest.runner.Framework inserted automatically for you by sbt-doctest and you are inserting your own custom test framework, provided by class test.utest.MyCustomFramework, in this example.

Caveats

There are still dependencies from ScalaTest and/or ScalaCheck when property checks are employed.

The difficulty can be circumvented for the time being by providing all dependencies in build.sbt, like shown in the example below which uses uTest with property checks, which require ScalaTest and ScalaCheck as well:

libraryDependencies ++= Seq(
  "com.lihaoyi"    %% "utest"      % "0.6.4"  % Test,
  "org.scalatest"  %% "scalatest"  % "3.0.5"  % Test,
  "org.scalacheck" %% "scalacheck" % "1.14.0" % Test
)
      
doctestTestFramework := DoctestTestFramework.MicroTest

Usage

sbt-doctest will generate tests from doctests in ScalaDoc comments. These tests are automatically generated and run when sbt's test task is invoked.

Here is an example that shows the different doctest styles that are supported by the plugin:

object Test {

  /**
   * A sample function.
   *
   * {{{
   * # Python style
   * >>> Test.f(10)
   * 20
   *
   * # Scala REPL style
   * scala> Test.f(20)
   * res1: Int = 40
   *
   * # Property based test
   * prop> (i: Int) => Test.f(i) == (i * 2)
   * }}}
   */
  def f(x: Int) = x + x
}

It also supports multi-line inputs:

/**
 * {{{
 * # Python style
 * >>> Test.f(
 * ...   10
 * ... )
 * 20
 *
 * # Scala REPL style
 * scala> Test.f(
 *      |   20
 *      | )
 * res1: Int = 40
 *
 * # Property based test
 * prop> (i: Int) =>
 *     |   Test.f(i) == (i * 2)
 * }}}
 */
def f(x: Int) = x + x

Please use <BLANKLINE> when an output contains blank lines.

/**
 * {{{
 * # Python style
 * >>> Test.helloWorld
 * Hello
 * <BLANKLINE>
 * World
 *
 * # Scala REPL style
 * scala> Test.helloWorld
 * res0: String =
 * Hello
 * <BLANKLINE>
 * World
 * }}}
 */
def helloWorld = "Hello\n\nWorld"

Ignoring Some Files

If you don't want to generate doctests for some of your sources, then specify a regex pattern:

doctestIgnoreRegex := Some(".*SomeClass.scala")

Source files with canonical paths (using UNIX separator - /) matching the regex, will not be used for doctest generation.

HTML Entities

Often when documenting libraries that work with HTML you need to encode HTML entities so that they will be displayed in browsers.

However, sbt-doctest ignores these and attempts to compare encoded HTML with unencoded HTML entities. You can fix this by enabling decoding of HTML entities. Just add the following setting to your build.sbt:

doctestDecodeHtmlEntities := true

Now the following should pass:

  /**
   * {{{
   * >>> Main.html
   * <html></html>
   * }}}
   */
  val html = "<html></html>"

Markdown

Also supports code examples in Markdown documentation. To enable add the following to your build.sbt:

doctestMarkdownEnabled := true

Any code blocks that start with the ```scala markdown directive will be parsed. It searches *.md under baseDirectory by default. It can be configured by doctestMarkdownPathFinder.

// default
doctestMarkdownPathFinder := baseDirectory.value * "*.md"

// search doc/ recursively
doctestMarkdownPathFinder := baseDirectory.value * "doc" ** "*.md" 

See an example markdown.

License

MIT