# serenity-bdd/serenity-cucumber-starter architecture

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

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

## Overview

##### Main Components
- Test Runner & Framework Integration: Represent the CucumberTestSuite (the JUnit test runner in src/test/java/starter) which ties Serenity’s reporting and lifecycle hooks to the tests. Also note that both Maven (pom.xml) and Gradle (build.gradle, gradlew, etc.) build scripts are present.
- Feature Files & Gherkin Scenarios: Show the Cucumber feature files (located in src/test/resources/features) which define the test scenarios in Gherkin.
- Step Definitions & Glue Code: Highlight the step definition classes (e.g., SearchStepDefinitions and ParameterDefinitions) which map Gherkin steps to Java methods.
- Serenity Infrastructure: Indicate the Serenity configuration files (serenity.properties, serenity.conf) that manage WebDriver setup, environment-specific URLs, and other testing options. Also note that Serenity integrates WebDriverManager to handle browser drivers.
- Reporting & CI/CD: Show the CI workflows from the .github/workflows folder (gradle.yml, maven.yml, living-documentation.yml) and the reporting components. This explains how test results are aggregated into Serenity reports (target/site/serenity).

##### Relationships and Interactions
- Then, branch out from the Step Definitions into two potential implementation paths:
- For Screenplay Pattern: Show actors (like “Sergey”) that perform Tasks. Link these tasks to classes such as NavigateTo and LookForInformation, and then to Page Objects (e.g., WikipediaHomePage, SearchForm).
- For Action Classes: Show the direct call chain from step definitions to methods on step classes (annotated with @Steps), like NavigateTo, SearchFor, and SearchResult, again linking to Page Objects.
- That both approaches interact with the WebDriver and Selenium APIs (possibly labeled “Serenity WebDriver API”) to locate and manipulate UI elements.
- Lastly, show a connection from the test execution flow to the reporting engine (serenity-maven-plugin or reporting mechanism integrated in Gradle) that generates living documentation and test reports.

##### Architectural Patterns & Design Principles
- Mention the use of the Single Responsibility Principle, which is emphasized by having multiple small classes (each with a clear role, whether a step definition, task, or page object).
- Separation between the test runner, the glue code (step definitions), and the helper libraries (tasks and page objects).
- If appropriate, mark the two parallel design implementations (Screenplay versus Action Classes) so a reader can quickly understand the architectural alternatives provided in the project.

##### Relevant Technologies and Frameworks
- Serenity BDD
- Cucumber (for Gherkin support)
- Selenium WebDriver (via Serenity’s wrapper)
- WebDriverManager (for binary management)
- Build tools: Maven and Gradle
- CI/CD configuration via GitHub Actions (workflow files)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Test Runner & Build Tools
    subgraph "Test Runner & Build Tools"
        CTR("Cucumber Test Suite"):::test_code
        BS1("pom.xml"):::ci_cd
        BS2("build.gradle"):::ci_cd
        BS3("gradlew"):::ci_cd
        BS4("gradlew.bat"):::ci_cd
        CTR -->|"triggers"| BS1
        CTR -->|"triggers"| BS2
        CTR -->|"triggers"| BS3
        CTR -->|"triggers"| BS4
    end

    %% Features and Glue Code
    subgraph "Features & Glue"
        FF("Feature Files"):::test_code
        FS("search_by_keyword.feature"):::test_code
        SD("Step Definitions"):::test_code
        SD1("SearchStepDefinitions.java"):::test_code
        SD2("ParameterDefinitions.java"):::test_code
        FF -->|"contains"| FS
        FF -->|"feeds"| SD
        SD -->|"includes"| SD1
        SD -->|"includes"| SD2
    end

    %% Implementation Patterns
    subgraph "Implementation Patterns"
        %% Screenplay Pattern Branch
        subgraph "Screenplay Pattern"
            A("Actor: Sergey"):::serenity
            T1("Task: NavigateTo"):::serenity
            T2("Task: LookForInformation"):::serenity
            PO1("Page Object: DuckDuckGoHomePage"):::serenity
            PO2("Page Object: SearchForm"):::serenity
            A -->|"initiates"| T1
            A -->|"initiates"| T2
            T1 -->|"uses"| PO1
            T2 -->|"uses"| PO2
        end
        %% Action Classes Branch
        subgraph "Action Classes"
            AC("Action: SearchArticle"):::serenity
        end
        SD -->|"calls"| A
        SD -->|"calls"| AC
    end

    %% Serenity Infrastructure
    subgraph "Serenity Infrastructure"
        SP("serenity.properties"):::infrastructure
        SC("serenity.conf"):::infrastructure
    end

    %% External Dependencies
    subgraph "External Dependencies"
        API("Serenity WebDriver API"):::infrastructure
        WDM("WebDriverManager"):::infrastructure
        API -->|"manages"| WDM
        T1 -->|"leverages"| API
        T2 -->|"leverages"| API
        AC -->|"leverages"| API
        PO1 -->|"leverages"| API
        PO2 -->|"leverages"| API
    end

    %% CI/CD & Reporting
    subgraph "CI/CD & Reporting"
        CI("CI/CD Workflows"):::ci_cd
        SR("Serenity Reporting"):::ci_cd
        CI -->|"generates"| SR
        BS1 -->|"integrated with"| CI
        BS2 -->|"integrated with"| CI
    end

    %% Infrastructure Integration
    SP -->|"configures"| CTR
    SC -->|"configures"| CTR
    SD -->|"initiates WebDriver"| API

    %% Click Events
    click CTR "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/src/test/java/starter/CucumberTestSuite.java"
    click BS1 "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/pom.xml"
    click BS2 "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/build.gradle"
    click BS3 "https://github.com/serenity-bdd/serenity-cucumber-starter/tree/master/gradlew"
    click BS4 "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/gradlew.bat"
    click FF "https://github.com/serenity-bdd/serenity-cucumber-starter/tree/master/src/test/resources/features"
    click FS "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/src/test/resources/features/search/search_by_keyword.feature"
    click SD "https://github.com/serenity-bdd/serenity-cucumber-starter/tree/master/src/test/java/starter/stepdefinitions"
    click SD1 "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/src/test/java/starter/stepdefinitions/SearchStepDefinitions.java"
    click SD2 "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/src/test/java/starter/stepdefinitions/ParameterDefinitions.java"
    click T1 "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/src/test/java/starter/navigation/NavigateTo.java"
    click T2 "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/src/test/java/starter/search/LookForInformation.java"
    click AC "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/src/test/java/starter/search/SearchArticle.java"
    click PO1 "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/src/test/java/starter/navigation/DuckDuckGoHomePage.java"
    click PO2 "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/src/test/java/starter/search/SearchForm.java"
    click SP "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/serenity.properties"
    click SC "https://github.com/serenity-bdd/serenity-cucumber-starter/blob/master/src/test/resources/serenity.conf"
    click CI "https://github.com/serenity-bdd/serenity-cucumber-starter/tree/master/.github/workflows"

    %% Class Definitions
    classDef test_code fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef serenity fill:#FAD7A0,stroke:#D68910,stroke-width:2px;
    classDef ci_cd fill:#A9DFBF,stroke:#229954,stroke-width:2px;
    classDef infrastructure fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
```
