# vitalets/playwright-bdd architecture

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

- Interactive diagram: https://gitdiagram.com/vitalets/playwright-bdd
- Repository: https://github.com/vitalets/playwright-bdd

## Overview

##### Main Components
- CLI & Configuration:
– Located in the src/cli and src/config directories, this component processes command line arguments, loads configuration defaults, and acts as the entry point to the system.
- Feature Parsing & Gherkin Processing:
– The src/gherkin folder contains the logic to load and parse feature files, extract scenarios, and handle Gherkin syntax.
– The src/cucumber directory further processes these parsed definitions to support Cucumber-style step definitions and formats.
- Test Generation:
– Under src/generate, the system transforms BDD feature files into executable test files tailored for Playwright.
– This module leverages additional helper scripts (such as in src/generate/test) to map features to corresponding test code.
- Step Definitions & BDD Runtime:
– The src/steps and src/runtime modules manage step definitions, fixture associations, context creation, and the invocation of BDD test steps during runtime.
- Playwright Integration:
– The src/playwright directory contains integration logic to load configuration, support dynamic imports (ESM or CJS), execute tests, and handle error reporting via Playwright’s built-in mechanisms.
- Reporting & Output:
– The src/reporter folder is dedicated to formatting test results and attaching additional metadata (including HTML, JSON, JUnit, and even external attachments) for comprehensive reporting.
- AI and Advanced Extensions:
– The src/ai module integrates AI-based features (such as prompt building and generating attachments) that enhance or automate features of the BDD process.
- Utility & Helper Modules:
– The src/utils directory includes general purpose helpers (logging, file paths, string manipulations) that are shared by several of the above components.

##### Detail the Relationships and Data Flow
- The user interacts with the system via the CLI. Commands (like “test”, “env”, or “export”) are parsed in src/cli and then passed along with configuration details from src/config.
- The CLI then calls the Feature Parsing module (src/gherkin) to read and extract scenarios from Gherkin feature files.
- Parsed data is forwarded to the Test Generation component (src/generate) where it is transformed into runnable test code that adheres to Playwright’s runner format.
- At runtime, the Playwright integration (src/playwright) initializes the browser sessions, runs the generated tests, and manages test fixtures via the runtime modules.
- Step definitions (stored in or referenced by src/steps and supported by src/runtime) are matched to function implementations that perform the test actions.
- Reporting modules (in src/reporter) collect execution results, convert them into multiple formats (JUnit, JSON, HTML) and attach any additional data such as screenshots or videos.
- Optionally, AI components in src/ai can generate or enhance feature files and test steps. They interact with both the generation and reporting layers.
- Utility modules (src/utils) support cross-cutting concerns such as logging, error handling, and path management across all areas.

##### Architectural Patterns and Design Principles
- Modularity: The design cleanly separates concerns – CLI handling, parsing/generation, runtime execution, and reporting are each encapsulated in their own modules.
- Layered Architecture: There is a clear progression from input (features via CLI) through processing (parsing and generation) to execution (Playwright runner) and finally to output (reports).
- Integration Style: The system acts as an adapter that converts natural language BDD scenarios into executable tests that leverage Playwright’s native features.
- Extensibility: With AI integration, custom reporters, and a rich plugin-like mechanism for step definitions, the design is highly extensible.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface & CLI Input"
        CLI["src/cli - Command Line Processing"]:::cli
        Config["src/config - Configuration Loading"]:::cli
    end

    subgraph "Feature Parsing & Test Generation"
        Parsing["src/gherkin - Feature File Parsing"]:::parsing
        Cucumber["src/cucumber - Cucumber Processing"]:::parsing
        Generation["src/generate - Main Test Generation"]:::generation
        GenHelper["src/generate/test - Generation Helper Scripts"]:::generation
    end

    subgraph "BDD Runtime"
        Steps["src/steps - Step Definitions"]:::runtime
        BDD["src/runtime - BDD Runtime Management"]:::runtime
    end

    subgraph "Playwright Integration"
        PW["src/playwright - Playwright Execution & Integration"]:::playwright
    end

    subgraph "Reporting & Output"
        Reporter["src/reporter - Reporting and Output"]:::reporter
    end

    subgraph "Extensions"
        AI["src/ai - AI Enhancements"]:::ai
    end

    subgraph "Utilities"
        Utils["src/utils - General Helpers & Utilities"]:::utils
    end

    %% Data Flow Relationships
    CLI -->|"processes commands"| Parsing
    Config -->|"loads config"| Parsing

    Parsing -->|"parses features"| Cucumber
    Cucumber -->|"forwards data"| Generation
    Generation -->|"uses helper scripts"| GenHelper
    GenHelper -->|"generates tests"| Steps
    Steps -->|"invokes test steps"| BDD
    BDD -->|"initiates tests"| PW
    PW -->|"reports results"| Reporter

    AI -.->|"enhances generation"| Generation
    AI -.->|"enhances reporting"| Reporter

    %% Utility Cross-Cutting Dependencies
    CLI ---|"uses"| Utils
    Config ---|"uses"| Utils
    Parsing ---|"uses"| Utils
    Cucumber ---|"uses"| Utils
    Generation ---|"uses"| Utils
    GenHelper ---|"uses"| Utils
    Steps ---|"uses"| Utils
    BDD ---|"uses"| Utils
    PW ---|"uses"| Utils
    Reporter ---|"uses"| Utils
    AI ---|"uses"| Utils

    %% Click Events
    click CLI "https://github.com/vitalets/playwright-bdd/tree/main/src/cli"
    click Config "https://github.com/vitalets/playwright-bdd/tree/main/src/config"
    click Parsing "https://github.com/vitalets/playwright-bdd/tree/main/src/gherkin"
    click Cucumber "https://github.com/vitalets/playwright-bdd/tree/main/src/cucumber"
    click Generation "https://github.com/vitalets/playwright-bdd/tree/main/src/generate"
    click GenHelper "https://github.com/vitalets/playwright-bdd/tree/main/src/generate/test"
    click Steps "https://github.com/vitalets/playwright-bdd/tree/main/src/steps"
    click BDD "https://github.com/vitalets/playwright-bdd/tree/main/src/runtime"
    click PW "https://github.com/vitalets/playwright-bdd/tree/main/src/playwright"
    click Reporter "https://github.com/vitalets/playwright-bdd/tree/main/src/reporter"
    click AI "https://github.com/vitalets/playwright-bdd/tree/main/src/ai"
    click Utils "https://github.com/vitalets/playwright-bdd/tree/main/src/utils"

    %% Styles
    classDef cli fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef parsing fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef generation fill:#ffddcc,stroke:#cc6600,stroke-width:2px;
    classDef runtime fill:#e5ccff,stroke:#663399,stroke-width:2px;
    classDef playwright fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef reporter fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef ai fill:#ffd1dc,stroke:#ad1457,stroke-width:2px;
    classDef utils fill:#e0e0e0,stroke:#808080,stroke-width:2px;
```
