# kolodny/safetest architecture

> Architecture diagram of the GitHub repository kolodny/safetest, 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/kolodny/safetest
- Repository: https://github.com/kolodny/safetest

## Overview

##### Main System Components
- Core Testing Library: This is the nucleus where the core test lifecycle is managed (e.g., in the “src” folder: modules like setup.ts, render.ts, bootstrap.ts, expect.ts, etc.). This part orchestrates test execution and communication between Node and browser.
- Test Runner Adapters: Separate implementations for different test runners (see “safetest/jest” and integrations for Vitest in config files and examples). These wrap the testing API to allow familiar syntax and integration.
- Browser Automation Layer: The integration with Playwright (and its configuration) which is used to drive real browser instances and record artifacts such as screenshots, videos, and traces.
- Framework Adapters: These include modules for React, Vue, Svelte, Angular, and Solid (for example, files in “src/react.ts”, “src/vue.ts”, etc.) that bootstrap and render components, and allow the tests to be written in a framework-specific manner.
- Override/Mimic and Bridge Mechanism: Components that provide test-time overrides (see usage of “createOverride”) and enable two-way communication between the Node environment and the in-page browser context. This mechanism lets you intercept test execution to simulate errors or change props.
- Artifacts and Reporting Module: The system that collects test outcomes, snapshots (via jest-image-snapshot), trace files, and videos; then processes them for a unified report (as seen in the reporting section of the README and the use of “safetest/report”).
- CLI and Environment Configuration: The support for environment variables (like OPT_URL, OPT_DOCKER, OPT_CI), along with the scripts in package.json, providing ways to run in local or CI modes (including Docker integration for deterministic snapshots).

##### Project’s File Structure for Architectural Clues
- The top-level directories include examples (a variety of front-end project samples for Angular, Create React App, Next.js, various Vite configurations, etc.) which point to how Safetest is intended to be used in multiple front-end frameworks.
- The “src” folder contains core modules that underlie the testing library functionality (rendering, bootstrapping, test hooks, browser-mock setup, snapshot helpers, etc.).
- The project also contains various configuration files (like tsconfig.json, .npmignore, .gitignore, build scripts, and GitHub workflows) that help with testing, reporting, and automation on CI/CD pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Environment Configuration Subgraph
    subgraph "CLI & Environment Configuration"
        cli1["src/cli.ts"]:::cli
        cli2["src/docker.ts"]:::cli
        cli3["package.json"]:::cli
        cli4["build.js"]:::cli
    end

    %% Test Runner Adapters Subgraph
    subgraph "Test Runner Adapters"
        runner1["src/jest.ts"]:::runner
        runner2["jest.js"]:::runner
        runner3["vitest.ts"]:::runner
        runner4["vitest.js"]:::runner
        runner5["vitest.d.ts"]:::runner
        runner6["jest-mock.ts"]:::runner
    end

    %% Core Testing Library Subgraph
    subgraph "Core Testing Library"
        core1["src/bootstrap.ts"]:::core
        core2["src/render.ts"]:::core
        core3["src/setup.ts"]:::core
        core4["src/expect.ts"]:::core
        core5["src/global.ts"]:::core
        core6["src/index.ts"]:::core
    end

    %% Browser Automation Layer Subgraph
    subgraph "Browser Automation Layer"
        auto1["src/browser-mock.ts"]:::automation
        auto2["src/get-page.ts"]:::automation
        auto3["src/playwright-types.ts"]:::automation
        auto4["src/playwright-page-keys.ts"]:::automation
    end

    %% Framework Adapter Layer Subgraph
    subgraph "Framework Adapter Layer"
        fram1["src/react.ts"]:::adapter
        fram2["src/vue.ts"]:::adapter
        fram3["src/svelte.ts"]:::adapter
        fram4["src/solid.ts"]:::adapter
        fram5["src/ng.ts"]:::adapter
    end

    %% Override/Mimic and Bridge Mechanism Subgraph
    subgraph "Override/Mimic and Bridge"
        over1["src/override-events.ts"]:::override
        over2["src/anythingProxy.ts"]:::override
    end

    %% Artifacts and Reporting Module Subgraph
    subgraph "Artifacts and Reporting Module"
        art1["src/artifacts.ts"]:::artifacts
        art2["report.js"]:::artifacts
        art3["report.d.ts"]:::artifacts
    end

    %% Connections between representative nodes
    %% Using the first node of each subgraph as the representative
    cli1 -->|"triggers"| runner1
    runner1 -->|"initiates"| core1
    core1 -->|"launches/control"| auto1
    core1 -->|"bootstrapsUI"| fram1
    core1 -->|"injectsOverride"| over1
    auto1 -->|"reports"| art1
    core1 -->|"reports"| art1

    %% Styles
    classDef cli fill:#D3D3D3,stroke:#000,stroke-width:2px,color:#000;
    classDef runner fill:#90EE90,stroke:#000,stroke-width:2px,color:#000;
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px,color:#000;
    classDef automation fill:#FFD580,stroke:#000,stroke-width:2px,color:#000;
    classDef adapter fill:#DDA0DD,stroke:#000,stroke-width:2px,color:#000;
    classDef override fill:#FFB6C1,stroke:#000,stroke-width:2px,color:#000;
    classDef artifacts fill:#F4A460,stroke:#000,stroke-width:2px,color:#000;
```
