# klassijs/klassi-js architecture

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

- Interactive diagram: https://gitdiagram.com/klassijs/klassi-js
- Repository: https://github.com/klassijs/klassi-js

## Overview

##### Project type and purpose
- This is an open-source, CLI-driven JavaScript test automation framework (klassi-js).
- It layers on top of Cucumber.js (for BDD) and WebdriverIO (for browser automation), adding AI-powered debugging helpers.

##### File structure
- Top-level:
- index.js – the CLI entrypoint
- *.rc.js / .env – configuration files for environments and data
- runtime/ – all of the framework’s core modules
- runtime/ contains:
- drivers/ – browser driver abstraction (chromeDriver.js)
- helpers.js – utility functions wrapping WebdriverIO
- reporter/ – custom reporter engine (reporter.js)
- world.js – custom Cucumber “World” context
- cucumber.js – Cucumber configuration
- .dataConfigrc.js, .envConfigrc.js – project & environment variables

##### Key insights from README
- The framework discovers feature files, step definitions, page objects, shared objects at runtime via CLI flags or defaults
- It spawns Cucumber.js with a customized World containing `browser`, `pageObjects`, `sharedObjects`, `helpers`, `expect/assert`, and `trace`
- On each step, it issues commands to WebdriverIO; on failure, AI-driven debugging assists
- Reports are generated in HTML/JSON via the reporter module

##### Main components & their interactions
a. CLI Layer (index.js)
- Parses flags (--browser, --tags, --steps, etc.)
- Loads config (`.envConfigrc.js`, `.dataConfigrc.js`)
- Invokes Cucumber.js with custom `world.js` and paths
b. Configuration Loader
- Reads .env, .envConfigrc.js, .dataConfigrc.js
- Exposes environment & test data to the World
c. Cucumber Core
- Loads feature files and step definitions
- Hooks into Before/After events via world.js
d. World Context (runtime/world.js)
- Initializes `browser` instance from chromeDriver.js or other driver adapters
- Loads pageObjects & sharedObjects from disk into memory
- Binds helpers.js, chai `expect/assert`, and debug `trace`
- Integrates AI-assisted debugging at step failure
e. Driver Abstraction (runtime/drivers)
- chromeDriver.js establishes WebdriverIO session based on CLI browser flag
- Exposes standard `browser` APIs for steps & helpers
f. Helpers Module (runtime/helpers.js)
- Provides extra utility methods (loadPage, clickHiddenElement, sortByDate, etc.)
g. Reporter Module (runtime/reporter/reporter.js)
- Hooks into Cucumber lifecycle to generate HTML/JSON reports
- Emits build-time artifacts under ./reports/<browser>/
h. File System (I/O)
- Feature files, step definitions, pageObjects, sharedObjects, and config live on disk
- Reporter writes results back to disk

##### Architectural patterns & design principles
- Plugin/Extension: Cucumber.js and WebdriverIO are extended via configurable World
- Separation of Concerns:
- CLI & config parsing
- Test orchestration (Cucumber)
- Domain logic Helpers & PageObjects
- Driver layer isolated under runtime/drivers
- Reporting isolated under runtime/reporter
- Inversion of Control: Cucumber injects the World, which in turn injects all dependencies into step definitions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Orchestration
    CLI["index.js parses arguments"]:::core
    ConfigLoader["Configuration Loader"]:::io
    CucumberCore["cucumber.js (Cucumber Core)"]:::core
    World["runtime/world.js (World Context)"]:::core

    %% Utilities
    Helpers["runtime/helpers.js"]:::util
    DriverAdapter["runtime/drivers/chromeDriver.js"]:::util

    %% I/O & Reporting
    Reporter["runtime/reporter/reporter.js"]:::io
    FileSystem[("File System\n(features, steps, pageObjects,\nsharedObjects, configs)")]:::io

    %% External Systems
    BrowserDriver[(Browser Driver)]:::external

    %% Runtime Directory Group
    subgraph "runtime/" 
        World
        Helpers
        DriverAdapter
        Reporter
    end
    RuntimeDir["runtime/"]

    %% Connections
    CLI -->|"parses flags & invokes"| ConfigLoader
    CLI -->|"invokes"| CucumberCore
    ConfigLoader -->|"loads configs"| CucumberCore
    ConfigLoader -->|"exposes env & data"| World
    CucumberCore -->|"initializes"| World
    World -->|"injects browser API"| DriverAdapter
    DriverAdapter -->|"establishes session"| BrowserDriver
    BrowserDriver -->|"provides browser"| DriverAdapter
    World -->|"provides utilities"| Helpers
    World -->|"loads pageObjects & sharedObjects"| FileSystem
    CucumberCore -->|"emits events to"| Reporter
    Reporter -->|"writes reports to"| FileSystem

    %% Click Events
    click CLI "https://github.com/klassijs/klassi-js/blob/main/index.js"
    click ConfigLoaderEnv "https://github.com/klassijs/klassi-js/blob/main/.envConfigrc.js"
    click ConfigLoaderData "https://github.com/klassijs/klassi-js/blob/main/.dataConfigrc.js"
    click CucumberCore "https://github.com/klassijs/klassi-js/blob/main/cucumber.js"
    click World "https://github.com/klassijs/klassi-js/blob/main/runtime/world.js"
    click DriverAdapter "https://github.com/klassijs/klassi-js/blob/main/runtime/drivers/chromeDriver.js"
    click Helpers "https://github.com/klassijs/klassi-js/blob/main/runtime/helpers.js"
    click Reporter "https://github.com/klassijs/klassi-js/blob/main/runtime/reporter/reporter.js"
    click RuntimeDir "https://github.com/klassijs/klassi-js/tree/main/runtime/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#339,stroke-width:2px
    classDef util fill:#E0F8E0,stroke:#2A7,stroke-width:2px
    classDef io fill:#FFE4B5,stroke:#E68A00,stroke-width:2px
    classDef external fill:#E0E0E0,stroke:#888,stroke-width:2px,stroke-dasharray: 5 5
```
