mirror of https://github.com/yusufipk/OpenFrame.git synced 2026-09-11 09:36:08 +00:00

Files

T

yusufipk 1d099c68f2 test: add unit, API, component and end-to-end test suites

The repo had no automated tests. Every change was verified by hand.

Adds four layers, 2023 tests in total, runnable with one command:

- 1191 unit tests over the pure logic in lib/, including the full
  computeProjectAccess permission matrix and the billing gate
- 167 component and hook tests in jsdom, covering the hooks that hold
  real logic rather than presentational wrappers
- 647 API integration tests against a real Postgres, with only auth()
  mocked, including a data-driven sweep asserting that none of the 60
  route modules answers 2xx to an unauthenticated caller
- 18 Playwright specs driving a real browser against a real build

Infrastructure: vitest.config.ts with three projects, a disposable
Postgres and MinIO in docker-compose.test.yml, factories and helpers
under tests/, scripts/test.sh as the single entry point, a pre-push
hook running bun run verify, and CI split into check, test and e2e jobs.

The test database is built with prisma db push plus a replay of the
hand-written SQL, because prisma migrate deploy cannot build this schema
from empty: the migration history has no captured baseline. This mirrors
what scripts/docker-db-bootstrap.ts already does in production, and
tests/setup/db-global.ts carries a drift guard so a new migration fails
the run until someone reviews it.

Production code is unchanged apart from one pure-function extraction out
of use-video-player.ts, which was too large to test in jsdom.

Several tests pin behaviour that looks wrong, each marked KNOWN BUG in
place. TESTING.md section 12 records where the plan turned out to be
wrong, and AGENTS.md now states which layer a change needs a test in.

2026-07-26 11:17:26 +07:00

4.6 KiB

Raw Blame History

AGENTS.md

Must-follow constraints

Use bun only. Do not use npm or pnpm.
Do not start the dev server (bun run dev); assume it is already running.
If you change prisma/schema.prisma, run bun run db:generate.
In App Router dynamic routes, keep params typed as Promise<...> and await params in handlers/pages.

Validation before finishing

Run bun run check.
Run bun run verify (this is bun run check plus the unit and component tests).
If you touched an API route, also run bun run test:api. It needs the test database: bun run test:db:up first.

Testing

The testing stack, layout and conventions live in TESTING.md. Read it before adding a test.
Tests live in a top-level tests/ tree, never colocated with the code.
Import test globals explicitly: import { describe, it, expect, vi } from 'vitest';.
Never write a BigInt literal (1n) in any file. tsconfig.json targets ES2017, so tsc rejects the syntax with TS2737 and bun run check fails. Use BigInt(1) instead, and compare BigInt(...) against BigInt(...).

When a change needs a test

Match the change to a layer. Most changes need exactly one.

You changed	Write
A pure function in `lib/` (validation, a limit, a date rule, a URL or filename check, a permission calculation)	a unit test in `tests/unit/lib/`
An API route, or any authorization, quota or billing rule behind one	an integration test in `tests/api/`
A new API route	classify it in `tests/api/auth-matrix.test.ts`, or the suite fails until you do
Real logic in a React hook (optimistic updates, throttling, retries)	a hook test in `tests/component/hooks/`
A user-visible flow across more than one page	an end-to-end spec in `tests/e2e/`
Presentation only (styling, copy, layout, a `components/ui/` wrapper)	nothing

Always write a test for a bug fix, at the layer where the bug lived. The test must fail before the fix and pass after it. If it passes before the fix, it is testing the wrong thing.

For an API route, three cases are the minimum: an unauthenticated caller, a caller who is signed in but not authorized, and the happy path. Assert the database row, not only the status code: a refused DELETE has to leave the row present.

Two ways a test can be worthless

Both have been found in this repo, so they are worth naming.

A test that cannot fail. Before you finish, name the specific mutation of the production code your test would catch. If you cannot name one, delete the test. When it matters, prove it: break the code on purpose, watch the test go red, then revert.
A test whose input comes from the code under test. Iterating the same constant the function looks up means deleting an entry from that constant also deletes its own test case. Write expected values by hand as literals.

Repo-specific conventions

Use auth() from @/lib/auth for server-side session reads.
Use checkProjectAccess() / checkWorkspaceAccess() for authorization instead of ad-hoc role checks.
For API responses, use successResponse / apiErrors from @/lib/api-response.
Keep API and UI imports on @/ aliases when available.
In Prisma raw SQL, use $executeRaw for statements that return no rows (e.g. pg_advisory_xact_lock). Using $queryRaw on void-returning functions causes a Prisma deserialization error (Failed to deserialize column of type 'void').

Important locations

Custom SQL managed by Prisma migrations: prisma/migrations/*/migration.sql.
Shared API response helpers: lib/api-response.ts.
Auth + access-control helpers: lib/auth.ts.

Change safety rules

Prefer backward-compatible API changes unless explicitly asked to break contracts.
For multi-step DB writes, use Prisma transactions.

4.6 KiB Raw Blame History