zio-bdd

zio-bdd is an innovative Behavior-Driven Development (BDD) testing framework designed specifically for Scala 3 applications built on ZIO. By seamlessly integrating Gherkin-style feature files with ZIO’s effect system, this framework provides developers with enhanced compile-time safety, fiber-based concurrency, and type-safe dependency injection through ZLayer. This empowers teams to create clear, business-oriented tests that deliver robust error handling and modular service integration.

Key Features

• Type-Safe Step Definitions: Ensure compile-time safety with typed parameters, which help minimize runtime errors.
• Typed Parameter Extraction: Utilize extractors (e.g., string, int, double, table[T]) for safe and easy parameter parsing, enhanced by ZIO Schema for complex data types.
• State Management: Employ ScenarioContext for efficient test state management across multiple steps, facilitating seamless data sharing during tests.
• Fiber-Based Concurrency: Optimize test performance by executing scenarios concurrently with ZIO fibers.
• ZIO Service Integration: Leverage ZLayer to enable modular and type-safe dependency injection, streamlining the setup of test environments.
• Dynamic Feature Loading: Automatically discover .feature files from a designated directory, with support for tag-based filtering to simplify test runs.
• Flexible Reporting: Includes a PrettyReporter for console output and JUnit XML reporting, while allowing extensibility for custom output formats.
• Rich Gherkin Support: Effectively handles Gherkin constructs such as Background, Scenario Outline, data tables, and tags (e.g., @ignore, @positive).

Usage Example

A sample implementation for testing a greeting service illustrates how to define steps, manage state with ScenarioContext, and integrate ZIO services through a Gherkin feature file.

Step 1: Define Domain and Steps

In example/src/test/scala/zio/bdd/example/GreetingSpec.scala, the domain model and service implementation are structured clearly:

// Domain and state
case class Context(userName: String, greeting: String)
object Context { implicit val schema: Schema[Context] = DeriveSchema.gen[Context] }

// Service
trait GreetingService { def greet(name: String): ZIO[Any, Nothing, String] }
case class GreetingServiceImpl(prefix: String) extends GreetingService {
  def greet(name: String): ZIO[Any, Nothing, String] = ZIO.succeed(s"$prefix, $name!")
}
object GreetingService {
  val live: ZLayer[String, Nothing, GreetingService] = ZLayer.fromFunction(GreetingServiceImpl(_))
}

Step 2: Create a Feature File

The behaviors of the greetings are defined in a Gherkin feature file found at example/src/test/resources/features/greeting.feature:

@core @greeting
Feature: User Greeting
  Scenario: Greet a positive user
    Given a user named "Alice"
    When the user is greeted
    Then the greeting should be "Hello, Alice!"

  @positive
  Scenario: Greet another positive user
    Given a user named "Bob"
    When the user is greeted
    Then the greeting should be "Hello, Bob!"

Step 3: Run Tests

To ensure comprehensive testing:

• Execute all scenarios using:

sbt "example/test"

• Filter tests by tags with:

sbt "testOnly zio.bdd.example.GreetingSpec -- --include-tags positive"

• Run specific features directly by specifying the feature file:

sbt "testOnly zio.bdd.example.GreetingSpec -- --feature-file example/src/test/resources/features/greeting.feature"

• Utilize debug mode for detailed step execution logs:

sbt "example/testOnly zio.bdd.example.GreetingSpec -- -DlogLevel=debug"

Contributions: This open-source project welcomes contributions aimed at enhancing Gherkin support, reporting capabilities, or overall performance. Community involvement is encouraged through issues or pull requests on GitHub.