# levetty/prisma-generator-integration-test-runner architecture

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

- Interactive diagram: https://gitdiagram.com/levetty/prisma-generator-integration-test-runner
- Repository: https://github.com/levetty/prisma-generator-integration-test-runner

## Overview

##### Project Type and Purpose
- This is a specialized library (“prisma-generator-integration-test-runner”) that acts as a Prisma generator. Its main task is to generate an integration test runner to support integration tests against an actual database.
- It is meant to be used with the Prisma CLI (via “npx prisma generate”), and the generated code is tailored for Jest-based integration tests.
- The README highlights its support for setting up pre-test seed data (recordSet), verifying method return values, and checking post-method database state (mutates).

##### Analyzing the File Structure
- Top-level directories and key files:
- “src” contains the core implementation of the generator (e.g., generator.ts, index.ts) plus the “template” folder, which holds the underlying templates (e.g., engine.ts.template and runner.ts) that produce the “it-runner” code.
- “example” provides a complete sample project demonstrating how to integrate and run the generated testing code. It includes its own Prisma schema (under “example/prisma”), migration files, Jest configuration, and test files under “example/src”.
- Various configuration files and scripts (e.g., tsconfig.json, package.json, pnpm-lock.yaml) help in building, testing, and running the project.
- This structure reveals a clear separation between the generator’s source code and an example application that illustrates its usage. The generator’s templating mechanism is central to how integration testing code is produced.

##### Key Components
- Prisma Schema (and configuration): Where the generator is invoked and configured via generator blocks in the Prisma schema.
- Prisma CLI/Generator Engine:
- When you run “npx prisma generate”, the Prisma CLI detects the custom generator (our library) based on the provider configuration.
- The CLI passes the necessary schema and context to the library.
- Code Generation Module (Core Library):
- The “src/generator.ts” and “src/index.ts” files are responsible for handling the generator logic.
- The “src/template” directory (with engine.ts.template and runner.ts) defines the template files that are used to render the final output.
- Generated Integration Test Runner:
- Output is created under the directory (typically “it-runner” within the same folder as the Prisma schema). Files such as “engine.ts” and “runner.ts” in “example/prisma/it-runner” represent the generated output that gets imported and used by Jest.
- Integration Testing Environment:
- Jest serves as the framework to run the tests.
- The tests will make use of PrismaClient (or TransactionClient) to connect to a test database.
- Components like “recordSet”, “method”, “returns”, and “mutates” flow in as function parameters to the test runner, controlling test setup, execution, and verification.

##### Relationships and Interactions
- At runtime, the Prisma CLI (when “npx prisma generate” is executed) calls the generator, which then uses the templates to produce integration test runner files in the designated output directory.
- The generated runner is imported into user test files (as shown in the example), where it manages:
- Pre-test database seeding (using “recordSet”).
- Invocation of the target method under test.
- Post-execution verifications (checks against “returns” and “mutates”).
- External services/components like Jest (for test execution) and the actual database (or test database) are linked with the generated integration test runner.

##### Architectural Patterns / Design Principles
- Code Generation Pattern: This project relies on templating (static templates under “src/template”) to dynamically generate integration test code based on the Prisma schema context.
- Modular Separation: There is a separation between the generator logic (in “src”) and its usage (demonstrated in “example”). This ensures that the core generator can be independently maintained while the sample application clearly exhibits integration points.
- Single Responsibility: Each module (template handling, generator logic, and test execution runner) encapsulates a distinct role, keeping responsibilities separated.

- Be as detailed as possible. Even if the file tree seems simple, capture every interaction: from reading the Prisma schema, triggering the generator process, using templates, to the actual integration test execution.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Generator Invocation
    subgraph "Generator Invocation"
        A["Prisma Schema (with generator config)"]:::schema
        B["Prisma CLI/Generator Process"]:::cli
        A -->|"triggers"| B
    end

    %% Code Generation Module
    subgraph "Code Generation Module"
        subgraph "Generator Core Logic"
            G1["generator.ts"]:::core
            G2["index.ts"]:::core
            G1 -->|"processes"| G2
        end
        subgraph "Template Engine"
            T1["engine.ts.template"]:::template
            T2["runner.ts"]:::template
            T1 -->|"renders"| T2
        end
        B -->|"invokes"| G1
        G2 -->|"suppliesContextTo"| T1
    end

    %% Generated Output
    subgraph "Generated Output"
        E["Integration Test Runner (it-runner)"]:::output
        T2 -->|"generates"| E
    end

    %% Integration Test Execution
    subgraph "Integration Test Execution"
        F1["jest.config.js"]:::testing
        F2["Test Files (src)"]:::testing
        E -->|"importedBy"| F1
        E -->|"importedBy"| F2
        F1 -->|"executesTestsAgainst"| Db["Test Database (PrismaClient)"]:::database
        F2 -->|"executesTestsAgainst"| Db
    end

    %% Click Events
    click A "https://github.com/levetty/prisma-generator-integration-test-runner/blob/main/example/prisma/schema.prisma"
    click G1 "https://github.com/levetty/prisma-generator-integration-test-runner/blob/main/src/generator.ts"
    click G2 "https://github.com/levetty/prisma-generator-integration-test-runner/blob/main/src/index.ts"
    click T1 "https://github.com/levetty/prisma-generator-integration-test-runner/blob/main/src/template/engine.ts.template"
    click T2 "https://github.com/levetty/prisma-generator-integration-test-runner/blob/main/src/template/runner.ts"
    click E "https://github.com/levetty/prisma-generator-integration-test-runner/tree/main/example/prisma/it-runner"
    click F1 "https://github.com/levetty/prisma-generator-integration-test-runner/blob/main/example/jest.config.js"
    click F2 "https://github.com/levetty/prisma-generator-integration-test-runner/tree/main/example/src"

    %% Styles
    classDef schema fill:#f4a261,stroke:#e76f51,stroke-width:2px;
    classDef cli fill:#2a9d8f,stroke:#264653,stroke-width:2px;
    classDef core fill:#e9c46a,stroke:#f4a261,stroke-width:2px;
    classDef template fill:#e76f51,stroke:#264653,stroke-width:2px;
    classDef output fill:#2a9d8f,stroke:#e9c46a,stroke-width:2px;
    classDef testing fill:#264653,stroke:#2a9d8f,stroke-width:2px;
    classDef database fill:#a8dadc,stroke:#457b9d,stroke-width:2px;
```
