<img src="https://yellow-cdn.veclightyear.com/835a84d5/b45217ae-2168-43b0-8828-020026143ba4.png" width="200px" height="231px" align="right">

请阅读以下内容：

Weaver 的管理权正在转移到 Typelevel。本仓库将不再进行任何开发，并将在 Typelevel 版本首次发布后归档。你可以在这里关注进展：https://github.com/typelevel/weaver-test/issues/1

Weaver-test

一个基于 cats-effect 和 fs2 构建的测试框架

安装

Weaver-test 目前发布用于 Scala 2.12、2.13 和 3.0

SBT

请参考 releases 页面了解最新发布的版本，并在你的 build.sbt 文件中添加以下内容（或等效的范围设置）。

libraryDependencies += "com.disneystreaming" %% "weaver-cats" % "x.y.z" % Test
testFrameworks += new TestFramework("weaver.framework.CatsEffect")

// 可选（用于 Scalacheck）
libraryDependencies +=  "com.disneystreaming" %% "weaver-scalacheck" % "x.y.z" % Test

动机

Weaver 旨在提供编写和运行测试时的良好体验：

• 套件内的测试默认并行运行，以获得尽可能快的结果
• 期望（即断言）是可组合的值。这迫使开发人员将测试场景与他们执行的检查分开，通常可以保持测试更清晰/更简洁。
• 失败会被聚合并在运行结束时报告。这避免了开发人员在试图理解失败原因时需要"向上滚动"很长时间。
• 每个测试都提供了一个惰性日志记录器，只有在测试失败时才显示日志语句。这让开发人员可以用线索丰富他们的测试，并且可以很好地适用于并行运行。

API

示例套件（cats-effect）

SimpleIOSuite

对开发人员最熟悉的套件：

import weaver.SimpleIOSuite
import cats.effect._

// 套件必须是"对象"，以便框架能够选择它们
object MySuite extends SimpleIOSuite {

  pureTest("非副作用（纯）测试"){
    expect("hello".size == 6)
  }

  private val random = IO(java.util.UUID.randomUUID())

  test("带副作用的测试") {
    for {
      x <- random
      y <- random
    } yield expect(x != y)
  }

  loggedTest("带副作用和日志记录器的测试"){ log =>
    for {
      x <- random
      _ <- log.info(s"x : $x")
      y <- random
      _ <- log.info(s"y : $y")
    } yield expect(x != y)
  }
}

IOSuite

IOSuite 为套件中的所有测试构建一次给定的资源。

import weaver.IOSuite
import cats.effect._

object MySuite extends IOSuite {

  type Res = Int

  def sharedResource : Resource[IO, Int] = Resource
    .make(
      IO(println("创建资源"))
        .as(123)
    )(n => IO(println(s"关闭资源 $n")))

  test("测试，但资源不可见"){
    IO(expect(123 == 123))
  }

  test("带资源的测试"){ n =>
    IO(expect(n == 123))
  }

  test("带资源和日志记录器的测试"){ (n, log) =>
    log.info("日志可用") *>
    IO(expect(n == 123))
  }
}

其他套件

Weaver 还包括对以下内容的支持

别名	套件名称	提供者	用例
SimpleIOSuite	SimpleMutableIOSuite	weaver-cats	每个测试都是独立的IO操作
IOSuite	MutableIOSuite	weaver-cats	每个测试需要访问共享的Resource

期望（断言）

构建期望

各种test函数的共同点是它们期望开发者返回一个Expectations类型的值，这只是一个包装了cats.data.Validated值的基本case类。

构建Expectations最方便的方式是使用expect函数。基于Eugene Yokota优秀的expecty，它在编译时捕获布尔表达式，并在出错时提供有用的反馈：

用户可以自由构建自己的期望函数，以符合他们习惯的方式。

组合期望

值得注意的是，期望不会抛出异常，如果用户想在同一测试中执行多个检查，他需要通过期望携带的and或or方法来组合期望。

过滤测试

使用IOSuite变体时，用户可以这样调用sbt的test命令：

> testOnly -- -o *foo*

这个过滤器将阻止执行任何在限定名称中不包含"foo"字符串的测试。对于在"fooPackage"包中的"FooSuite"对象里标记为"foo"的测试，其限定名称是：

fooPackage.FooSuite.foo

独立运行套件

可以通过常规的main函数在构建工具之外运行套件。为此，你可以实例化weaver.Runner，创建一个包含你想运行的套件的fs2.Stream，并调用runner.run(stream)。

当你将测试（通常是端到端测试）视为独立程序，并希望避免每次运行时都付出编译成本时，这种方法很有用。

Scalacheck（基于属性的测试）

Weaver提供了基本的scalacheck集成。

import weaver._
import weaver.scalacheck._
import org.scalacheck.Gen

// 注意Checkers混入
object ForallExamples extends SimpleIOSuite with Checkers {

  // CheckConfig可以在测试套件级别被重写
  override def checkConfig: CheckConfig =
    super.checkConfig.copy(perPropertyParallelism = 100)

  test("Gen形式") {
    // 接受一个显式的"Gen"实例。这个重载只有一个版本。
    // 如果你想一次传递多个Gen实例，只需以单子方式组合它们。
    forall(Gen.posNum[Int]) { a =>
      expect(a > 0)
    }
  }

  test("Arbitrary形式") {
    // 接受多个隐式的"Arbitrary"实例。有6个重载可以传递1到6个参数。
    forall { (a1: Int, a2: Int, a3: Int) =>
      expect(a1 * a2 * a3 == a3 * a2 * a1)
    }
  }

  test("foobar") {
    // CheckConfig可以在本地被重写
    forall.withConfig(super.checkConfig.copy(perPropertyParallelism = 1,
                                             initialSeed = Some(7L))) {
      (x: Int) =>
        expect(x > 0)
    }
  }

}

贡献

非常欢迎贡献！

开发要求

:警告: 本仓库使用Git LFS。需要安装它才能正常使用git checkout。

使用brew在Mac上安装：

brew install git-lfs
git lfs install

如果你想构建和运行网站，则需要安装yarn：

brew install yarn

构建网站

如果你正在修改文档，以下是如何在本地检查你的更改：

sbt docs/docusaurusCreateSite
cd website
yarn start

如果你只修改.md文件，可以运行sbt '~docs/mdoc'。

注意，网站看起来会有一点不同，因为为了构建版本化网站，我们在CI上运行的脚本中有一些机制 - 但你不必担心这一点。

IntelliJ插件

IntelliJ插件的代码位于这里

PR指南

请：

• 签署CLA
• 编写正面和负面测试
• 包含文档

灵感来源

非常感谢Alexandru Nedelcu，Monix的作者和cats-effect的贡献者，他编写了minitest框架，这是本框架的起点。