# zebrunner/carina architecture

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

- Interactive diagram: https://gitdiagram.com/zebrunner/carina
- Repository: https://github.com/zebrunner/carina

## Overview

##### Project Type and Purpose
- This is an open-source Java-based test automation framework (Carina) that provides a unified API for Web, Mobile (iOS/Android), Windows, REST services, databases, and reporting.
- It consists of a core library (carina-core) plus optional modules (carina-api, carina-azure, carina-aws-s3, etc.) and an archetype project to generate new test projects.

##### Main Components
a. Carina Core Modules (src/main/java/com/zebrunner/carina)
- Core engine: AbstractTest, IAbstractTest
- Configuration: ReportConfiguration, TestConfiguration
- Session creation & WebDriver wrapper (carina-webdriver)
- Filters & rules (v1, v2 filter subsystems)
- Listeners (TestNG listeners chain, CarinaListener)
- Reporting connectors (Email, QTest, TestRail)
- Utilities: DateUtils, RetryAnalyzer, ParameterGenerator, ArtifactUtils, ConnectionFactory
b. Archetype Project (archetype/)
- Maven archetype that scaffolds a Carina-powered test project, with sample packages for API, DB, GUI, SOAP, WebSocket, mobile.
c. Resources & Configuration
- src/main/resources: localization (L10N), capabilities.properties, config.properties, mybatis.config.xml, log4j2.xml
- Archetype resources: _config.properties, database/email/testdata properties, test data sources (CSV, XLSX), Freemarker templates for API.
d. Optional Modules
- carina-api (RestAssured + Freemarker for REST)
- carina-aws-s3, carina-azure, carina-appcenter, carina-dataprovider, etc.
e. Documentation & Site
- docs/: mkdocs documentation, getting started guides, advanced topics, architecture overviews.

##### Relationships & Data Flows
- User test code (extends AbstractTest) → Carina Core
→ SessionFactory (WebDriver/Appium) ↔ Selenium/Appium servers or cloud providers (BrowserStack)
→ Execution on target (Web/Mobile/Windows) → Listeners gather results
→ Report generators push to Email/QTest/TestRail/Zebrunner
- DB layer uses MyBatis mappers + models to read/write data.
- API tests use Freemarker templates + RestAssured.
- Configuration & capabilities read from properties files.
- Archetype generates project skeleton that plugs into Carina Core and optional modules.

##### Architectural Patterns & Principles
- Layered architecture: Test layer → Core engine → Driver/session layer → External tools/services.
- Plugin/extensibility via interfaces (carina-commons) and ServiceLoader (META-INF/services/org.testng.ITestNGListener).
- Separation of concerns: filters, listeners, reporters, utilities each in separate packages.
- Maven modularity: “carina-core” artifact plus optional JARs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Test Project
    subgraph "Test Project (Archetype)" 
        Archetype["Project Skeleton"]:::optional
    end

    %% Carina Core
    subgraph "Carina Core" 
        direction TB
        subgraph "Core Engine"
            AbstractTest["AbstractTest"]:::core
            IAbstractTest["IAbstractTest"]:::core
        end
        subgraph "Configuration"
            ReportConfiguration["ReportConfiguration"]:::core
            TestConfiguration["TestConfiguration"]:::core
        end
        subgraph "Filters"
            direction TB
            FiltersV1["v1 Subsystem"]:::core
            FiltersV2["v2 Subsystem"]:::core
            Rule["Rule (v1)"]:::core
        end
        subgraph "Listeners"
            CarinaListener["CarinaListener"]:::core
            CarinaListenerChain["CarinaListenerChain"]:::core
            AbstractTestListener["AbstractTestListener"]:::core
        end
        subgraph "Reporting Connectors"
            EmailReportGenerator["EmailReportGenerator"]:::core
            IQTestManager["IQTestManager (QTest)"]:::core
            ITestRailManager["ITestRailManager"]:::core
        end
        subgraph "Utilities"
            DateUtils["DateUtils"]:::core
            RetryAnalyzer["RetryAnalyzer"]:::core
            ParameterGenerator["ParameterGenerator"]:::core
        end
        subgraph "Plugin Interfaces"
            ServiceLoader["ServiceLoader (ITestNGListener)"]:::plugin
        end
    end

    %% Resources
    subgraph "Resources & Config" 
        L10N["L10N messages"]:::resources
        Capabilities["capabilities.properties"]:::resources
        ConfigProps["config.properties"]:::resources
        MyBatisConfig["mybatis.config.xml"]:::resources
        Log4j2["log4j2.xml"]:::resources
        TestDataProps["testdata.properties"]:::resources
    end

    %% Optional Modules
    subgraph "Optional Modules"
        CarinaAPI["carina-api"]:::optional
        CarinaAWSS3["carina-aws-s3"]:::optional
        CarinaAzure["carina-azure"]:::optional
        CarinaAppCenter["carina-appcenter"]:::optional
    end

    %% External Dependencies
    subgraph "External Dependencies"
        TestNG["TestNG"]:::external
        Selenium["Selenium/Appium"]:::external
        MyBatis["MyBatis"]:::external
        Freemarker["Freemarker"]:::external
    end

    %% External Services
    BrowserStack["BrowserStack"]:::external
    DBServer["DB Server"]:::db
    EmailServer["Email Server"]:::external
    RESTEndpoint["REST Endpoint"]:::external
    CloudStorage["AWS S3/Azure/AppCenter"]:::external

    %% Interactions
    Archetype -->|extends| AbstractTest
    Archetype -->|implements| IAbstractTest
    AbstractTest -->|reads config| ReportConfiguration
    AbstractTest -->|reads config| TestConfiguration
    AbstractTest -->|applies filters| FiltersV1
    AbstractTest -->|applies filters| FiltersV2
    FiltersV1 -->|uses rules| Rule
    AbstractTest -->|registers listeners| CarinaListenerChain
    CarinaListenerChain -->|contains| CarinaListener
    CarinaListenerChain -->|contains| AbstractTestListener
    AbstractTest -->|invokes utilities| DateUtils
    AbstractTest -->|invokes utilities| RetryAnalyzer
    AbstractTest -->|invokes utilities| ParameterGenerator
    AbstractTest -->|loads plugins| ServiceLoader
    AbstractTest -->|creates session via| Selenium
    Selenium -->|executes| BrowserStack
    AbstractTest -->|executes| CloudStorage
    AbstractTest -->|connects via JDBC| MyBatis
    MyBatis -->|accesses| DBServer
    APIFlow["API Test Flow"]:::external -->|templates via| Freemarker
    Freemarker -->|sends HTTP to| RESTEndpoint
    CarinaListener -->|push results to| EmailReportGenerator
    CarinaListener -->|push results to| IQTestManager
    CarinaListener -->|push results to| ITestRailManager
    EmailReportGenerator -->|sends email via| EmailServer

    %% Click Events
    click AbstractTest "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/AbstractTest.java"
    click IAbstractTest "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/IAbstractTest.java"
    click ReportConfiguration "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/config/ReportConfiguration.java"
    click TestConfiguration "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/config/TestConfiguration.java"
    click FiltersV1 "https://github.com/zebrunner/carina/tree/master/src/main/java/com/zebrunner/carina/core/filter/v1"
    click FiltersV2 "https://github.com/zebrunner/carina/tree/master/src/main/java/com/zebrunner/carina/core/filter/v2"
    click Rule "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/filter/v1/rule/Rule.java"
    click CarinaListener "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/listeners/CarinaListener.java"
    click CarinaListenerChain "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/listeners/CarinaListenerChain.java"
    click AbstractTestListener "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/listeners/AbstractTestListener.java"
    click EmailReportGenerator "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/report/email/EmailReportGenerator.java"
    click IQTestManager "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/report/qtest/IQTestManager.java"
    click ITestRailManager "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/core/report/testrail/ITestRailManager.java"
    click DateUtils "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/utils/DateUtils.java"
    click RetryAnalyzer "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/utils/retry/RetryAnalyzer.java"
    click ParameterGenerator "https://github.com/zebrunner/carina/blob/master/src/main/java/com/zebrunner/carina/utils/ParameterGenerator.java"
    click ServiceLoader "https://github.com/zebrunner/carina/blob/master/src/main/resources/META-INF/services/org.testng.ITestNGListener"
    click L10N "https://github.com/zebrunner/carina/blob/master/src/main/resources/L10N/messages.properties"
    click Capabilities "https://github.com/zebrunner/carina/blob/master/src/main/resources/capabilities.properties"
    click ConfigProps "https://github.com/zebrunner/carina/blob/master/src/main/resources/config.properties"
    click MyBatisConfig "https://github.com/zebrunner/carina/blob/master/src/main/resources/mybatis.config.xml"
    click Log4j2 "https://github.com/zebrunner/carina/blob/master/src/main/resources/log4j2.xml"
    click TestDataProps "https://github.com/zebrunner/carina/blob/master/src/main/resources/testdata.properties"
    click Archetype "https://github.com/zebrunner/carina/tree/master/archetype/"
    click TestNG "https://github.com/zebrunner/carina/blob/master/docs/getting_started.md"
    click Selenium "https://github.com/zebrunner/carina/blob/master/docs/advanced/program_flow.md"

    %% Styles
    classDef core fill:#E8F1F2,stroke:#333,stroke-width:1px
    classDef optional fill:#F9E2AE,stroke:#333,stroke-width:1px
    classDef external fill:#D5E8D4,stroke:#333,stroke-width:1px
    classDef db fill:#FFE6E6,stroke:#333,stroke-width:1px
    classDef plugin fill:#E1D5E7,stroke:#333,stroke-width:1px
    classDef resources fill:#FFF2CC,stroke:#333,stroke-width:1px
```
