# smartbear/testserver-cucumber architecture

> Architecture diagram of the GitHub repository smartbear/testserver-cucumber, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smartbear/testserver-cucumber
- Repository: https://github.com/smartbear/testserver-cucumber

## Overview

##### Main Components
- Code Generation Module ("modules/codegen"): This module holds the logic for generating Cucumber features and possibly producing or customizing test recipes (note the presence of Mustache templates and Docker resources). It also includes a separate README indicating its self-contained functionality.
- Core Module ("modules/core"): This module contains the heart of the test recipe builder and executor. Key classes here include components that build the Cucumber test recipes and interact with the Ready! API TestServer through the Java client.
- Runner Module ("modules/runner"): This module is designed to create a standalone executable (a runnable jar and also Docker integration) to run the tests based on the Cucumber features. It includes its own Docker configuration.
- Step Definitions Module ("modules/stepdefs"): This module provides the glue-code for mapping the Gherkin steps to actions (including REST calls, parameter handling, Swagger schema integration).
- Samples Module ("modules/samples"): Although not part of the core framework, this module contains example projects (feature files and sample test classes) that demonstrate how to use the vocabulary.
- External Systems:
- Ready! API TestServer: The target system where the generated test recipes are sent.
- Swagger Definitions: External documentation for REST APIs, used to deduce parameter types and endpoints.
- Maven Build Environment/Docker: These act as infrastructure elements for building and executing the system.

##### Lay Out the Relationships and Data Flow
- The Runner module (with its Docker image support) is responsible for executing the tests. It calls the Step Definitions (from the stepdefs module) that map the plain-English steps to underlying method calls.
- The step definitions make use of the Core module’s CucumberRecipeBuilder and CucumberRecipeExecutor. These classes construct the test “recipes” (which define the API testing steps) and then send these recipes to the Ready! API TestServer.
- The Codegen module might be used upstream to automatically generate some of the Cucumber test artifacts or boilerplate code using Mustache templates.
- Samples module provides example integrations which show how a user might set everything up when running tests.
- External interactions: When a CLI or Docker command starts the Runner, it uses the included TestServer Java client (from the core) to post test recipes to the Ready! API TestServer endpoint.

##### Architectural Patterns & Design Principles
- Modularization: The project is split into several Maven modules (Codegen, Core, Runner, StepDefs, and Samples), each with a clearly defined responsibility supporting separation of concerns.
- Integration of DSL (Domain-Specific Language): The project encapsulates a custom vocabulary in Gherkin that abstracts away technical details (like Swagger parsing) and provides a simple BDD interface.
- Containerization: Docker support is provided in both codegen and runner modules to allow easy distribution and execution.
- Dependency Injection/Loose Coupling: The sample extension of custom step definitions demonstrates the usage of dependency injection (notably using Guice with @ScenarioScoped) for better extensibility.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Input
    F["Feature Files (Gherkin)"]:::userInput

    %% Modules
    subgraph "Modules"
        Codegen["Code Generation Module"]:::module
        CoreMod["Core Module (CucumberRecipeBuilder & Executor)"]:::module
        RunnerMod["Runner Module (CLI & Docker Integration)"]:::module
        StepDefsMod["Step Definitions Module (Gherkin to Test Logic)"]:::module
        SamplesMod["Samples Module (Example Projects)"]:::module
    end

    %% External Systems
    subgraph "External Systems"
        TestServer["Ready! API TestServer"]:::external
        SwaggerDef["Swagger Definitions"]:::external
        DockerEnv["Docker Environment"]:::external
        MavenBuild["Maven Build Environment"]:::external
    end

    %% Data Flow and Interactions
    F -->|"triggers"| RunnerMod
    SamplesMod -->|"offers sample input"| F
    RunnerMod -->|"invokes"| StepDefsMod
    StepDefsMod -->|"utilizes"| CoreMod
    CoreMod -->|"dispatches recipe"| TestServer
    Codegen -->|"generates artifacts"| StepDefsMod
    RunnerMod -->|"operates in"| DockerEnv
    RunnerMod -->|"built via"| MavenBuild
    SwaggerDef -->|"supports"| StepDefsMod
    SwaggerDef -->|"informs"| CoreMod

    %% Click Events for Component Mapping
    click Codegen "https://github.com/smartbear/testserver-cucumber/tree/master/modules/codegen"
    click CoreMod "https://github.com/smartbear/testserver-cucumber/tree/master/modules/core"
    click RunnerMod "https://github.com/smartbear/testserver-cucumber/tree/master/modules/runner"
    click StepDefsMod "https://github.com/smartbear/testserver-cucumber/tree/master/modules/stepdefs"
    click SamplesMod "https://github.com/smartbear/testserver-cucumber/tree/master/modules/samples"

    %% Styles
    classDef module fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef external fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef userInput fill:#FFECB3,stroke:#FF6F00,stroke-width:2px;
```
