{"id":13801497,"url":"https://github.com/com-lihaoyi/utest","last_synced_at":"2026-01-12T08:04:10.403Z","repository":{"id":13575513,"uuid":"16268021","full_name":"com-lihaoyi/utest","owner":"com-lihaoyi","description":"A simple testing framework for Scala","archived":false,"fork":false,"pushed_at":"2025-12-01T19:15:27.000Z","size":2783,"stargazers_count":509,"open_issues_count":17,"forks_count":88,"subscribers_count":13,"default_branch":"master","last_synced_at":"2026-01-06T21:07:18.858Z","etag":null,"topics":[],"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/com-lihaoyi.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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},"funding":{"github":"lihaoyi"}},"created_at":"2014-01-27T03:12:39.000Z","updated_at":"2025-12-29T16:42:00.000Z","dependencies_parsed_at":"2025-12-01T19:01:50.635Z","dependency_job_id":null,"html_url":"https://github.com/com-lihaoyi/utest","commit_stats":null,"previous_names":["lihaoyi/utest"],"tags_count":52,"template":false,"template_full_name":null,"purl":"pkg:github/com-lihaoyi/utest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/com-lihaoyi%2Futest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/com-lihaoyi%2Futest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/com-lihaoyi%2Futest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/com-lihaoyi%2Futest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/com-lihaoyi","download_url":"https://codeload.github.com/com-lihaoyi/utest/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/com-lihaoyi%2Futest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2024-08-04T00:01:23.490Z","updated_at":"2026-01-12T08:04:10.396Z","avatar_url":"https://github.com/com-lihaoyi.png","language":"Scala","funding_links":["https://github.com/sponsors/lihaoyi","https://www.patreon.com/lihaoyi"],"categories":["Table of Contents","测试"],"sub_categories":["Testing"],"readme":"µTest 0.9.5\n====================================================================================================\n\n\nuTest is a simple, convenient testing library for Scala.\nIts key features are:\n\n- Nicely formatted, colored, easy-to-read command-line test output\n\n![PrettyPrint.png](docs/PrettyPrint.png)\n\n- [Single uniform syntax for defining tests and grouping them together](#nesting-tests)\n\n- [Single uniform syntax for running test suites and individual tests](#running-tests)\n\n- [Single uniform syntax for Smart Asserts](#smart-asserts), instead of multiple\n  redundant `must_==`/`must beEqual`/`should be` operators\n\n- Auto-updating [assertGoldenLiteral](#assertgoldenliteral) and [assertGoldenFile](#assertgoldenfile) assertions \n  that make easy to keep your test suite up to date with the last behavior of your code\n\n![Golden.png](docs/Golden.png)\n\n- [Isolation-by-default for tests in the same suite](#sharing-setup-code-and-sharing-setup-objects)\n\n- Supports [Scala.js and Scala-Native](#scalajs-and-scala-native), Scala 2.12.x/2.13.x/3.x,\n  projects using [SBT](#getting-started) or [Mill](https://mill-build.org/mill/index.html)\n  [standalone](#running-utest-standalone) (e.g. via a `main` method, or in\n  Ammonite Scripts),\n  projects using [Gradle plugin for Scala.js and Scala Native](https://github.com/dubinsky/scalajs-gradle).\n\nUnlike traditional testing libraries for Scala (like\n[Scalatest](http://www.scalatest.org/) or\n[Specs2](https://etorreborre.github.io/specs2/)) uTest aims to be simple enough\nyou will never \"get lost\" in its codebase and functionality, so you can focus on\nwhat's most important: your tests.\n\nWhile uTest has many fewer features than other libraries,\nthe features that it does provide are polished and are enough to build\nand maintain test suites of any size. uTest is used for countless projects, from\nthe 1-file test suite for\n[Fansi](https://github.com/lihaoyi/fansi)\nto the 50-file 9,000-line test suite for [Ammonite](https://github.com/lihaoyi/Ammonite)\n\nIf you use uTest and like it, please support it by donating to our Patreon:\n\n- [https://www.patreon.com/lihaoyi](https://www.patreon.com/lihaoyi)\n\nContents\n--------\n\n- [Getting Started](#getting-started)\n- [Defining and Running a Test Suite](#defining-and-running-a-test-suite)\n  - [Nesting Tests](#nesting-tests)\n  - [Running Tests](#running-tests)\n  - [Sharing Setup Code, and Sharing Setup Objects](#sharing-setup-code-and-sharing-setup-objects)\n  - [Other Ways of Naming tests](#other-ways-of-naming-tests)\n  - [Asynchronous Tests](#asynchronous-tests)\n- [Smart Asserts](#smart-asserts)\n  - [Arrow Asserts](#arrow-asserts)\n  - [assertThrows](#assertThrows)\n  - [assertEventually and assertContinually](#asserteventually-and-assertcontinually)\n  - [assertMatch](#assert-match)\n  - [assertCompileError](#assertcompileerror)\n  - [assertGoldenLiteral](#assertgoldenliteral)\n  - [assertGoldenFile](#assertgoldenfile)\n- [Test Utilities](#test-utilities)\n  - [TestPath](#testpath)\n  - [Local Retries](#local-retries)\n- [Configuring uTest](#configuring-utest)\n  - [Per-Run Setup/Teardown, and other test-running Config](#per-run-setupteardown-and-other-test-running-config)\n  - [Output Formatting](#output-formatting)\n  - [Suite Retries](#suite-retries)\n  - [Running code before and after test cases](#running-code-before-and-after-test-cases)\n  - [Running code before and after test suites](#running-code-before-and-after-test-suites)\n  - [Test Wrapping](#test-wrapping)\n- [Scala.js and Scala-Native](#scalajs-and-scala-native)\n- [Running uTest Standalone](#running-utest-standalone)\n- [Why uTest](#why-utest)\n- [Changelog](#changelog)\n\nGetting Started\n===============\n\nMost people coming to uTest will be running tests through\n[SBT](http://www.scala-sbt.org/). Add the following to your `build.sbt` and you\ncan immediately begin defining and running tests programmatically.\n\n\n```scala\nlibraryDependencies += \"com.lihaoyi\" %% \"utest\" % \"0.9.5\" % \"test\" // Scala-JVM\nlibraryDependencies += \"com.lihaoyi\" %%% \"utest\" % \"0.9.5\" % \"test\" // Scala.js or Scala-Native\n\ntestFrameworks += new TestFramework(\"utest.runner.Framework\")\n```\n\nOr Mill:\n\n```scala\ndef mvnDeps = Seq(mvn\"com.lihaoyi::utest:0.9.5\") // Scala-JVM\ndef mvnDeps = Seq(mvn\"com.lihaoyi::utest::0.9.5\") // Scala.js or Scala-Native\n\ndef testFramework = \"utest.runner.Framework\"\n```\n\nFor Scala-Native, you will also need\n\n```scala\nnativeLinkStubs := true\n```\n\n[Gradle plugin for Scala.js and Scala Native](https://github.com/dubinsky/scalajs-gradle)\nsupports using uTest with [Gradle](https://gradle.org/).\n\nDefining and Running a Test Suite\n=================================\n\nPut this in your `src/test/scala/` folder:\n\n```scala\npackage example\n\nimport utest._\n\nclass HelloTests extends TestSuite{\n  val tests = Tests{\n    test(\"test1\"){\n      throw new Exception(\"test1\")\n    }\n    test(\"test2\"){\n      1\n    }\n    test(\"test3\"){\n      val a = List[Byte](1, 2)\n      a(10)\n    }\n  }\n}\n```\n\nYou can then run this via\n\n```text\nsbt myproject/test\n```\n\nOr \n\n```text\n./mill myproject.test\n```\n\nWhich should produce this output:\n\n```text\n-------------------------------- Running Tests --------------------------------\nSetting up CustomFramework\nX example.HelloTests.test1 4ms\n  java.lang.Exception: test1\n    example.HelloTests$.$anonfun$tests$2(HelloTests.scala:7)\n+ example.HelloTests.test2.inner 0ms  1\nX example.HelloTests.test3 0ms\n  java.lang.IndexOutOfBoundsException: 10\n    scala.collection.LinearSeqOptimized.apply(LinearSeqOptimized.scala:63)\n    scala.collection.LinearSeqOptimized.apply$(LinearSeqOptimized.scala:61)\n    scala.collection.immutable.List.apply(List.scala:86)\n    example.HelloTests$.$anonfun$tests$5(HelloTests.scala:16)\nTearing down CustomFramework\nTests: 3, Passed: 1, Failed: 2\n```\n\nThe tests are run one at a time, and any tests that fail with an exception have\ntheir stack trace printed. If the number of tests is large, a separate\nresults-summary and failures-summary will be shown after all tests have run.\nTests can either be inside zero-parameter `class`es (as shown above) or static `object`s.\n\nNesting Tests\n-------------\n\nNote that tests within the suite can nested within each other, but only\ndirectly. E.g. you cannot define tests within `if`-statements or `for`-loops.\nuTest relies on the test structure to be statically known at compile time. They\ncan be nested arbitrarily deep:\n\n```scala\npackage example\n\nimport utest._\n\nclass NestedTests extends TestSuite{\n  val tests =  Tests{\n    val x = 1\n    test(\"outer1\"){\n      val y = x + 1\n\n      test(\"inner1\"){\n        assert(x == 1, y == 2)\n        (x, y)\n      }\n      test(\"inner2\"){\n        val z = y + 1\n        assert(z == 3)\n      }\n    }\n    test(\"outer2\"){\n      test(\"inner3\"){\n        assert(x \u003e 1)\n      }\n    }\n  }\n}\n```\n\nHere, we have a tree of nested blocks, with three tests at the inner-most blocks\nof this tree: `innerest`, `inner2` and `inner3`. Test blocks can be nested\narbitrary deeply to help keep things neat, and only the inner-most blocks are\nconsidered to be tests.\n\nWhen this suite is run with\n`sbt myproject/test`, it is those three tests that get executed:\n\n```text\n------------------------------- Running Tests -------------------------------\n+ example.NestedTests.outer1.inner1 21ms  (1,2)\n+ example.NestedTests.outer1.inner2 0ms\n+ example.NestedTests.outer2.inner3 0ms\n```\n\nYou can see also that `example.NestedTests.outer1.inner1` displays\nthe value of `(x, y)` returned from the test: `(1,2)`. Returning a value from a\ntest is useful if you want to skim the test's results after a run to perform\nmanual sanity-checks on some computed value.\n\nIf you find yourself wanting to define a test in a for, loop, e.g.\n\n```scala\n// Doesn't work!\nval tests =  Tests{\n  for(fileName \u003c- Seq(\"hello\", \"world\", \"i\", \"am\", \"cow\")){\n    fileName - {\n      // lots of code using fileName\n    }\n  }\n}\n```\n\nYou can instead factor out the common code into a function, and call that from\neach distinct test case:\n\n```scala\n// Works!\nval tests = Tests{\n  def runTestChecks(fileName: String) = {\n    // lots of code using fileName\n  }\n  test(\"hello\"){ runTestChecks(\"hello\") }\n  test(\"world\"){ runTestChecks(\"world\") }\n  test(\"i\"){ runTestChecks(\"i\") }\n  test(\"am\"){ runTestChecks(\"am\") }\n  test(\"cow\"){ runTestChecks(\"cow\") }\n}\n```\n\nOr even using the [TestPath](#testpath) that is available implicitly to every\ntest, you can remove the duplication between the test name and the call to\n`runTestChecks()`:\n\n```scala\n// Also works!\nval tests = Tests{\n  def runTestChecks()(implicit path: utest.framework.TestPath) = {\n    val fileName = path.value.last\n    // lots of code using fileName\n  }\n  test(\"hello\"){ runTestChecks() }\n  test(\"world\"){ runTestChecks() }\n  test(\"i\"){ runTestChecks() }\n  test(\"am\"){ runTestChecks() }\n  test(\"cow\"){ runTestChecks() }\n}\n```\n\nRunning Tests\n-------------\n\nApart from running all tests at once using\n\n```\nsbt myproject/test\n```\n\nYou can also run individual tests using their full path e.g.\n\n```sh\nsbt 'myproject/test-only -- example.NestedTests.outer1.inner1'\nsbt 'myproject/test-only -- example.NestedTests.outer2.inner2'\nsbt 'myproject/test-only -- example.NestedTests.outer2.inner3'\n\n./mill myProject.test example.NestedTests.outer1.inner1\n./mill myProject.test example.NestedTests.outer2.inner2\n./mill myProject.test example.NestedTests.outer2.inner3\n```\n\nYou can also wrap the test selector in double quotes, which lets you run test\nwhose path segments contain spaces or other special characters:\n\n```sh\nsbt 'myproject/test-only -- \"example.NestedTests.segment with spaces.inner\"'\n\n./mill myProject.test \"example.NestedTests.segment with spaces.inner\"\n```\n\nYou can run groups of tests by providing the path to the block enclosing all of\nthem:\n\n```sh\n# runs both tests `inner1` and `inner2`\nsbt 'myproject/test-only -- example.NestedTests.outer1'\n./mill myProject.test example.NestedTests.outer1\n\n# runs all tests in the `NestedTests` test suite\nsbt 'myproject/test-only -- example.NestedTests'\n./mill myProject.test example.NestedTests\n\n# runs all tests in `NestedTests` and any other suites within `example`\nsbt 'myproject/test-only -- example'\n./mill myProject.test example\n```\n\nYou can also use the `{foo,bar}` syntax to specify exactly which tests you would\nlike to run:\n\n```sh\n# runs both tests `inner2` and `inner3`, explicitly\nsbt 'myproject/test-only -- example.NestedTests.outer1.{inner1,inner2}'\n./mill myProject.test 'example.NestedTests.outer1.{inner1,inner2}'\n\n# runs `outer1.inner1` and `outer2.inner3` but not `outer1.inner2`\nsbt 'myproject/test-only -- example.NestedTests.{outer1.inner1,outer2.inner3}'\n./mill myProject.test 'example.NestedTests.{outer1.inner1,outer2.inner3}'\n\n# also runs `inner1` and `innerest` (and any other test inside `inner1`) but not `inner2`\nsbt 'myproject/test-only -- example.NestedTests.{outer1.inner1,outer2}'\n./mill myProject.test 'example.NestedTests.{outer1.inner1,outer2}'\n```\n\nThe same syntax can be used to pick and choose specific `TestSuite`s to run, or\ntests within those test suites:\n\n```sh\n# Run every test in `HelloTests` and `NestedTests`\nsbt 'myproject/test-only -- example.{HelloTests,NestedTests}'\n\n# Runs `HelloTests.test1`, `NestedTests.outer1.inner2` and `NestedTests.outer2.inner3`\nsbt 'myproject/test-only -- example.{HelloTests.test1,NestedTests.outer2}'\nsbt 'myproject/test-only -- {example.HelloTests.test1,example.NestedTests.outer2}'\n```\n\nIn general, it doesn't really matter if you are running individual tests, groups\nof tests within a `TestSuite`, individual `TestSuite`s, or packages containing\n`TestSuite`. These all form one a single large tree of tests that you can run,\nusing the same uniform syntax.\n\nBy default, SBT and Mill run multiple test suites in parallel, so the output from\nthose suites may be interleaved. You can set `parallelExecution in Test := false`\nin your SBT config or `def testParallelism = false` in your Mill config \nto make the tests execute sequentially, so the output from\neach suite will be grouped together in the terminal.\n\nuTest defaults to emitting ANSI-colored terminal output describing the test run.\nYou can configure the colors by\n[overriding methods on your test suite](#output-formatting), or disable it\naltogether with `override def formatColor = false`.\n\nSharing Setup Code, and Sharing Setup Objects\n---------------------------------------------\n\nAs you saw in the previous section, you can define blocks tests to group them\ntogether, and have them share common initialization code in the enclosing block.\nYou can also define *mutable* values, or \"fixtures\" in the shared initialization\ncode, and each nested test with a `Tests` block gets its own copy of any mutable\nvariables defined within it:\n\n```scala\npackage example\n\nimport utest._\n\nclass SeparateSetupTests extends TestSuite{\n  val tests = Tests{\n    var x = 0\n    test(\"outer1\"){\n      x += 1\n      test(\"inner1\"){\n        x += 2\n        assert(x == 3) // += 1, += 2\n        x\n      }\n      test(\"inner2\"){\n        x += 3\n        assert(x == 4) // += 1, += 3\n        x\n      }\n    }\n    test(\"outer2\"){\n      x += 4\n      test(\"inner3\"){\n        x += 5\n        assert(x == 9) // += 4, += 5\n        x\n      }\n    }\n  }\n}\n```\n\nHere, you can see that the `x` available in each inner test block (`inner1`,\n`inner2`, `inner3`) is separate and independent: each test gets a new copy of\n`x`, modified only by that test's enclosing blocks. This helps avoid inter-test\ninterference (where a test ends up implicitly depending on some state\ninitialized by another test running earlier in the block) while still making it\nconvenient to share common setup code between the various tests in your suite.\n\nIf you want the mutable fixtures to really-truly be shared between individual\ntests (e.g. because they are expensive to repeatedly initialize) define it\noutside the `Tests{}` block in the enclosing `class`:\n\n```scala\npackage example\n\nimport utest._\n\nclass SharedFixturesTests extends TestSuite{\n  var x = 0\n  val tests = Tests{\n    test(\"outer1\"){\n      x += 1\n      test(\"inner1\"){\n        x += 2\n        assert(x == 3) // += 1, += 2\n        x\n      }\n      test(\"inner2\"){\n        x += 3\n        assert(x == 7) // += 1, += 2, += 1, += 3\n        x\n      }\n    }\n    test(\"outer2\"){\n      x += 4\n      test(\"inner3\"){\n        x += 5\n        assert(x == 16) // += 1, += 2, += 1, += 3, += 4, += 5\n        x\n      }\n    }\n  }\n}\n```\n\nHere you see that the changes to `x` are being shared between the invocations of\nall the tests. If you are initializing something expensive to share between\ntests, this allows you to avoid paying that cost multiple times, but you need to\nbe careful the tests aren't mutating shared state that could cause other tests\nto fail!\n\nOther Ways of Naming tests\n--------------------------\n\nYou can also use the `test(\"symbol\") -` syntax, if your tests are simply forwarding\nto a separate helper method to do the real testing:\n\n```scala\ntest(\"test1\") - processFileAndCheckOutput(\"input1.txt\", \"expected1.txt\")\ntest(\"test2\") - processFileAndCheckOutput(\"input2.txt\", \"expected2.txt\")\ntest(\"test3\") - processFileAndCheckOutput(\"input3.txt\", \"expected3.txt\")\n```\n\nThe `test(\"string\"){...}` and `test(\"symbol\") - ...` syntaxes are equivalent.\n\nThe last way of defining tests is with a bare `test {...}` or `test - ...`, e.g. these tests\nfrom the [Fansi](https://github.com/lihaoyi/fansi/blob/master/fansi/shared/src/test/scala/fansi/FansiTests.scala)\nproject:\n\n```scala\ntest(\"parsing\"){\n  def check(frag: fansi.Str) = {\n    val parsed = fansi.Str(frag.render)\n    assert(parsed == frag)\n    parsed\n  }\n  test - check(fansi.Color.True(255, 0, 0)(\"lol\"))\n  test - check(fansi.Color.True(1, 234, 56)(\"lol\"))\n  test - check(fansi.Color.True(255, 255, 255)(\"lol\"))\n  test{\n    (for(i \u003c- 0 to 255) yield check(fansi.Color.True(i,i,i)(\"x\"))).mkString\n  }\n  test{\n    check(\n      \"#\" + fansi.Color.True(127, 126, 0)(\"lol\") + \"omg\" + fansi.Color.True(127, 126, 0)(\"wtf\")\n    )\n  }\n\n  test{ check(square(for(i \u003c- 0 to 255) yield fansi.Color.True(i,i,i))) }\n}\n```\n\nTests defined using the `test` symbol are give the numerical names \"0\", \"1\", \"2\",\netc.. This is handy if you have a very large number of very simple test cases,\ndon't really care what each one is called, but still want to be able to run them\nand collect their result separately.\n\nAsynchronous Tests\n------------------\n\n```scala\nval tests = Tests {\n  test(\"testSuccess\"){\n    Future {\n      assert(true)\n    }\n  }\n  test(\"testFail\"){\n    Future {\n      assert(false)\n    }\n  }\n  test(\"normalSuccess\"){\n    assert(true)\n  }\n  test(\"normalFail\"){\n    assert(false)\n  }\n}\n\nTestRunner.runAsync(tests).map { results =\u003e\n  val leafResults = results.leaves.toSeq\n  assert(leafResults(0).value.isSuccess) // root\n  assert(leafResults(1).value.isSuccess) // testSuccess\n  assert(leafResults(2).value.isFailure) // testFail\n  assert(leafResults(3).value.isSuccess) // normalSuccess\n}\n```\n\nYou can have tests which return (have a last expression being) a `Future[T]`\ninstead of a normal value. You can run the suite using `.runAsync` to return a\n`Future` of the results, or you can continue using `.run` which will wait for\nall the futures to complete before returning.\n\nIn Scala.js, calling `.run` on a test suite with futures in it throws an error\ninstead of waiting, since you cannot wait for asynchronous results in Scala.js.\n\nWhen running the test suites from SBT, you do not need worry about any of this\n`run` vs `runAsync` stuff: the test runner will handle it for you and provide\nthe correct results.\n\nSmart Asserts\n=============\n\n```scala\nval x = 1\nval y = \"2\"\nassert(x \u003e 0)\nassert(x == y)\n\n// utest.AssertionError: x == y\n// x: Int = 1\n// y: String = 2\n\nassertAll( // Helper to perform multiple asserts at once\n  x \u003e 0,\n  x == y\n)\n```\n\nuTest comes with a macro-powered smart `assert`s that provide useful debugging\ninformation in the error message. These take one or more boolean expressions,\nand when they fail, will print out the names, types and values of any local\nvariables used in the expression that failed. This makes it much easier to see\nwhat's going on than Scala's default `assert`, which gives you the stack trace\nand nothing else.\n\nuTest also wraps any exceptions thrown within the assert, to help trace what\nwent wrong:\n\n```scala\nval x = 1L\nval y = 0L\nassert(x / y == 10)\n\n// utest.AssertionError: assert(x / y == 10)\n// caused by: java.lang.ArithmeticException: / by zero\n// x: Long = 1\n// y: Long = 0\n```\n\nThe origin exception is stored as the `cause` of the `utest.AssertionError`, so\nthe original stack trace is still available for you to inspect.\n\nuTest's smart asserts live on the `utest` package, and are brought into scope\nvia `import utest._`. If you want to continue using the built-in Scala asserts,\ne.g. if you want custom messages if the assert fails, those remain available as\n`Predef.assert`.\n\nArrow Asserts\n-------------\n\n```scala\n1 ==\u003e 1 // passes\nArray(1, 2, 3) ==\u003e Array(1, 2, 3) // passes\ntry{\n  1 ==\u003e 2 // throws\n}catch{case e: java.lang.AssertionError =\u003e\n  e\n}\n```\n\nYou can use `a ==\u003e b` as a shorthand for `assert(a == b)`. This results in\npretty code you can easily copy-paste into documentation.\n\nassertThrows\n---------\n\n```scala\nval e = assertThrows[MatchError]{\n  (0: Any) match { case _: String =\u003e }\n}\nprintln(e)\n\n// scala.MatchError: 0 (of class java.lang.Integer)\n```\n\n`assertThrows` allows you to verify that a block raises an exception. This\nexception is caught and returned so you can perform further validation on it,\ne.g. checking that the message is what you expect. If the block does not raise\none, an `AssertionError` is raised.\n\nAs with `assert`, `assertThrows` adds debugging information to the error messages\nif the `assertThrows` fails or throws an unexpected Exception.\n\nassertEventually and assertContinually\n--------------------------\n\n```scala\nval x = Seq(12)\nassertEventually(x == Nil)\n\n// utest.AssertionError: assertEventually(x == Nil)\n// x: Seq[Int] = List(12)\n```\n\nIn addition to a macro-powered `assert`, uTest also provides macro-powered\nversions of `assertEventually` and `assertContinually`. These are used to test asynchronous\nconcurrent operations:\n\n- `assertEventually(tests: Boolean*)`: ensure that the boolean values of `tests` all\n  become true at least once within a certain period of time.\n- `assertContinually(tests: Boolean*)`: ensure that the boolean values of `tests` all\n  remain true and never become false within a certain period of time.\n\nThese are implemented via a retry-loop, with a default retry interval of 0.1\nsecond and retries up to a total of 1 second. If you want to change this\nbehavior, you can shadow the implicit values `retryInterval` and `retryMax`, for\nexample this:\n\n```scala\nimplicit val retryMax = RetryMax(300.millis)\nimplicit val retryInterval = RetryInterval(50.millis)\n```\n\nWould set the retry-loop to happen every 50ms up to a max of 300ms.\n\nTogether, these two operations allow you to easily test asynchronous operations.\nYou can use them to help verify Liveness properties (that condition must\neventually be met) and Safety properties (that a condition is never met)\n\nAs with `assert`, `assertEventually` and `assertContinually` add debugging information to\nthe error messages if they fail.\n\nAssert Match\n------------\n\n```scala\nassertMatch(Seq(1, 2, 3)){case Seq(1, 2) =\u003e}\n// AssertionError: Matching failed Seq(1, 2, 3)\n```\n\n`assertMatch` is a convenient way of checking that a value matches a particular\nshape, using Scala's pattern matching syntax. This includes support for use of\n`|` or `_` or `if`-guards within the pattern match. This gives you additional\nflexibility over a traditional `assert(a == Seq(1, 2))`, as you can use `_` as a\nwildcard e.g. using `assertMatch(a){case Seq(1, _)=\u003e}` to match any 2-item `Seq`\nwhose first item is `1`.\n\nAs with `assert`, `assertMatch` adds debugging information to the error messages\nif the value fails to match or throws an unexpected Exception while evaluating.\n\nassertCompileError\n------------------\n\n```scala\nassertCompileError(\"true * false\")\n// CompileError.Type(\"value * is not a member of Boolean\")\n\nassertCompileError(\"(}\")\n// CompileError.Parse(\"')' expected but '}' found.\")\n```\n\n`assertCompileError` is a macro that can be used to assert that a fragment of code\n(given as a literal String) fails to compile.\n\n- If the code compiles successfully, `assertCompileError` will fail the compilation\n  run with a message.\n- If the code fails to compile, `assertCompileError` will return an instance of\n  `CompileError`, one of `CompileError.Type(pos: String, msgs: String*)` or\n  `CompileError.Parse(pos: String, msgs: String*)` to represent typechecker\n  errors or parser errors\n\nIn general, `assertCompileError` works similarly to `assertThrows`, except it does its\nchecks (that a snippet of code fails) and errors (if it doesn't fail) at\ncompile-time rather than run-time. If the code fails as expected, the failure\nmessage is propagated to runtime in the form of a `CompileError` object. You can\nthen do whatever additional checks you want on the failure message, such as\nverifying that the failure message contains some string you expect to be there.\n\nThe `assertCompileError` macro compiles the given string in the local scope and\ncontext. This means that you can refer to variables in the enclosing scope, i.e.\nthe following example will fail to compile because the variable `x` exists.\n\n```scala\nval x = 0\n\nassertCompileError(\"x + x\"),\n// [error] assertCompileError check failed to have a compilation error\n```\n\nThe returned `CompileError` object also has a handy `.check` method, which takes\na position-string indicating where the error is expected to occur, as well as\nzero-or-more messages which are expected to be part of the final error message.\nThis is used as follows:\n\n```scala\nassertCompileError(\"true * false\").check(\n  \"\"\"\nassertCompileError(\"true * false\").check(\n                   ^\n  \"\"\",\n  \"value * is not a member of Boolean\"\n)\n```\n\nNote that the position-string needs to exactly match the line of code the\ncompile-error occured on. This includes any whitespace on the left, as well as\nany unrelated code or comments sharing the same line as the `assertCompileError`\nexpression.\n\nassertGoldenLiteral\n-------------------\nGolden testing is a useful way of defining tests that assert the value of variable matches\neither a literal data structure or the contents of a file.\nFor example, in `assertGoldenLiteral`,\nyou pass in the runtime value on the left and the expected literal on the right:\n\n```scala\nval x = List(1, 2)\nassertGoldenLiteral(x, List(1, 2, 3, 4))\n```\n\nRunning this test shows you the diff between the two values as well as an environment variable you can \npass to update the literal:\n\n```text\nX test.utest.examples.HelloTests.test 75ms \n  utest.AssertionError: Actual value does not match golden data in file\n  /Users/lihaoyi/Github/utest/utest/test/src/test/utest/examples/HelloTests.scala\n  Run tests with UTEST_UPDATE_GOLDEN_TESTS=1 to apply the following patch to update the golden value\n  goldenValue != actualValue:\n  - List(1, 2, 3, 4)\n  + List(1, 2)\n    utest.asserts.AssertsPlatformSpecific.throwAssertionError(AssertsPlatformSpecific.scala:8)\n    utest.asserts.AssertsPlatformSpecific.assertGoldenLiteral(AssertsPlatformSpecific.scala:41)\n    utest.asserts.AssertsPlatformSpecific.assertGoldenLiteral$(AssertsPlatformSpecific.scala:6)\n    utest.package$.assertGoldenLiteral(package.scala:8)\n    test.utest.examples.HelloTests.$init$$$anonfun$1$$anonfun$1(HelloTests.scala:16)\n```\n\nRunning the test with the `UTEST_UPDATE_GOLDEN_TESTS=1` environment variable will update the source\ncode of your test suite in-place, using [PPrint](https://github.com/com-lihaoyi/PPrint) to convert\nthe left-hand value into a string to splice into the source code. While this won't work for more\ncomplex data structures, it works well enough for the common cases which involve primitives,\ncollections, and `case class`es. You can customize the printing logic by overriding \n`def goldenLiteralPrinter` in a [custom framework](#configuring-utest). \n\n### Using assertGoldenLiteral in helper methods\n\n`assertGoldenLiteral` can also be used in helper methods, in which case the helper should take\nthe golden literal as an instance of type `utest.framework.GoldenFix.Span[T]` to capture the \nsource-metadata necessary to update the literal (filename, start/end offsets), as well as\nan implicit `utest.framework.GoldenFix.Reporter` (if not written within a `TestSuite` class\nwhich provides the reporter implicitly in scope):\n\n```scala\ndef goldenHelper(value: List[Int],\n           golden: utest.framework.GoldenFix.Span[List[Int]]) = {\n  assertGoldenLiteral(value, golden)\n}\ntest(\"test\"){\n  val x = List(1, 2)\n  goldenHelper(x, List(1, 2))\n}\n```\n\n### Using assertGoldenLiteral to write your test \n\nYou can also use `assertGoldenLiteral` to automatically fill in the expected value the\nfirst time you run the test by passing in `()` as the current literal value, and running the\ntest with `UTEST_UPDATE_GOLDEN_TESTS=1`. For example, starting with:\n\n```scala\nval x = List(1, 2)\nassertGoldenLiteral(x, ())\n```\n\nAfter running the test with `UTEST_UPDATE_GOLDEN_TESTS=1`, the code will be updated to\n\n```scala\nval x = List(1, 2)\nassertGoldenLiteral(x, List(1, 2))\n```\n\nThis means it is easy to write the logic of the tests and have uTest \"fill in the blanks\"\nfor you.\n\nSee\n[Golden Literal Testing in uTest 0.9.0](https://www.lihaoyi.com/post/GoldenLiteralTestinginuTest090.html)\nfor more details.\n\n`assertGoldenLiteral` is only supported on Scala-JVM, and not on Scala-JS and Scala-Native\n\nassertGoldenFile\n----------------\n\n`assertGoldenFile(String, java.nio.file.Path)` can be used to check that a `String`\nvalue matches the contents in the file at the given `java.nio.file.Path`, and update the file\nwhen `UTEST_UPDATE_GOLDEN_TESTS=1` is passed. A non-existent file is treated as equivalent\nto an empty string `\"\"`, and running the test with `UTEST_UPDATE_GOLDEN_TESTS=1` will \n\n\n```scala\ntest(\"test\"){\n  val expected =\n    \"\"\"I am cow\n      |Hear me moo\n      |I weigh twice as much as you\n      |And I look good on the barbecue\"\"\".stripMargin\n  assertGoldenFile(expected, java.nio.file.Path.of(\"/Users/lihaoyi/Github/utest/hello.txt\"))\n}\n```\n\n```text\nX test.utest.examples.HelloTests.test 72ms \n  utest.AssertionError: Actual value does not match golden data in file\n  /Users/lihaoyi/Github/utest/hello.txt\n  Run tests with UTEST_UPDATE_GOLDEN_TESTS=1 to apply the following patch to update the golden value\n  goldenValue != actualValue:\n  - I am cow\n    I am cow\n    Hear me moo\n  - Moo\n  + I weigh twice as much as you\n  + And I look good on the barbecue\n    utest.asserts.AssertsPlatformSpecific.throwAssertionError(AssertsPlatformSpecific.scala:8)\n    utest.asserts.AssertsPlatformSpecific.assertGoldenFile(AssertsPlatformSpecific.scala:29)\n    utest.asserts.AssertsPlatformSpecific.assertGoldenFile$(AssertsPlatformSpecific.scala:6)\n    utest.package$.assertGoldenFile(package.scala:8)\n    test.utest.examples.HelloTests.$init$$$anonfun$1$$anonfun$1(HelloTests.scala:28)\n```\n\nRunning the test again with `UTEST_UPDATE_GOLDEN_TESTS=1` will update the file on disk to\nuse the latest value present during the test.\n\n`assertGoldenFile` is only supported on Scala-JVM, and not on Scala-JS and Scala-Native\n\nTest Utilities\n==============\n\nuTest provides a range of test utilities that aren't strictly necessary, but aim\nto make your writing of tests much more convenient and DRY.\n\n\nTestPath\n--------\n\n```scala\npackage example\n\nimport utest._\n\nobject TestPathTests extends TestSuite{\n  val tests = Tests{\n    'testPath{\n      'foo {\n        assert(implicitly[utest.framework.TestPath].value == Seq(\"testPath\", \"foo\"))\n      }\n    }\n  }\n}\n```\n\nuTest exposes the path to the current test to the body of the test via the\n`utest.framework.TestPath` implicit. This can be used to print debugging\ninformation while the test is running (\"test foo.bar.baz 50% done\") or to\navoid repetition between the test name and test body.\n\nOne example is the Fastparse test suite, which uses the name of the test to\nprovide the repository that it needs to clone and parse:\n\n```scala\ndef checkRepo(filter: String =\u003e Boolean = _ =\u003e true)\n             (implicit testPath: utest.framework.TestPath) = {\n  val url = \"https://github.com/\" + testPath.value.last\n  import sys.process._\n  val name = url.split(\"/\").last\n  if (!Files.exists(Paths.get(\"target\", \"repos\", name))){\n    println(\"CLONING\")\n    Seq(\"git\", \"clone\", url, \"target/repos/\"+name, \"--depth\", \"1\").!\n  }\n  checkDir(\"target/repos/\"+name, filter)\n}\n\n\"lihaoyi/fastparse\" - checkRepo()\n\"scala-js/scala-js\" - checkRepo()\n\"scalaz/scalaz\" - checkRepo()\n\"milessabin/shapeless\" - checkRepo()\n\"akka/akka\"- checkRepo()\n\"lift/framework\" - checkRepo()\n\"playframework/playframework\" - checkRepo()\n\"PredictionIO/PredictionIO\" - checkRepo()\n\"apache/spark\" - checkRepo()\n```\n\nThis allows us to keep the tests DRY - avoiding having to repeat the name of the\nrepo in the name of the test for every test we define - as well as ensuring that\nthey always stay in sync.\n\nIf you need additional metadata such as line-numbers or file-paths or class or\npackage names, you can use the\n[SourceCode](https://github.com/lihaoyi/sourcecode) library's implicits to pull\nthem in for you.\n\nLocal Retries\n-------------\n\n```scala\nobject LocalRetryTests extends utest.TestSuite{\n  val flaky = new FlakyThing\n  def tests = Tests{\n    test(\"hello\") - retry(3){\n      flaky.run\n    }\n  }\n}\n```\n\nYou can wrap individual tests, or even individual expressions, in a `retry`\nblock to make them retry a number of times before failing. That is very useful\nfor dealing with small points of flakiness within your test suite. A `retry`\nblock simply retries its body up to the specified number of times; the first run\nthat doesn't throw an exception returns the value returned by that run.\n\nYou can also use [Suite Retries](#suite-retries) if you want to configure\nretries more globally across your test suite.\n\nConfiguring uTest\n=================\n\nPer-Run Setup/Teardown, and other test-running Config\n-----------------------------------------------------\n\nTo configure things which affect an entire test run, and not any individual\n`TestSuite` object, you can create your own subclass of `utest.runner.Framework`\nand override the relevant methods.\n\nFor example, if you need to perform some action (initialize a database, cleanup\nthe filesystem, etc.) not just per-test but per-run, you can do that by defining\na custom `utest.runner.Framework` and overriding the `setup` and `teardown`\nmethods:\n\n```scala\nclass CustomFramework extends utest.runner.Framework{\n  override def setup() = {\n    println(\"Setting up CustomFramework\")\n  }\n  override def teardown() = {\n    println(\"Tearing down CustomFramework\")\n  }\n}\n```\n\nAnd then telling SBT to run tests using the custom framework:\n\n```scala\ntestFrameworks += new TestFramework(\"test.utest.CustomFramework\"),\n```\n\nThis is handy for setup/teardown that is necessary but too expensive to do\nbefore/after every single test, which would be the case if you used\n[Test Wrapping](#test-wrapping) to do it.\n\nApart from setup and teardown, there are other methods on\n`utest.runner.Framework` that you can override to customize:\n\n```scala\n  /**\n    * Override to run code before tests start running. Useful for setting up\n    * global databases, initializing caches, etc.\n    */\n  def setup() = ()\n\n  /**\n    * Override to run code after tests finish running. Useful for shutting\n    * down daemon processes, closing network connections, etc.\n    */\n  def teardown() = ()\n\n  /**\n    * How many tests need to run before uTest starts printing out the test\n    * results summary and test failure summary at the end of a test run. For\n    * small sets of tests, these aren't necessary since all the output fits\n    * nicely on one screen; only when the number of tests gets large and their\n    * output gets noisy does it become valuable to show the clean summaries at\n    * the end of the test run.\n    */\n  def showSummaryThreshold = 30\n\n  /**\n    * Whether to use SBT's test-logging infrastructure, or just println.\n    *\n    * Defaults to println because SBT's test logging doesn't seem to give us\n    * anything that we want, and does annoying things like making a left-hand\n    * gutter and buffering input by default\n    */\n  def useSbtLoggers = false\n\n  def resultsHeader = DefaultFormatters.resultsHeader\n  def failureHeader = DefaultFormatters.failureHeader\n  \n  \n  def startHeader(path: String) = DefaultFormatters.renderBanner(\"Running Tests\" + path)\n```\n\nOutput Formatting\n-----------------\n\nYou can control how the output of tests gets printed via overriding methods on\nthe `Framework` class, described above. For example, this snippet overrides the\n`exceptionStackFrameHighlighter` method to select which stack frames in a stack\ntrace are more relevant to you, so they can be rendered more brightly:\n\n```scala\nclass CustomFramework extends utest.runner.Framework{\n  override def exceptionStackFrameHighlighter(s: StackTraceElement) = {\n    s.getClassName.contains(\"utest.\")\n  }\n}\n```\n\nThis results in stack traces being rendered as such:\n\n![docs/StackHighlight.png](docs/StackHighlight.png)\n\nthe `utest.runner.Framework` provides a wide range of hooks you can use to\ncustomize how the uTest output is colored, wrapped, truncated or formatted:\n\n```scala\ndef formatColor: Boolean = true\ndef formatTruncateHeight: Int = 15\ndef formatWrapWidth: Int = 100\n\ndef formatValue(x: Any) = testValueColor(x.toString)\n\ndef toggledColor(t: utest.shaded.fansi.Attrs) = if(formatColor) t else utest.shaded.fansi.Attrs.Empty\ndef testValueColor = toggledColor(utest.shaded.fansi.Color.Blue)\ndef exceptionClassColor = toggledColor(utest.shaded.fansi.Underlined.On ++ utest.shaded.fansi.Color.LightRed)\ndef exceptionMsgColor = toggledColor(utest.shaded.fansi.Color.LightRed)\ndef exceptionPrefixColor = toggledColor(utest.shaded.fansi.Color.Red)\ndef exceptionMethodColor = toggledColor(utest.shaded.fansi.Color.LightRed)\ndef exceptionPunctuationColor = toggledColor(utest.shaded.fansi.Color.Red)\ndef exceptionLineNumberColor = toggledColor(utest.shaded.fansi.Color.LightRed)\ndef exceptionStackFrameHighlighter(s: StackTraceElement) = true\n\ndef formatResultColor(success: Boolean) = toggledColor(\n  if (success) utest.shaded.fansi.Color.Green\n  else utest.shaded.fansi.Color.Red\n)\n\ndef formatMillisColor = toggledColor(utest.shaded.fansi.Bold.Faint)\n```\n\nAny methods overriden on your own custom `Framework` apply to every `TestSuite`\nthat is run. If you want to further customize how a single `TestSuite`'s output\nis formatted, you can override `utestFormatter` on that test suite.\n\nNote that uTest uses an internal copy of the\n[Fansi](https://www.github.com/lihaoyi/fansi) library, vendored at\n`utest.shaded.fansi`, in order to avoid any compatibility problems with any of your\nother dependencies. You can use `utest.shaded.fansi` to construct the colored `utest.shaded.fansi.Str`s\nthat these methods require, or you could just return colored `java.lang.String`\nobjects containing ANSI escapes, created however you like, and they will be\nautomatically parsed into the correct format.\n\nSuite Retries\n-------------\n\nYou can mix in the `TestSuite.Retries` trait to any `TestSuite` and define the\n`utestRetryCount` int to enable test-level retries for all tests within a suite:\n\n```scala\n\nobject SuiteRetryTests extends TestSuite with TestSuite.Retries{\n  override val utestRetryCount = 3\n  val flaky = new FlakyThing\n  def tests = Tests{\n    'hello{\n      flaky.run\n    }\n  }\n}\n\n```\n\nYou can also use [Local Retries](#local-retries) if you want to only retry\nwithin specific tests or expressions instead of throughout the entire suite.\n\nRunning code before and after test cases\n----------------------------------------\n\nuTest offers the `utestBeforeEach` and `utestAfterEach` methods that you can\noverride on any `TestSuite`, these methods are invoked before and after running\neach test.\n\n```scala\ndef utestBeforeEach(path: Seq[String]): Unit = ()\ndef utestAfterEach(path: Seq[String]): Unit = ()\n```\n\nThese are equivalent to `utestWrap` but easier to use for simple cases.\n\n```scala\npackage example\n\nimport utest._\nobject BeforeAfterEachTest extends TestSuite {\n  var x = 0\n  override def utestBeforeEach(path: Seq[String]): Unit = {\n    println(s\"on before each x: $x\")\n    x = 0\n  }\n  override def utestAfterEach(path: Seq[String]): Unit =\n    println(s\"on after each x: $x\")\n\n  val tests = Tests{\n    test(\"outer1\"){\n      x += 1\n      test(\"inner1\"){\n        x += 2\n        assert(x == 3) // += 1, += 2\n        x\n      }\n      test(\"inner2\"){\n        x += 3\n        assert(x == 4) // += 1, += 3\n        x\n      }\n    }\n    test(\"outer2\"){\n      x += 4\n      test(\"inner3\"){\n        x += 5\n        assert(x == 9) // += 4, += 5\n        x\n      }\n    }\n  }\n}\n```\n```text\n-------------------------------- Running Tests --------------------------------\nSetting up CustomFramework\non before each x: 0\non after each x: 3\n+ example.BeforeAfterEachTest.outer1.inner1 22ms  3\non before each x: 3\non after each x: 4\n+ example.BeforeAfterEachTest.outer1.inner2 1ms  4\non before each x: 4\non after each x: 9\n+ example.BeforeAfterEachTest.outer2.inner3 0ms  9\nTearing down CustomFramework\nTests: 3, Passed: 3, Failed: 0\n```\n\nBoth `utestBeforeEach` and `utestAfterEach` runs inside `utestWrap`'s `body`\ncallback.\n\nIf you need something fancier than what `utestBeforeEach` or `utestAfterEach`\nprovide, e.g. passing initialized objects into the main test case or tearing\nthem down after the test case has completed, feel free to define your test\nwrapper/initialization function and use it for each test case:\n\n\n```scala\ndef myTest[T](func: Int =\u003e T) = {\n  val fixture = 1337 // initialize some value\n  val res = func(fixture) // make the value available in the test case\n  assert(fixture == 1337) // properly teardown the value later\n  res\n}\n\ntest(\"test\") - myTest{ fixture =\u003e\n  // do stuff with fixture\n}\n```\n\nThe above `myTest` function can also take a [TestPath](#testpath) implicit if it\nwants access to the current test's path.\n\nRunning code before and after test suites\n-----------------------------------------\n\nIf you're looking for something like `utestBeforeAll`, you can add your code to\nthe object body, and you can also use lazy val to delay the initialization until\nthe test suite object is created.\n\nuTest offers the `utestAfterAll` method that you can override on any\ntest suite, this method is invoked after running the entire test suite.\n\n```scala\ndef utestAfterAll(): Unit = ()\n```\n\n```scala\npackage example\n\nimport utest._\nobject BeforeAfterAllSimpleTests extends TestSuite {\n  println(\"on object body, aka: before all\")\n\n  override def utestAfterAll(): Unit = {\n    println(\"on after all\")\n  }\n\n  val tests = Tests {\n    test(\"outer1\"){\n      test(\"inner1\"){\n        1\n      }\n      test(\"inner2\"){\n        2\n      }\n    }\n  }\n}\n\n```\n```text\n-------------------------------- Running Tests --------------------------------\nSetting up CustomFramework\non object body, aka: before all\n+ example.BeforeAfterAllSimpleTests.outer1.inner1 2ms  1\n+ example.BeforeAfterAllSimpleTests.outer1.inner2 0ms  2\non after all\n```\n\nTest Wrapping\n-------------\n\nuTest exposes the `utestWrap` function that you can override on any test suite:\n\n```scala\ndef utestWrap(path: Seq[String], runBody: =\u003e concurrent.Future[Any])\n             (implicit ec: ExecutionContext): concurrent.Future[Any]\n```\n\nThis is a flexible function that wraps every test call; you can use it to:\n\n- Perform initialization before evaluating `runBody`\n- Perform cleanup after the completion of `runBody` via `runBody.onComplete`\n- Perform retries by executing `runBody` multiple times\n- Log the start and end times of each test, along with the `path` of that test,\n  e.g. `Seq(\"outer\", \"inner1\", \"innerest\")` for the test `outer.inner1.innerest`\n\nGenerally, if you want to perform messy before/after logic around every\nindividual test, override `utestWrap`. Please remember to call the\n`utestBeforeEach` and `utestAfterEach` methods when needed.\n\n`runBody` is a future to support asynchronous testing, which is the only way to\ntest things like Ajax calls in [Scala.js](#scalajs-and-scala-native)\n\n\n\nScala.js and Scala-Native\n=========================\n\nuTest is completely compatible with Scala.js and Scala-Native: the above sections on\ndefining a test suite, asserts and the test-running API all work unchanged under\nScalaJS, with minor differences:\n\n- ScalaJS does not support parallelism, and as such only single-threaded\n  `ExecutionContexts` like `utest.ExecutionContext.runNow` or\n  `scala.scalajs.concurrent.JSExecutionContext.runNow` work. When run via SBT,\n  `--parallel` has no effect.\n- [Eventually and Continually](#eventually-and-continually) are not supported,\n  as they rely on a blocking retry-loop whereas you can't block in ScalaJS.\n\nApart from these differences, there should be no problem compiling uTest\nTestSuites via Scala.js and running them on Node.js, in the browser, or (with\nScala-Native) on LLVM.\n\nNote that Scala-Native support, like Scala-Native, is experimental. While it is\ntested in a few projects (uTest's own test suite runs in Scala-Native), it does\nhave it's own quirks (e.g. `NullPointerException`s appear to be fatal) and does\nnot have the weight of third-party usage that the Scala-JVM and Scala.js\nversions of uTest have.\n\nRunning uTest Standalone\n========================\n\nuTest exposes a straightforward API that allows you to run tests, receive\nresults and format them in a nice way when used standalone, without using SBT's\ntest integration. The following code snippet demonstrates how to define tests\nand run them directly:\n\n```scala\nimport utest._\nval tests = Tests{\n  test(\"test1\"){\n    // throw new Exception(\"test1\")\n  }\n  test(\"test2\"){\n    test(\"inner\"){\n      1\n    }\n  }\n  test(\"test3\"){\n    val a = List[Byte](1, 2)\n    // a(10)\n  }\n}\n\n// Run and return results\nval results1 = TestRunner.run(tests)\n```\n\nThe `TestRunner.run` call can be customized with additional arguments to control\nhow the code is run, or can be replaced with `.runAsync` to handle asynchronous\ntesting, or `.runAndPrint`/`.runAndPrintAsync` if you want to print the results\nof tests as they complete using the normal output formatter:\n\n```scala\n\n// Run, return results, and print streaming output with the default formatter\nval results2 = TestRunner.runAndPrint(\n  tests,\n  \"MyTestSuiteA\"\n)\n// Run, return results, and print output with custom formatter and executor\nval results3 = TestRunner.runAndPrint(\n  tests,\n  \"MyTestSuiteA\",\n  executor = new utest.framework.Executor{\n    override def utestWrap(path: Seq[String], runBody: =\u003e Future[Any])\n                 (implicit ec: ExecutionContext): Future[Any] = {\n      println(\"Getting ready to run \" + path.mkString(\".\"))\n      utestBeforeEach()\n      runBody.andThen {\n        case _ =\u003e utestAfterEach()\n      }\n    }\n  },\n  formatter = new utest.framework.Formatter{\n    override def formatColor = false\n  }\n)\n```\n\nLastly, you can also run `TestSuite` objects in the same way:\n\n```scala\n// Run `TestSuite` object directly without using SBT, and use\n// its configuration for execution and output formatting\nobject MyTestSuite extends TestSuite{\n  val tests = Tests{\n    test(\"test1\"){\n      // throw new Exception(\"test1\")\n    }\n    test(\"test2\"){\n      test(\"inner\"){\n        1\n      }\n    }\n    test(\"test3\"){\n      val a = List[Byte](1, 2)\n      // a(10)\n    }\n  }\n}\n\nval results4 = TestRunner.runAndPrint(\n  MyTestSuite.tests,\n  \"MyTestSuiteB\",\n  executor = MyTestSuite,\n  formatter = MyTestSuite\n)\n```\n\nuTest provides helpers to render the standard summary reports at the end of a\ntest run, once all your results are in:\n\n```scala\n// Show summary and exit\nval (summary, successes, failures) = TestRunner.renderResults(\n  Seq(\n    \"MySuiteA\" -\u003e results1,\n    \"MySuiteA\" -\u003e results2,\n    \"MySuiteA\" -\u003e results3,\n    \"MySuiteB\" -\u003e results4\n  )\n)\nif (failures \u003e 0) sys.exit(1)\n```\n\nYou can thus use uTest anywhere you can run Scala code, even when not using SBT:\nin a normal `main` method, within [Ammonite](http://ammonite.io/) scripts, or\nelsewhere.\n\n\n\nWhy uTest\n=========\n\nuTest aims to give you the things that everyone needs to run tests, giving you\none obvious way to do common tasks while testing. uTest is simple and compact,\nletting you avoid thinking about it so you can focus on what's most important:\nyou tests.\n\nHence uTest provides:\n\n- A simple, uniform syntax for\n  [delimiting tests and grouping tests together as blocks](#nesting-tests):\n  `test(\"test\"){ ... }`\n\n- A simple, uniform syntax for [running tests](#running-tests): `foo.BarTests`,\n  `foo.BarTests.baz.qux`, `foo.BarTests.{baz,qux}` or `foo.{BarTests,BazTests}`\n\n- A simple, uniform syntax for [Smart Asserts](#smart-asserts), that save you\n  the day-to-day drudgery of printing out the value of variables when things\n  fail\n\n- [Isolation of tests within the same suite](#sharing-setup-code-and-sharing-setup-objects),\n  to avoid inter-test interference due to mutable state\n\nuTest tries to provide things that every developer needs, in their minimal,\nessential form. It intentionally avoids redundant/unnecessary features or\nsyntaxes that bloat the library and make it harder to developers to pick up,\nwhich I find to be common in other popular testing libraries like\n[Scalatest](http://www.scalatest.org/) or\n[Specs2](https://etorreborre.github.io/specs2/):\n\n- Fluent English-like code: matchers like [`shouldBe` or `should not\n  be`](http://www.scalatest.org/user_guide/using_matchers#checkingForEmptiness)\n  or [`mustbe_==`](http://etorreborre.github.io/specs2/guide/org.specs2.guide.Matchers.html)\n  don't really add anything, and it doesn't really matter whether you name each\n  test block using [`should`, `when`, `can`,\n  `must`](http://doc.scalatest.org/2.0/#org.scalatest.Spec),\n  [`feature(\"...\")`](http://doc.scalatest.org/2.0/#org.scalatest.FlatSpec) or\n  [`it should \"...\"`](http://doc.scalatest.org/2.0/#org.scalatest.FlatSpec)\n\n- [Multiple redundant ways](http://www.scalatest.org/user_guide/selecting_a_style)\n  of defining test suites, individual tests and blocks of related tests\n\n- Legacy code, like ScalaTests [time\n  package](http://doc.scalatest.org/2.0/#org.scalatest.time.package), now\n  obsolete with the introduction of\n  [scala.concurrent.duration](http://www.scala-lang.org/api/current/index.html#scala.concurrent.duration.package).\n\nWhile uTest has and will continue to slowly grow and add more features, it is\nunlikely that it will ever reach the same level of complexity that other testing\nlibraries are currently at.\n\nChangelog\n=========\n0.9.5\n-----\n\n* Fix pathological performance of stringdiff algorithm on large assertion diffs [#412](https://github.com/com-lihaoyi/utest/pull/412)\n* Fixes for crashes in named pattern matches\n\n\n0.9.2\n-----\n\n* Fix pathological performance in `def splitLines` affecting assertion diffs [#409](https://github.com/com-lihaoyi/utest/pull/409)\n* Bump PPrint version to fix `assertGoldenValue` code-generation for `HashMap`, `HashSet`, and `ArraySeq` [#408](https://github.com/com-lihaoyi/utest/pull/408)\n\n\n0.9.1\n-----\n\n* Don't truncate large data in golden testing [#399](https://github.com/com-lihaoyi/utest/pull/399)\n\n0.9.0\n-----\n\n* uTest now uses a vendored version of [PPrint](https://github.com/com-lihaoyi/PPrint)\n  to print out the value of local variables found during assertion errors. This includes proper\n  formatting, syntax highlighting, and a diff of the two values whenever an `a == b` equality\n  check fails:\n\n![PrettyPrint.png](docs/PrettyPrint.png)\n  \n* Golden testing is now supported via [assertGoldenLiteral](#assertgoldenliteral) and\n  [assertGoldenFile](#assertgoldenfile). This allows uTest to help you fill in the\n  \"expected\" value of simple assertions the first time you run the test, and keep\n  that value up to date as the behavior of your code evolves. See\n  [Golden Literal Testing in uTest 0.9.0](https://www.lihaoyi.com/post/GoldenLiteralTestinginuTest090.html)\n  for more details\n\n![Golden.png](docs/Golden.png)\n\n* Renamings: these are a breaking changes that will cause some inconvenience for people \n  upgrading, but should result in a much more consistent user experience going forward\n  * `compileError` is now `assertCompileError`\n  * `eventually` is now `assertEventually`\n  * `continually` is now `assertContinually`\n  * `intercept` is now `assertThrows`\n\n* Test suites can now be `class`es rather than `object`s. `object`s are still supported for backwards \n  compatibility, but using `class`es provide better scoping and encapsulation and\n  is the recommended style going forward [#173](https://github.com/com-lihaoyi/utest/issues/173)\n\n* Fixed a lot of old bugs and tickets\n  [#334](https://github.com/com-lihaoyi/utest/issues/334)\n  [#319](https://github.com/com-lihaoyi/utest/issues/319)\n  [#252](https://github.com/com-lihaoyi/utest/issues/252)\n  [#233](https://github.com/com-lihaoyi/utest/issues/233)\n  [#219](https://github.com/com-lihaoyi/utest/issues/219)\n  [#190](https://github.com/com-lihaoyi/utest/issues/190)\n  [#97](https://github.com/com-lihaoyi/utest/issues/97)\n\n0.8.9\n-----\n\n* More fixes for failed assertion line numbers [#382](https://github.com/com-lihaoyi/utest/pull/382)\n\n\n0.8.8\n-----\n\n* More fixes for failed assertion line numbers [#381](https://github.com/com-lihaoyi/utest/pull/381)\n\n0.8.7\n-----\n\n* Fix line numbers in failed assertion traces in Scala 3 [#380](https://github.com/com-lihaoyi/utest/pull/380)\n\n0.8.5\n-----\n\n* Run `Future` tests sequentially, not concurrently [#359](https://github.com/com-lihaoyi/utest/pull/359)\n* Minimum version of Java bumped from 8 to 11\n\n0.8.4\n-----\n\n* Avoid crashing if test logs have invalid ANSI escape codes [#344](https://github.com/com-lihaoyi/utest/pull/344)\n\n0.8.3\n-----\n\n* Support for Scala-Native 0.5.0\n\n0.8.2\n-----\n\n* Fix compiler warning when using `utest.framework.TestPath` [#309](https://github.com/com-lihaoyi/utest/pull/309)\n\n0.8.1\n-----\n\n* Add `++` to `Tests` so that test suites can be concatenated\n* Add `.prefix(name: String)` to `Tests` to nest all of its tests under a single test group with a given name\n\n0.8.0\n-----\n\n- Drop support for Scala.js 0.6\n- Bump Scala.js to 1.10 (minimum version supported is 1.8)\n- Bump Scala versions to latest (2.12.16, 2.13.8, 3.1.3)\n\n0.7.11\n-----\n\n- Add support for Scala 3 on Scala Native\n\n0.7.10\n-----\n\n- Add support for Scala 3.0.0\n\n0.7.9\n-----\n\n- Add support for Scala 3.0.0-RC3\n- Bump Scala.js from 1.4.0 to 1.5.1\n\n0.7.8\n-----\n\n- Add support for Scala 3.0.0-RC2\n- Support Scala 3 on Scala.js\n\n0.7.7\n-----\n\n- Re-publish to maven central only. The version 0.7.6 broke binary compatibility\n  with JDK 8.\n\n0.7.6\n-----\n\n- Support for Scala-Native 0.4.x\n\n0.7.4\n-----\n\n- Add support for Scala.js 1.0.0\n\n0.7.3\n-----\n\n- Add support for Scala.js 1.0.0-RC2\n\n0.7.2\n-----\n\n- Add support for Scala.js 1.0.0-RC1\n\n0.7.1\n-----\n\n- Changed test syntax to `test(\"foo\"){...}`, `test{...}`. Old syntax is now\n  deprecated.\n\n0.6.9\n-----\n\n- Added support for Scala 2.13.0 Final\n- Dropped support for Scala 2.10.x, 2.11.x\n- Temporarily dropped support for Scala.js 1.0.0-M8, Scala-native 0.4.0-M2\n\n0.6.7\n-------------------\n- Add support for Scala 2.13.0-RC1\n- Use IndexedSeq instead of Array in `Tests` macro\n\n0.6.6\n-------------------\n- Add support for Scala 2.13.0-M5\n- Upgrade Scala 2.13.0-M2 to 2.13.0-M3\n- Upgrade Scala.JS 0.6.22 to 0.6.25\n- Upgrade Scala.JS 1.0.0-M3 to 1.0.0-M5\n- Upgrade Scala Native 0.3.6 to 0.3.7\n- Replace Scala.JS' deprecated `TestUtils` with portable-scala-reflect\n\n0.6.5\n-----\n- Bugfix where sometimes all tests would pass but report as failed (thanks @eatkins)\n- By default, don't cut-off and wrap output\n- (Hopefully) fix intermittent `IllegalStateException: Unknown opcode 5` exceptions occuring with Scala.JS.\n\n0.6.4\n-----\n- Returning `null` from a test case no longer blows up\n- Added `utest.runner.MillFramework`\n\n0.6.3\n-----\n- Added support for Scala.js 1.0.0-M2.\n\n0.6.2\n-----\n- Fix cross-publishing for Scala.js, which was borked in 0.6.0\n- Ensure utestAfterEach be executed regardless of a test failure\n\n0.6.0\n-----\n\n- Migrate formatting-related configuration options from `utest.TestSuite` onto\n  the `utest.runner.Framework`, as described [here](#output-formatting).\n\n- Added the `exceptionStackFrameHighlighter` formatting hook, letting you choose\n  which stack frames in an exception are of interest to you so they can be\n  rendered more brightly.\n\n0.5.4\n-----\n\n- Added hooks for\n  [Running code before and after test cases](#running-code-before-and-after-test-cases)\n  and\n  [Running code before and after test suites](#running-code-before-and-after-test-suites),\n  thanks to [Diego Alvarez](https://github.com/d1egoaz)\n\n0.5.3\n-----\n\n- Cross-publish for Scala 2.13.0-M2, Scala.js 0.6.20, Scala-Native 0.3.3\n\n- Stack traces for chained exceptions (i.e. those with a `.getCause != null`)\n  are now properly displayed when tests fail\n\n- Portions of stack traces caused by the internals of the `assert` macros are\n  now hidden, since they aren't relevant to any failure in user code\n\n- Revamped test output format, motivated by\n  [drhumlen](https://github.com/drhumlen)'s\n  [PR 113](https://github.com/lihaoyi/utest/pull/113), which should be much\n  easier to read and skim\n\n- Much smarter test-output-value truncation, now based on lines-of-output\n  (including wrapping) rather than number-of-characters\n\n- Line-wrapping of output is now indentation aware: it wraps to the next line\n  with the same indentation, preserving the outline of indentation on the left\n  making it easier to skim\n\n- How long tests take (im milliseconds) is now displayed in the standard test\n  output format\n\n- Hierarchical test summary and failure-summary are now only shown when you have\n  a large number of tests, since it's not use when running individual or small\n  numbers of tests. The default threshold is 20, which can be configured by\n  defining a custom framework overriding `showSummaryThreshold`\n\n- Revamped test-query system, now allowing you to run multiple groups of tests\n  at once via `test-only -- mypackage.{foo,bar,baz}` or `{mypackage,\n  myotherpackage}` or `mypackage.{foo,bar.{baz,qux}}`\n\n- Overhauled the execution model of test suites: now only the inner-most blocks\n  within your `TestSuite{...}` block count as tests, and the surrounding blocks\n  do not. Thus the surrounding blocks no longer show pass/fail status, return a\n  test result-value, or get run independently.\n\n- Various user errors (non-existent test, non-existing test suite, invalid test\n  query syntax) now give slightly more friendly error messages\n\n- Using uTest with `fork in Test := true` in SBT no longer gives an incorrect\n  results summmary\n\n- Fix problem with lazy vals in test blocks crashing the compiler\n  [#67](https://github.com/lihaoyi/utest/issues/67). Note that the issue is only\n  fixed on 2.12.3, and not on Scala 2.10.x or 2.11.x.\n\n- Deprecated the `'foo{...}` syntax for defining tests. We should standardize on\n  `test(\"foo\"){...}` or `test(\"foo\"){...}`\n\n- The `TestSuite{...}` for defining a block of tests is now deprecated; it never\n  actually defined a `TestSuite` object, so the name was pretty misleading. The\n  new syntax is `Tests{...}`\n\n- Remove the `MultipleErrors` wrapper when you test more than one expression in\n  an `assert` and multiple of them fail. Now only the first expression in the\n  `assert` call which fails will have it's exception thrown.\n\n- Moved [smart asserts](#smart-asserts) from being embedded into the `TestSuite`\n  objects directly onto the `utest` package, so they are pulled in by the\n  `import utest._` import.\n\n0.4.8\n-----\n\n- Scala Native support.\n\n0.4.7\n-----\n\n- Scala 2.13 support\n- Compile for Scala 2.12 with method optimisations (`-opt:l:method`)\n\n0.4.6\n-----\n\n* Upgrade Scala.JS to 0.6.16.\n* Upgrade Scala to 2.11.11 and 2.12.2.\n* Avoid using `getStackTraceString` deprecated in Scala 2.13\n\n0.4.5\n-----\n\n- Catch Fatal exceptions like ClassCasts in Scala.JS.\n\n0.4.4\n-----\n\n- Scala 2.12 support\n\n0.4.3\n-----\n\n- Generalize `==\u003e` asserts to work on `Array`s\n- Shiny new [CI build](https://travis-ci.org/lihaoyi/utest) and\n  [Gitter Chat](https://gitter.im/lihaoyi/utest?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n0.4.2\n-----\n\n- Move errors into `utest.*` from `utest.framework.*`\n- Removed `acyclic` hack variable\n\n0.4.1\n-----\n\n- Fix usage of by-name function calls within tests #55\n\n0.4.0\n-----\n\n- `foo: @Show` annotation lets you tell uTest to print out arbitrary expressions\n  within the test suite when things fail, in addition to the default of local\n  variables\n\n- You can use `a ==\u003e b` to assert equality within a test suite, in a form that's\n  pretty enough to use as documentation\n\n- `compileError` now properly passes when an expression would fail to compile\n  due to `@compileTimeOnly` annotations\n\n- [Configuring uTest](#configuring-utest) has been overhauled.\n\n- Scala `2.12.0-M3` support\n\n- Fix some warnings appearing when the `-Ydead-code` flag is used\n\n- Added [TestPath](#testpath) implicit to make the path to the current test\n  available for usage inside the test body or helpers.\n\n0.3.1\n-----\n\n- Published for Scala.js 0.6.1\n\n0.3.0\n-----\n\n- Published for Scala.js 0.6.0\n- Removed `JsCrossBuild` now that Scala.js supports cross-building via\n  `crossProject`\n- `compileTimeOnly` has been re-introduced, so invalid use of test DSL should\n  fail with nice errors\n- Removed `--throw` flag in favor of \"native\" SBT error reporting\n\n0.2.4\n-----\n\n- Added support for asynchronous tests which return a `Future`.\n\n0.2.3\n-----\n\n- Updated to work against ScalaJS 0.5.4\n\n0.2.2\n-----\n\n- Introduced `CompileError.check(pos: String, msgs: String*)` to simplify the\n  common pattern of checking that the error occurs in the right place and with\n  the message you expect.\n- Changed the file layout expected by `JsCrossBuild`, to expect the shared files\n  to be in `js/shared/` and `jvm/shared/`, rather than in `shared/`. This is\n  typically achieved via symlinks, and should make the cross-build play much\n  more nicely with IDEs.\n\n0.2.1\n-----\n\n- Fix bug in `utestJsSettings` pulling in the wrong version of uTest\n\n0.2.0\n-----\n\n- Introduced the `compileError` macro to allow testing of compilation errors.\n- Stack traces are now only shown for the user code, with the uTest/SBT internal\n  stack trace ignored, making them much less spammy and noisy.\n- Introduced the `*` symbol, which can be used in place of a test name to get\n  sequentially numbered test names.\n\n0.1.9\n-----\n\n\n- ScalaJS version is now built against ScalaJS 0.5.3\n- Fixed linking errors in ScalaJS version, to allow proper operation of the new\n  optimization\n\n0.1.8\n-----\n\n- Fixed bug causing local-defs in assert macro to fail\n\n0.1.7\n-----\n\n- Extracted out `utestJvmSettings` and `utestJsSettings` for use outside the\n  `JsCrossBuild` plugin, for people who don't want to use the plugin.\n\n0.1.6\n-----\n\n- Print paths of failing tests after completion to make C\u0026P-ing re-runs more\n  convenient\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcom-lihaoyi%2Futest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcom-lihaoyi%2Futest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcom-lihaoyi%2Futest/lists"}