mirror of
https://github.com/yusufipk/OpenFrame.git
synced 2026-09-11 17:46:06 +00:00
yusufipk
1d099c68f2
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.
77 lines
4.6 KiB
Markdown
77 lines
4.6 KiB
Markdown
# 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.
|
|
|
|
1. **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.
|
|
2. **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.
|