airspec

Instruction file imported from wvlet/wvlet (.github/instructions/airspec.instructions.md). Copyright stays with the author.

Generate test cases in Scala 3 syntaxes using the AirSpec testing framework (wvlet.airspec.AirSpec).

AirSpec Basic Syntax Explanation:

• AirSpec tests are typically defined within a Scala object or class that extends wvlet.airspec.AirSpec.
• AirSpec uses test("...") { ... } syntax for writing test cases.

AirSpec provides a rich set of assertion syntaxes for verifying test expectations. Here are some common ones:

Assertion Syntax Table:

Assertion Example:

import wvlet.airspec.AirSpec

class MyTest extends AirSpec:
  test("assertion examples") {
    // checking the value equality with shouldBe, shouldNotBe:
    1 shouldBe 1
    1 shouldNotBe 2
    List().isEmpty shouldBe true

    // For optional values, shouldBe defined (or empty) can be used:
    Option("hello") shouldBe defined
    Option(null) shouldBe empty
    None shouldNotBe defined

    // null check
    val s:String = null
    s shouldBe null
    "s" shouldNotBe null

    // For Arrays, shouldBe checks the equality with deep equals
    Array(1, 2) shouldBe Array(1, 2)

    // Collection checker
    Seq(1) shouldBe defined
    Seq(1) shouldNotBe empty
    Seq(1, 2) shouldBe Seq(1, 2)
    (1, 'a') shouldBe (1, 'a')

    // Object equality checker
    val a = List(1, 2)
    val a1 = a
    val b = List(1, 2)
    a shouldBe a1
    a shouldBeTheSameInstanceAs a1
    a shouldBe b
    a shouldNotBeTheSameInstanceAs b

    // Pattern matcher
    Seq(1, 2) shouldMatch {
      case Seq(1, _) => // ok
    }

    // Containment check
    "hello world" shouldContain "world"
    Seq(1, 2, 3) shouldContain 1

    "hello world" shouldNotContain "!!"
    Seq(1, 2, 3) shouldNotContain 4
  }

  // You can nest test cases
  test("nested test examples") {
    test("nested test") {
      1 shouldBe 1
    }

    test("nested test with pending") {
      pending("this test is pending")
    }
  }

Logging

To add debug messages, use debug and trace methods.

test("my test") {
  debug("debug message")
  trace("trace message")
}

Debug logging can be enabled by setting the log level in testOnly command in sbt with -l debug or -l trace:

> testOnly * -- -l debug

DI Example

To set up commonly used resources, use Airframe DI to bind instances. Test methods accept the bound instances as parameters:

import wvlet.airspec.AirSpec

case class ServiceConfig(port:Int)
class Service(val config:ServiceConfig)

class ServiceSpec extends AirSpec:
  initDesign { design =>
    design
      .bindInstance[ServiceConfig](ServiceConfig(port=8080))
      .bindSingleton[Service]
      .onStart{x => info(s"Starting a server at ${x.config.port}")}
      .onShutdown{x => info(s"Stopping the server at ${x.config.port}")}
  }

  test("test1") { (service:Service) =>
     info(s"server id: ${service.hashCode}")
  }

  test("test2") { (service:Service) =>
     info(s"server id: ${service.hashCode}")
  }