{"id":32957741,"url":"https://github.com/sbt-doctest/sbt-doctest","last_synced_at":"2026-01-14T02:16:58.464Z","repository":{"id":17804144,"uuid":"20691262","full_name":"sbt-doctest/sbt-doctest","owner":"sbt-doctest","description":"Doctest for scala","archived":false,"fork":false,"pushed_at":"2026-01-10T07:42:32.000Z","size":765,"stargazers_count":187,"open_issues_count":9,"forks_count":28,"subscribers_count":8,"default_branch":"master","last_synced_at":"2026-01-11T02:13:22.696Z","etag":null,"topics":["doctest","sbt","scala","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbt-doctest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-06-10T15:46:12.000Z","updated_at":"2026-01-10T07:42:36.000Z","dependencies_parsed_at":"2026-01-05T23:07:13.831Z","dependency_job_id":null,"html_url":"https://github.com/sbt-doctest/sbt-doctest","commit_stats":null,"previous_names":["sbt-doctest/sbt-doctest","tkawachi/sbt-doctest"],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/sbt-doctest/sbt-doctest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt-doctest%2Fsbt-doctest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt-doctest%2Fsbt-doctest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt-doctest%2Fsbt-doctest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt-doctest%2Fsbt-doctest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbt-doctest","download_url":"https://codeload.github.com/sbt-doctest/sbt-doctest/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt-doctest%2Fsbt-doctest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["doctest","sbt","scala","unit-testing"],"created_at":"2025-11-12T23:00:31.033Z","updated_at":"2026-01-14T02:16:58.455Z","avatar_url":"https://github.com/sbt-doctest.png","language":"Scala","funding_links":[],"categories":["Table of Contents","Sbt plugins"],"sub_categories":["Sbt plugins"],"readme":"# sbt-doctest\n\nPlugin for [sbt](https://www.scala-sbt.org) that generates tests from examples\nin ScalaDoc.\n\n## Install\n\nTo use this plugin, add it to your `project/plugins.sbt`.\n\n```scala\naddSbtPlugin(\"io.github.sbt-doctest\" % \"sbt-doctest\" % \"0.12.3\")\n```\n\nThis plugin supports sbt 1.x and 2.x.\n\nIt's automatically enabled.\n\nsbt-doctest allows you to choose which test library to use by `doctestTestFramework`.\nBy default, the tests are generated for ScalaCheck.\nThe test libraries need to be added separately to libraryDependencies.\n\n### Using ScalaCheck\n\nIf you are using [``ScalaCheck``](https://github.com/typelevel/scalacheck), add the following lines to your ``build.sbt``:\n\n```scala\nlibraryDependencies ++= Seq(\n  \"org.scalacheck\" %% \"scalacheck\" % \"1.19.0\" % Test\n)\n\ndoctestTestFramework := DoctestTestFramework.ScalaCheck // Default value for doctestTestFramework\n```\n\n### Using ScalaTest\n\nIf you are using [``ScalaTest``](https://github.com/scalatest/scalatest), add the following lines to your ``build.sbt``:\n\n```scala\n// ScalaTest 3.2\n// ScalaTest 3.2 has been modularized. sbt-doctest generates tests using FunSpec.\nlibraryDependencies ++= Seq(\n  \"org.scalatest\" %% \"scalatest-funspec\" % \"3.2.19\" % Test,\n  \"org.scalatestplus\" %% \"scalacheck-1-18\" % \"3.2.19.0\" % Test\n)\n\n// ScalaTest 3.1\nlibraryDependencies ++= Seq(\n  \"org.scalatest\" %% \"scalatest\" % \"3.1.2\" % Test,\n  \"org.scalatestplus\" %% \"scalacheck-1-14\" % \"3.1.2.0\" % Test\n)\n\n// ScalaTest 3.0\nlibraryDependencies ++= Seq(\n  \"org.scalatest\"  %% \"scalatest\"  % \"3.0.9\"  % Test,\n  \"org.scalacheck\" %% \"scalacheck\" % \"1.14.0\" % Test\n)\n\ndoctestTestFramework := DoctestTestFramework.ScalaTest\n```\n\nDue to changes in the ScalaTest API, the test code generated will be slightly different depending on the version of\nScalaTest. sbt-doctest automatically determines which test code to generate by looking at `libraryDependencies`.\n\nIf you want to explicitly specify the version of ScalaTest to be generated, you can specify `doctestScalaTestVersion`.\n\n```scala\ndoctestScalaTestVersion := Some(\"3.2.15\")\n```\n\n### Using Specs2\n\nIf you are using [``Specs2``](https://github.com/etorreborre/specs2), add the following lines to your ``build.sbt``:\n\n```scala\nlibraryDependencies ++= Seq(\n  \"org.specs2\" %% \"specs2-scalacheck\" % \"4.23.0\" % Test\n)\n\ndoctestTestFramework := DoctestTestFramework.Specs2\n```\n\n### Using Minitest\n\nIf you are using [``Minitest``](https://github.com/monix/minitest), add the following lines to your ``build.sbt``:\n```scala\nlibraryDependencies ++= Seq(\n  \"io.monix\" %% \"minitest\" % \"2.9.5\" % Test,\n  \"io.monix\" %% \"minitest-laws\" % \"2.9.6\" % Test\n)\n\ndoctestTestFramework := DoctestTestFramework.Minitest\n```\n\n### Using µTest\n\nIf you are using [``µTest``](https://github.com/com-lihaoyi/utest), add the following lines to your ``build.sbt``:\n```scala\nlibraryDependencies ++= Seq(\n  \"com.lihaoyi\" %% \"utest\" % \"0.8.4\" % Test\n)\n\ndoctestTestFramework := DoctestTestFramework.MicroTest\n```\n\n### Using MUnit\n\nIf you are using [``MUnit``](https://scalameta.org/munit/), add the following lines to your ``build.sbt``:\n```scala\nlibraryDependencies ++= Seq(\n  \"org.scalameta\" %% \"munit\" % \"0.7.29\" % Test\n)\n\ndoctestTestFramework := DoctestTestFramework.Munit\n```\n\nIn case you are [configuring µTest or using a custom test framework](https://github.com/com-lihaoyi/utest#configuring-utest), you can do something like this below in your ``build.sbt``:\n```scala\ntestFrameworks -= new TestFramework(\"utest.runner.Framework\")\ntestFrameworks += new TestFramework(\"test.utest.MyCustomFramework\")\n```\nwhich 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.\n\n#### Caveats\n\nThere are still dependencies from ``ScalaTest`` and/or ``ScalaCheck`` when property checks are employed.\n\nThe difficulty can be circumvented for the time being by providing all dependencies in ``build.sbt``, like\nshown in the example below which uses ``uTest`` with property checks, which require ``ScalaTest`` and ``ScalaCheck`` as well:\n\n```scala\nlibraryDependencies ++= Seq(\n  \"com.lihaoyi\"    %% \"utest\"      % \"0.8.4\"  % Test,\n  \"org.scalatest\"  %% \"scalatest\"  % \"3.0.9\"  % Test,\n  \"org.scalacheck\" %% \"scalacheck\" % \"1.19.0\" % Test\n)\n      \ndoctestTestFramework := DoctestTestFramework.MicroTest\n```\n\n## Usage\n\nsbt-doctest will generate tests from\ndoctests in ScalaDoc comments. These tests are automatically generated and\nrun when sbt's `test` task is invoked.\n\nHere is an example that shows the different doctest styles that are supported\nby the plugin:\n\n```scala\nobject Test {\n\n  /**\n   * A sample function.\n   *\n   * {{{\n   * # Python style\n   * \u003e\u003e\u003e Test.f(10)\n   * 20\n   *\n   * # Scala REPL style\n   * scala\u003e Test.f(20)\n   * res1: Int = 40\n   *\n   * # Property based test\n   * prop\u003e (i: Int) =\u003e Test.f(i) == (i * 2)\n   * }}}\n   */\n  def f(x: Int) = x + x\n}\n```\n\nIt also supports multi-line inputs:\n\n```scala\n/**\n * {{{\n * # Python style\n * \u003e\u003e\u003e Test.f(\n * ...   10\n * ... )\n * 20\n *\n * # Scala REPL style\n * scala\u003e Test.f(\n *      |   20\n *      | )\n * res1: Int = 40\n *\n * # Property based test\n * prop\u003e (i: Int) =\u003e\n *     |   Test.f(i) == (i * 2)\n * }}}\n */\ndef f(x: Int) = x + x\n```\n\nPlease use `\u003cBLANKLINE\u003e` when an output contains blank lines.\n\n```scala\n/**\n * {{{\n * # Python style\n * \u003e\u003e\u003e Test.helloWorld\n * Hello\n * \u003cBLANKLINE\u003e\n * World\n *\n * # Scala REPL style\n * scala\u003e Test.helloWorld\n * res0: String =\n * Hello\n * \u003cBLANKLINE\u003e\n * World\n * }}}\n */\ndef helloWorld = \"Hello\\n\\nWorld\"\n```\n\n## Ignoring Some Files\n\nIf you don't want to generate doctests for some of your sources, then specify a regex pattern:\n\n```scala\ndoctestIgnoreRegex := Some(\".*SomeClass.scala\")\n```\n\nSource files with canonical paths (using UNIX separator - `/`) matching the regex, will not be used for doctest generation.\n\n## Only Code Blocks Mode\n\nIf you all you need is to check that code in Scaladoc code blocks (text inside `{{{}}}`) compiles),\nyou can enable only code blocks mode by setting `doctestOnlyCodeBlocksMode` to `true`:\n\n```scala\ndoctestOnlyCodeBlocksMode := true\n```\n\nGenerated tests won't have any assertions, unless they are present in your Scaladocs.\n\n## HTML Entities\n\nOften when documenting libraries that work with HTML you need to encode HTML entities so that they will be displayed in browsers.\n\nHowever, `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`:\n\n```scala\ndoctestDecodeHtmlEntities := true\n```\n\nNow the following should pass:\n\n```scala\n  /**\n   * {{{\n   * \u003e\u003e\u003e Main.html\n   * \u0026lt;html\u0026gt;\u0026lt;/html\u0026gt;\n   * }}}\n   */\n  val html = \"\u003chtml\u003e\u003c/html\u003e\"\n```\n\n## Markdown\n\nAlso supports code examples in Markdown documentation. To enable add the following to your `build.sbt`:\n\n```scala\ndoctestMarkdownEnabled := true\n```\n\nAny code blocks that start with the ```` ```scala```` markdown directive will be parsed.\nIt searches `*.md` under `baseDirectory` by default. It can be configured by\n`doctestMarkdownPathFinder`.\n\n```scala\n// default\ndoctestMarkdownPathFinder := baseDirectory.value * \"*.md\"\n\n// search doc/ recursively\ndoctestMarkdownPathFinder := baseDirectory.value * \"doc\" ** \"*.md\" \n```\n\nSee [an example markdown](https://github.com/sbt-doctest/sbt-doctest/blob/master/src/test/resources/ScalaText.md).\n\n## Compatibility with other sbt plugins\n\nIf you happen to have other plugins that use [scalameta](https://github.com/scalameta/scalameta)\n (e.g. [sbt-scalafmt](https://github.com/scalameta/sbt-scalafmt))\nplease make sure those plugins don't bring conflicting version of scalameta.\n\nAt this moment sbt-scalafmt need to be of version 1.6.x at least.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbt-doctest%2Fsbt-doctest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbt-doctest%2Fsbt-doctest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbt-doctest%2Fsbt-doctest/lists"}