# emergingcode/gherxunit architecture

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

- Interactive diagram: https://gitdiagram.com/emergingcode/gherxunit
- Repository: https://github.com/emergingcode/gherxunit

## Overview

##### Project Type & Purpose
- This project is a .NET library that extends xUnit to support Behavior-Driven Development (BDD) by allowing tests to be written using Gherkin syntax.
- Its purpose is to enable teams already using xUnit to adopt BDD without needing external tools like Cucumber or SpecFlow.
- Key functionality includes custom lexers (for Gherkin language elements), BDD attributes, and an integration mechanism to run test scenarios written in a BDD style via xUnit.

##### Analysis of the File Structure
- There are two primary code areas:
a. The “src/base/GherXunit.Core” folder which contains the core implementation (attributes, interfaces, methods, and a variety of samples demonstrating BDD concepts such as Backgrounds, Features, Scenario Outlines, etc.).
b. The “src/lib/GherXunit” folder which appears to provide additional content, likely wrapping or extending the core functionality. It also contains its own project file and global using statements.
- The project uses a modular structure with clearly separated cores, samples, and extension libraries that promote extensibility via the use of partial classes and customizable lexers.

##### Main Components
- xUnit Framework (External Dependency): The underlying test framework that GherXunit leverages.
- GherXunit Core Library:
- Attributes, Interfaces, Methods that enable specifying Gherkin scenarios.
- Internal implementations for executing and parsing BDD style scenarios.
- GherXunit Content Library (in src/lib):
- Additional attributes and string handling features which might provide alternative or enriched functionalities compared to the core.
- Samples/Demos:
- Various sample folders (e.g., Samples/Backgrounds, Features, etc.) demonstrating how tests are written using the library.
- Custom Lexers:
- Implementation and integration of lexers (including built-in ones for “PtBr” and “EnUs” and custom lexers like the EmojiGherXunitLexer) which are key customization points for the library.
- NuGet Package & Continuous Integration:
- The repository setup (with GitHub workflows) shows CI/CD (for example, dotnet.yml) and distribution via NuGet.

##### Relationships and Interactions
- The test classes defined by client code use the GherXunit attributes to annotate methods for test scenarios.
- When tests execute, these attributes and helper methods (from both the core and content libraries) interact with the xUnit test runner.
- Lexers are injected into the test execution process, converting natural language steps into instructions for the test engine.
- The modular structure (partial classes) emphasizes separation of scenario definitions from the step implementations.
- Samples serve as an example integration of these components, showing the interaction between scenario definitions and their step method implementations.

##### Key Architectural Patterns or Design Principles
- Layered/Modular Architecture: Separation into core and library (extension) modules.
- Use of Partial Classes to modularize code (separating scenario definitions from step methods).
- Dependency Injection (for example, when passing lexers to the execution methods, allowing clients to customize the BDD syntax).
- Clean separation of concerns between defining test scenarios and executing the underlying behavior.

##### Elements
- Clear labels for each component with brief descriptions (e.g., “GherXunit Core,” “GherXunit Content/Extensions,” “xUnit Framework”).
- From “Test Classes (User Code)” to “GherXunit Core Library” indicating ‘invokes / uses’ relationship.
- From “Core Library” to “Custom Lexers” showing dependency injection.
- From “GherXunit Library” to “xUnit Framework” for test execution flow.

- Below that, position the “GherXunit Library,” subdividing it into the “Core Component” and “Content/Extension Component.”
- “User Test Scenarios” (using partial classes and Gherkin syntax) interacting with the GherXunit Library.
- On the side, indicate the supporting infrastructure which includes the CI/CD workflows and distribution via NuGet.

## Diagram (Mermaid)

```mermaid
flowchart TD
    X["xUnit Framework"]:::external
    UT["User Test Scenarios"]:::user
    CL["Custom Lexers"]:::integration
    CI_CD["CI/CD Workflow"]:::ci
    NF["NuGet & Project Files"]:::ci

    subgraph "GherXunit Core"
        A["Attributes.cs"]:::core
        I["Interfaces.cs"]:::core
        M["Methods.cs"]:::core
        SH["StringHandler.cs"]:::core
        S["BDD Samples/Demos"]:::core
    end

    subgraph "GherXunit Content/Extension"
        GA["GherXunit.Content.Attributes.cs"]:::content
        GI["GherXunit.Content.Interfaces.cs"]:::content
        GM["GherXunit.Content.Methods.cs"]:::content
        GSH["GherXunit.Content.StringHandler.cs"]:::content
        GU["GlobalUsings.cs"]:::content
    end

    UT -->|"invokes"| A
    UT -->|"invokes"| GA

    A -->|"executesVia"| X
    I -->|"executesVia"| X
    GA -->|"executesVia"| X
    GI -->|"executesVia"| X

    SH -->|"injects"| CL

    CI_CD -->|"builds"| A
    NF -->|"packages"| GA

    click A "https://github.com/emergingcode/gherxunit/blob/develop/src/base/GherXunit.Core/Attributes.cs"
    click I "https://github.com/emergingcode/gherxunit/blob/develop/src/base/GherXunit.Core/Interfaces.cs"
    click M "https://github.com/emergingcode/gherxunit/blob/develop/src/base/GherXunit.Core/Methods.cs"
    click SH "https://github.com/emergingcode/gherxunit/blob/develop/src/base/GherXunit.Core/StringHandler.cs"
    click S "https://github.com/emergingcode/gherxunit/tree/develop/src/base/GherXunit.Core/Samples"
    click GA "https://github.com/emergingcode/gherxunit/blob/develop/src/lib/GherXunit/GherXunit.Content.Attributes.cs"
    click GI "https://github.com/emergingcode/gherxunit/blob/develop/src/lib/GherXunit/GherXunit.Content.Interfaces.cs"
    click GM "https://github.com/emergingcode/gherxunit/blob/develop/src/lib/GherXunit/GherXunit.Content.Methods.cs"
    click GSH "https://github.com/emergingcode/gherxunit/blob/develop/src/lib/GherXunit/GherXunit.Content.StringHandler.cs"
    click GU "https://github.com/emergingcode/gherxunit/blob/develop/src/lib/GherXunit/GlobalUsings.cs"
    click CI_CD "https://github.com/emergingcode/gherxunit/blob/develop/.github/workflows/dotnet.yml"
    click NF "https://github.com/emergingcode/gherxunit/blob/develop/src/GherXunit.sln"

    classDef external fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef core fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef content fill:#98fb98,stroke:#000,stroke-width:2px;
    classDef integration fill:#f4a460,stroke:#000,stroke-width:2px;
    classDef user fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef ci fill:#ffb6c1,stroke:#000,stroke-width:2px;
```
