Github pages

Author: EtaCassiopeia

README.md

@@ -45,7 +45,7 @@ import zio.schema.{DeriveSchema, Schema}
 // Domain and state
 case class Context(userName: String, greeting: String)
 object Context {
-  implicit val schema: Schema[ScenarioContext] = DeriveSchema.gen[ScenarioContext]
+  implicit val schema: Schema[Context] = DeriveSchema.gen[Context]
 }
 
 // Service

docs/_config.yml

@@ -0,0 +1,4 @@
+theme: just-the-docs
+title: zio-bdd Documentation
+description: Documentation for zio-bdd
+url: "https://EtaCassiopeia.github.io/zio-bdd"

docs/junit-report-formats.md docs/adr/junit-report-formats.mddocs/junit-report-formats.md renamed to docs/adr/junit-report-formats.md

@@ -0,0 +1,141 @@
+
+# Advanced Features in zio-bdd
+
+This page delves into advanced capabilities of `zio-bdd`, including integrating ZIO services, managing complex state, using `ScenarioContext` effectively, and leveraging custom reporters. These features enable you to write sophisticated tests for complex applications.
+
+## Integrating ZIO Services
+
+`zio-bdd` seamlessly integrates with ZIO's dependency injection system via `ZLayer`. This allows you to provide services to your step definitions, making your tests modular and easy to manage.
+
+### Providing Services
+
+In your `ZIOSteps` subclass, override the `environment` method to provide the required services:
+
+```scala
+override def environment: ZLayer[Any, Any, Env] =
+  ZLayer.make[Env](
+    Service1.live,
+    Service2.live
+  )
+```
+
+- **Env**: The type of the environment required by your steps (e.g., `Service1 with Service2`).
+
+### Using Services in Steps
+
+Access services in your step definitions using `ZIO.service`:
+
+```scala
+When("some action is performed") {
+  for {
+    service <- ZIO.service[Service1]
+    result  <- service.doSomething()
+    // ...
+  } yield ()
+}
+```
+
+This approach keeps your tests clean and decoupled from service implementations.
+
+## Managing Complex State
+
+For tests requiring intricate state management, `ScenarioContext` can hold complex data structures. Define a case class to represent your state and provide an implicit `Schema` for serialization.
+
+### Example
+
+```scala
+case class ComplexState(users: Map[String, User], currentUser: Option[String])
+implicit val schema: Schema[ComplexState] = DeriveSchema.gen[ComplexState]
+
+Given("a user named " / string) { (name: String) =>
+  for {
+    state <- ScenarioContext.get
+    updatedUsers = state.users + (name -> User(name))
+    _ <- ScenarioContext.update(_.copy(users = updatedUsers))
+  } yield ()
+}
+```
+
+- Use `ScenarioContext.update` to modify the state immutably.
+
+## Custom Reporters
+
+While `zio-bdd` provides built-in reporters, you can create custom reporters for specialized output formats.
+
+### Implementing a Custom Reporter
+
+Extend the `Reporter` trait:
+
+```scala
+class CustomReporter extends Reporter {
+  override def report(results: List[FeatureResult]): ZIO[Any, Nothing, Unit] = {
+    // Custom reporting logic
+    ZIO.succeed(())
+  }
+}
+```
+
+- Register your reporter in the `@Suite` annotation:
+
+```scala
+@Suite(reporters = Array("custom"))
+object MySpec extends ZIOSteps[Env, State] {
+  // ...
+}
+```
+
+- You'll need to map `"custom"` to your `CustomReporter` instance in the test framework configuration.
+
+## Scenario Outlines and Examples
+
+`zio-bdd` fully supports Gherkin’s `Scenario Outline` and `Examples` for data-driven testing.
+
+### Defining Steps for Outlines
+
+Write step definitions as usual, using extractors for placeholders:
+
+```scala
+Given("a user named " / string) { (name: String) =>
+  // ...
+}
+```
+
+- `zio-bdd` automatically handles the expansion of outlines into multiple scenarios.
+
+## Background Steps
+
+Gherkin’s `Background` section runs before each scenario in a feature. Define steps for background as you would for any other step.
+
+### Example
+
+In your feature file:
+
+```gherkin
+Feature: User Management
+  Background:
+    Given a system is running
+  Scenario: Create user
+    When a user is created
+    Then the user exists
+```
+
+Define the background step:
+
+```scala
+Given("a system is running") {
+  // Setup system
+}
+```
+
+- Background steps are executed before each scenario, ensuring a consistent starting state.
+
+## Best Practices
+
+- **Service Mocking**: Use test doubles or mocks for services to isolate tests.
+- **State Reset**: Ensure each scenario starts with a clean state, especially when using shared resources.
+- **Custom Extractors**: For complex parameter types, define custom extractors extending `TypedExtractor`.
+
+## Next Steps
+
+- Explore practical applications in [Examples](examples.md).
+- Contribute to `zio-bdd` by checking the [Contribution Guide](contributing.md).

docs/advanced-features.md

@@ -0,0 +1,80 @@
+
+# Contributing to zio-bdd
+
+We welcome contributions to `zio-bdd`! This guide outlines how to get involved, from reporting issues to submitting pull requests. Your contributions help make `zio-bdd` better for the entire community.
+
+## Getting Started
+
+### Reporting Issues
+
+If you encounter bugs, have feature requests, or need clarification, please open an issue on the [GitHub repository](https://github.com/EtaCassiopeia/zio-bdd). When reporting issues:
+
+- **Search First**: Check if the issue already exists.
+- **Be Detailed**: Provide steps to reproduce, expected behavior, and actual behavior.
+- **Include Versions**: Mention your Scala, ZIO, and `zio-bdd` versions.
+
+### Suggesting Features
+
+Feature suggestions are welcome! When proposing a new feature:
+
+- **Explain the Use Case**: Describe the problem it solves.
+- **Consider Alternatives**: Mention any workarounds or existing solutions.
+- **Be Open to Discussion**: Engage with the community to refine the idea.
+
+## Development Workflow
+
+### Setting Up the Environment
+
+1. **Fork the Repository**: Create your own fork on GitHub.
+2. **Clone Your Fork**:
+   ```bash
+   git clone https://github.com/your-username/zio-bdd.git
+   ```
+3. **Install Dependencies**: Ensure you have Scala 3 and SBT installed.
+4. **Build the Project**:
+   ```bash
+   sbt compile
+   ```
+
+### Making Changes
+
+1. **Create a Branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+2. **Write Code**: Follow the coding standards and add tests for new features.
+3. **Run Tests**:
+   ```bash
+   sbt test
+   ```
+4. **Commit Changes**: Use clear, descriptive commit messages.
+5. **Push to Your Fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+### Submitting a Pull Request
+
+1. **Open a Pull Request**: From your fork to the main repository.
+2. **Describe Your Changes**: Explain what you did and why.
+3. **Link to Issues**: If applicable, reference related issues.
+4. **Wait for Review**: Be responsive to feedback and make necessary adjustments.
+
+## Coding Standards
+
+- **Follow Scala Style**: Adhere to the [Scala Style Guide](https://docs.scala-lang.org/style/).
+- **Use ZIO Best Practices**: Write idiomatic ZIO code.
+- **Document Code**: Add Scaladoc comments for public APIs.
+- **Test Thoroughly**: Ensure new features are covered by tests.
+
+## Community Guidelines
+
+- **Be Respectful**: Treat all contributors with kindness and respect.
+- **Stay Constructive**: Provide feedback that helps improve the project.
+- **Collaborate**: Work together to solve problems and implement features.
+
+## License
+
+By contributing to `zio-bdd`, you agree that your contributions will be licensed under the Apache License 2.0.
+
+Thank you for contributing to `zio-bdd`! Your efforts help advance BDD testing in the Scala and ZIO ecosystems.