How isaacharrisholt/supawright works
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.