# charlyautomatiza/starter-karate-dsl architecture

> Architecture diagram of the GitHub repository charlyautomatiza/starter-karate-dsl, 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/charlyautomatiza/starter-karate-dsl
- Repository: https://github.com/charlyautomatiza/starter-karate-dsl

## Overview

##### Main Components of the System
- API Test Suite – The core of the project where all API tests are defined.
- REST API tests: Located under src/test/java/examples/users with the feature file (users.feature) and its associated runner (UsersRunner.java).
- GraphQL API tests: Located under src/test/java/examples/usersgql with the feature file (users-gql.feature), associated queries (e.g., user-by-id.graphql), and runner (UsersGqlRunner.java).
- Additional examples/test files: Such as ExamplesTest.java for generic examples.
- Configuration & Setup:
- karate-config.js: Contains global configuration for Karate tests.
- logback-test.xml: Provides logging configuration.
- pom.xml: Maven build configuration including dependencies and build plugins necessary for the execution of tests.
- CI/CD Integration:
- GitHub Workflows: .github/workflows/karate-test-runner.yml to trigger tests on pushes.
- JUnit Report actions on the marketplace, as referenced in the README.
- Reporting:
- Test execution generates HTML reports in target/karate-reports (even though the target folder isn’t shown, it’s generated at runtime).

##### Relationships and Interactions
- Test Runner -> Feature Files: Runners (e.g., UsersRunner.java, UsersGqlRunner.java) are responsible for invoking the execution of the corresponding feature files.
- Feature Files -> API Endpoints: The feature files contain scenarios that target external API endpoints (REST or GraphQL), though these endpoints are not hosted within the project.
- Configuration -> Tests: karate-config.js and logback-test.xml are used to set up the testing environment and logging.
- Maven Lifecycle -> Execution & Reporting: The pom.xml drives compilation, test execution (via mvn clean test), and report generation.
- GitHub Actions -> CI Test Pipeline: When a push event occurs, .github/workflows/karate-test-runner.yml triggers the Maven commands on the remote environment and subsequently builds reports of the test runs.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project clearly separates test definitions (feature files), test runners, configuration files, and CI/CD workflows.
- Convention over Configuration: Following Karate DSL conventions for directory structure and naming, making it easy to locate and modify tests.
- Automation & Reporting: Built-in support for automatic test execution and unified reports, aiding in continuous integration practices.

##### Relevant Technologies, Frameworks, and Tools
- Karate DSL: The primary framework used for writing and executing API tests (both REST and GraphQL).
- Maven: Manages dependency, build lifecycle, and runs tests.
- Java JDK (version 17 is required): For running the test automation framework.
- GitHub Actions: For CI/CD automation.
- JUnit and Report Generation Tools: For generating structured test reports.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Test Suite Component
    subgraph "API Test Suite"
        subgraph "REST API Tests"
            UsersFeature["users.feature (REST)"]:::testSuite
            UsersRunner["UsersRunner.java"]:::testSuite
            UsersRunner -->|"executes"| UsersFeature
        end
        subgraph "GraphQL API Tests"
            UsersGQLFeature["users-gql.feature (GraphQL)"]:::testSuite
            UsersGQLRunner["UsersGqlRunner.java"]:::testSuite
            GraphQLQuery["user-by-id.graphql (Query)"]:::testSuite
            UsersGQLRunner -->|"executes"| UsersGQLFeature
            UsersGQLFeature -->|"uses"| GraphQLQuery
        end
        AdditionalTest["ExamplesTest.java (Generic Test)"]:::testSuite
    end

    %% Configuration & Setup
    subgraph "Configuration & Setup"
        KarateConfig["karate-config.js"]:::config
        LogbackTest["logback-test.xml"]:::config
        Pom["pom.xml"]:::config
    end

    %% CI/CD and Reporting
    subgraph "CI/CD & Reporting"
        GitHubActions["GitHub Actions Workflow"]:::ci
        MavenBuild["Maven Build & Test Execution"]:::ci
        TestReports["Test Reports (target/karate-reports)"]:::reporting
    end

    %% External API Endpoints
    ExternalAPI["External API Endpoints Under Test"]:::external

    %% Relationships
    Pom -->|"triggers"| MavenBuild
    KarateConfig -->|"configures"| UsersRunner
    KarateConfig -->|"configures"| UsersGQLRunner
    LogbackTest -->|"configures_logging"| MavenBuild

    GitHubActions -->|"triggers"| MavenBuild
    MavenBuild -->|"executes_tests"| UsersRunner
    MavenBuild -->|"executes_tests"| UsersGQLRunner
    MavenBuild -->|"executes_tests"| AdditionalTest

    UsersFeature -->|"calls"| ExternalAPI
    UsersGQLFeature -->|"calls"| ExternalAPI

    MavenBuild -->|"generates"| TestReports

    %% Click Events
    click UsersFeature "https://github.com/charlyautomatiza/starter-karate-dsl/blob/main/src/test/java/examples/users/users.feature"
    click UsersRunner "https://github.com/charlyautomatiza/starter-karate-dsl/blob/main/src/test/java/examples/users/UsersRunner.java"
    click UsersGQLFeature "https://github.com/charlyautomatiza/starter-karate-dsl/blob/main/src/test/java/examples/usersgql/users-gql.feature"
    click GraphQLQuery "https://github.com/charlyautomatiza/starter-karate-dsl/blob/main/src/test/java/examples/usersgql/queries/user-by-id.graphql"
    click UsersGQLRunner "https://github.com/charlyautomatiza/starter-karate-dsl/blob/main/src/test/java/examples/usersgql/UsersGqlRunner.java"
    click AdditionalTest "https://github.com/charlyautomatiza/starter-karate-dsl/blob/main/src/test/java/examples/ExamplesTest.java"
    click KarateConfig "https://github.com/charlyautomatiza/starter-karate-dsl/blob/main/src/test/java/karate-config.js"
    click LogbackTest "https://github.com/charlyautomatiza/starter-karate-dsl/blob/main/src/test/java/logback-test.xml"
    click Pom "https://github.com/charlyautomatiza/starter-karate-dsl/blob/main/pom.xml"
    click GitHubActions "https://github.com/charlyautomatiza/starter-karate-dsl/blob/main/.github/workflows/karate-test-runner.yml"
    click TestReports "https://github.com/charlyautomatiza/starter-karate-dsl/tree/main/target/karate-reports"

    %% Styles
    classDef testSuite fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef config fill:#98fb98,stroke:#000,stroke-width:2px;
    classDef ci fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef reporting fill:#ffcccb,stroke:#000,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
