# serenity-bdd/serenity-rest-starter architecture

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

- Interactive diagram: https://gitdiagram.com/serenity-bdd/serenity-rest-starter
- Repository: https://github.com/serenity-bdd/serenity-rest-starter

## Overview

##### Main Components
- Maven Build System: Represented by the pom.xml, which handles project dependencies and build orchestration.
- Serenity BDD Configuration: This includes serenity.properties and serenity.conf files that configure and control the Serenity framework.
- Test Runner/Execution: Mark the central test suite file (CucumberTestSuite.java) that orchestrates the test execution.
- Step Definitions: Include the step definitions package (e.g., starter/postcodes/PostCodeStepDefinitions.java) which links Gherkin steps to Java method implementations.
- Feature Files: Represent the Gherkin feature files (located in src/test/resources/features/postcodes/looking_up_post_codes.feature) that describe test scenarios in a human-readable format.
- REST API Client Components: Illustrate the API client classes (for example, PostCodeAPI.java and LocationResponse.java) that encapsulate API calls and response handling.
- Additional Libraries/Frameworks: Call out the use of Cucumber 6 for BDD, Serenity for reporting and test management, and RestAssured for forming REST calls.

##### Out the Relationships and Interactions
- The Cucumber feature files are consumed by the Cucumber test runner (invoked via CucumberTestSuite.java).
- Step definitions, in turn, interact with the REST API client classes to issue HTTP requests using RestAssured.
- The responses and test results are handled and reported using Serenity BDD, with configuration details drawn from the serenity.properties and serenity.conf files.
- Logging is configured via logback-test.xml to capture runtime details.

##### Architectural Patterns and Principles
- Separation of Concerns: Each component has a clear responsibility (test definitions, API interactions, configuration, build management).
- Layered Approach: The tests are structured in a layer where the feature files describe scenarios, step definitions handle test logic, and API client classes manage external interactions.

##### Relevant Technologies and Frameworks
- Maven (pom.xml) – project build and dependency management.
- Serenity BDD – for test execution reporting and advanced BDD practices.
- Cucumber 6 – for writing feature files and orchestrating BDD test scenarios.
- RestAssured – for sending HTTP REST requests and verifying responses.
- Logback (logback-test.xml) – for logging purposes.

- From here, show the branching into two main paths: one side for “Test Scenario Definition” (feature files) and the other side for “Test Implementation” (step definitions and API client calls).
- Reporting/feedback loop from Serenity at the end of the flow to indicate how test outcomes are captured and reported.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Maven Build System (pom.xml)"]:::maven
    subgraph "Serenity BDD Configuration"
        conf1["serenity.properties"]:::config
        conf2["serenity.conf"]:::config
        conf3["logback-test.xml"]:::config
    end
    B["Test Runner (CucumberTestSuite.java)"]:::runner
    C["Feature Files (looking_up_post_codes.feature)"]:::feature
    D["Step Definitions (PostCodeStepDefinitions.java)"]:::step
    subgraph "REST API Client Components"
        E["API Request (PostCodeAPI.java)"]:::rest
        F["Response Handler (LocationResponse.java)"]:::rest
    end
    G["Serenity Reporting"]:::reporting

    %% Connections
    A -->|"triggers"| B
    C -->|"feeds"| B
    conf1 -.-> B
    conf2 -.-> B
    conf3 -.-> B
    B -->|"executes"| D
    D -->|"calls"| E
    E -->|"processes"| F
    F -->|"reports"| G

    %% Styles
    classDef maven fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef config fill:#dcedc8,stroke:#558b2f,stroke-width:2px;
    classDef runner fill:#b3e5fc,stroke:#0288d1,stroke-width:2px;
    classDef feature fill:#ffccbc,stroke:#d84315,stroke-width:2px;
    classDef step fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef rest fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef reporting fill:#d1c4e9,stroke:#512da8,stroke-width:2px;

    %% Click Events
    click A "https://github.com/serenity-bdd/serenity-rest-starter/blob/master/pom.xml"
    click conf1 "https://github.com/serenity-bdd/serenity-rest-starter/blob/master/serenity.properties"
    click conf2 "https://github.com/serenity-bdd/serenity-rest-starter/blob/master/src/test/resources/serenity.conf"
    click conf3 "https://github.com/serenity-bdd/serenity-rest-starter/blob/master/src/test/resources/logback-test.xml"
    click B "https://github.com/serenity-bdd/serenity-rest-starter/blob/master/src/test/java/starter/CucumberTestSuite.java"
    click C "https://github.com/serenity-bdd/serenity-rest-starter/blob/master/src/test/resources/features/postcodes/looking_up_post_codes.feature"
    click D "https://github.com/serenity-bdd/serenity-rest-starter/blob/master/src/test/java/starter/postcodes/PostCodeStepDefinitions.java"
    click E "https://github.com/serenity-bdd/serenity-rest-starter/blob/master/src/test/java/starter/postcodes/PostCodeAPI.java"
    click F "https://github.com/serenity-bdd/serenity-rest-starter/blob/master/src/test/java/starter/postcodes/LocationResponse.java"
```
