# isaacharrisholt/supawright architecture

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

- Interactive diagram: https://gitdiagram.com/isaacharrisholt/supawright
- Repository: https://github.com/isaacharrisholt/supawright

## Overview

##### Project type and purpose
- Supawright is an NPM‐published test‑harness library that integrates Playwright E2E tests with a Supabase (Postgres) database.
- It provides a decorator (`withSupawright`) that instruments Playwright’s test runner, manages test fixtures by creating and tearing down records, and introspects database schemas and foreign‑key relationships.

##### File structure
- Top‑level:
- src/ – the core library code
– index.ts: exports `withSupawright` entry point
– harness.ts: core harness logic (fixture lifecycle, cleanup)
– tree.ts: builds a dependency graph of tables/foreign keys
– fixtures.ts: creates individual record fixtures, records what was created
– utils.ts: helper functions (e.g. random data generation)
– types.ts: TypeScript definitions, including generic `Database`
– test.ts: glue code for integrating with Playwright
- supabase/ – migrations and seed scripts used for library testing or examples
- test/ – library’s own tests against a local Supabase instance
- .github/workflows/ – CI/CD pipelines (publish to npm, run tests)
- Config files: tsconfig.json, package.json, Makefile (type‐generation), .changeset, pnpm-lock.yaml

##### README for additional insights
- Core flow:
a. `withSupawright` wraps Playwright tests to inject a `supawright` fixture.
b. On `create(...)`, it introspects the DB schema (via Supabase client), builds or extends a dependency tree, generates fake or overridden data, and inserts records.
c. On test teardown, it deletes records in dependency order and also discovers and deletes any “extra” related records.
- Supports custom data generators, overrides per table or type, and hooks like `beforeTeardown`.

a. Main components
1. Playwright Test Runner
2. Supawright Harness Library (the `withSupawright` wrapper)
3. Internal Modules:
– Schema Introspector (tree.ts)
– Fixture Manager (fixtures.ts, utils.ts)
– Cleanup Engine (harness.ts)
– Types & Config Loader (types.ts + user‐provided overrides)
4. Supabase Client (JavaScript/TypeScript API layer)
5. Postgres Database (local or remote Supabase instance)
6. CI/CD Pipelines (GitHub Actions for test & publish)
b. Relationships and data flow
- Playwright Test Runner invokes a test wrapped by `withSupawright`.
- `withSupawright` configures and instantiates a Supawright Harness before tests.
- Harness uses Supabase Client to:
- Introspect schema and FKs → builds dependency graph
- Insert records (via Fixture Manager)
- Provide the `supawright` API into tests
- Tests call `supawright.create(...)` → Fixture Manager generates data, uses Supabase Client to insert
- After test, Harness calls Cleanup Engine → navigates the dependency graph, deletes records (including “orphaned” ones discovered), using Supabase Client
- CI/CD pipelines run tests, generate types (Makefile), and publish package
c. Architectural patterns and principles
- Decorator/Wrapper around Playwright’s test function
- Dependency graph (tree) data structure for ordering create/delete operations
- Inversion of Control: user can inject custom generators and overrides
- Separation of concerns: Introspection vs. Fixture creation vs. Cleanup
d. Key technologies & libraries
- Node.js/TypeScript
- Playwright test runner
- Supabase JavaScript client (and Postgres Meta under the hood)
- pnpm, Makefile for dev workflows
- GitHub Actions for CI/CD

##### Detail
- Every major module in `src/` as a node or subcomponent.
- Recursive flow: create → introspect → insert → discover extra → delete.
- Extension points: where user code (generators/overrides) plugs in.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Components
    A["Playwright Runner"]:::tools
    subgraph "Supawright Harness"
        direction TB
        Index["Decorator: withSupawright"]:::runtime
        Glue["Playwright Integration Glue"]:::runtime
        Introspect["Schema Introspector"]:::runtime
        Fixture["Fixture Manager"]:::runtime
        Cleanup["Cleanup Engine"]:::runtime
        Utils["Utility Functions"]:::runtime
        Types["Types & Config Loader"]:::runtime
    end
    B["Supabase Client"]:::external
    C["Postgres DB"]:::external
    CI["CI/CD (GitHub Actions)"]:::ci

    %% Data Flows
    A -->|"wraps tests"| Index
    Index -->|"loads integration"| Glue
    A -->|"injects supawright fixture"| Glue
    Glue -->|"initialize harness"| Introspect
    Introspect -->|"schema introspection"| B
    Fixture -->|"INSERT records"| B
    Cleanup -->|"DELETE cleanup"| B
    Utils -->|"helper routines"| Fixture
    Types -->|"load config & types"| Fixture
    B -->|"queries"| C
    CI -->|"run tests"| A
    CI -->|"publish package"| Index

    %% Click Events
    click Index "https://github.com/isaacharrisholt/supawright/blob/main/src/index.ts"
    click Harness "https://github.com/isaacharrisholt/supawright/blob/main/src/harness.ts"
    click Introspect "https://github.com/isaacharrisholt/supawright/blob/main/src/tree.ts"
    click Fixture "https://github.com/isaacharrisholt/supawright/blob/main/src/fixtures.ts"
    click Utils "https://github.com/isaacharrisholt/supawright/blob/main/src/utils.ts"
    click Types "https://github.com/isaacharrisholt/supawright/blob/main/src/types.ts"
    click Glue "https://github.com/isaacharrisholt/supawright/blob/main/src/test.ts"
    click supabase "https://github.com/isaacharrisholt/supawright/tree/main/supabase/"
    click test "https://github.com/isaacharrisholt/supawright/tree/main/test/"
    click CI "https://github.com/isaacharrisholt/supawright/blob/main/ .github/workflows/publish.yml"
    click CI "https://github.com/isaacharrisholt/supawright/blob/main/ .github/workflows/push.yml"
    click Makefile "https://github.com/isaacharrisholt/supawright/tree/main/Makefile"
    click tsconfig "https://github.com/isaacharrisholt/supawright/blob/main/tsconfig.json"
    click package "https://github.com/isaacharrisholt/supawright/blob/main/package.json"

    %% Styles
    classDef runtime fill:#cde8ff,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef external fill:#e2ffe2,stroke:#2c662d,color:#2c662d,stroke-width:1px;
    classDef tools fill:#fff4e5,stroke:#d1861f,color:#d1861f,stroke-width:1px;
    classDef ci fill:#eeeeee,stroke:#888888,color:#555555,stroke-width:1px;
```
