mirror of
https://github.com/yusufipk/OpenFrame.git
synced 2026-09-11 09:36:08 +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.
117 lines
3.8 KiB
Markdown
117 lines
3.8 KiB
Markdown
# Contributing to OpenFrame
|
|
|
|
Thanks for taking the time to contribute.
|
|
This guide covers setup, PR expectations, and required conventions.
|
|
|
|
## Local setup
|
|
|
|
1. Install dependencies.
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
2. Copy environment variables.
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
3. Generate Prisma client.
|
|
|
|
```bash
|
|
bun run db:generate
|
|
```
|
|
|
|
4. Run validation.
|
|
|
|
```bash
|
|
bun run check
|
|
```
|
|
|
|
## Running the tests
|
|
|
|
The testing stack, layout, and conventions live in [TESTING.md](TESTING.md). Read it before adding a test, and see the "When a change needs a test" table in [AGENTS.md](AGENTS.md) for which layer your change belongs in. A bug fix always needs a test that fails before the fix.
|
|
|
|
| Command | Runs | Needs the test database |
|
|
| ------------------ | -------------------------------------------------- | ----------------------- |
|
|
| `bun run test` | unit and component suites | no |
|
|
| `bun run test:api` | API integration suites | yes |
|
|
| `bun run test:e2e` | Playwright end-to-end specs | yes |
|
|
| `bun run verify` | `bun run check` plus the unit and component suites | no |
|
|
|
|
The test database is a disposable Postgres defined in `docker-compose.test.yml`, on port `55432` so it cannot collide with your dev stack.
|
|
|
|
```bash
|
|
bun run test:db:up
|
|
bun run test:api
|
|
bun run test:db:down
|
|
```
|
|
|
|
`scripts/test.sh <unit|api|e2e|all>` does all of that in one command. It runs each suite inside a container, so no package manager runs on your host, and it starts the test database first when the suite needs one.
|
|
|
|
```bash
|
|
./scripts/test.sh unit
|
|
./scripts/test.sh all
|
|
```
|
|
|
|
The `pre-push` hook runs `bun run verify`, so lint, format, typecheck, and the unit and component suites have to pass before a push leaves your machine. `bun run test:api` is deliberately not in the hook, because it needs the database container. Run it yourself when you change an API route.
|
|
|
|
## Contribution workflow
|
|
|
|
1. Fork and create a branch from `master`.
|
|
2. Keep changes focused on one logical concern.
|
|
3. Follow repository conventions in this file.
|
|
4. Run required checks locally.
|
|
5. Open a PR with a clear summary and checklist.
|
|
|
|
## Branch naming
|
|
|
|
- `feature/<short-topic>`
|
|
- `fix/<short-topic>`
|
|
- `docs/<short-topic>`
|
|
- `refactor/<short-topic>`
|
|
- `chore/<short-topic>`
|
|
|
|
## Commit and PR title standard
|
|
|
|
Use Conventional Commits with this pattern:
|
|
|
|
```text
|
|
type(scope): short summary
|
|
```
|
|
|
|
## Required checks before opening a PR
|
|
|
|
- Run `bun run check`.
|
|
- Run `bun run verify`, or let the `pre-push` hook run it for you.
|
|
- If you changed an API route, also run `bun run test:api` with the test database up.
|
|
- If `prisma/schema.prisma` changed, run `bun run db:generate`.
|
|
- Ensure no unrelated file changes are included.
|
|
- Ensure no secrets or private keys are committed.
|
|
- Update docs when behavior changes.
|
|
|
|
## Project conventions (must follow)
|
|
|
|
- Use Bun commands only.
|
|
- Server-side session reads must use `auth()` from [lib/auth.ts](lib/auth.ts).
|
|
- Access control should use `checkProjectAccess()` / `checkWorkspaceAccess()`.
|
|
- API responses should use `successResponse` / `apiErrors` from [lib/api-response.ts](lib/api-response.ts).
|
|
- In App Router dynamic routes, keep `params` typed as `Promise<...>` and use `await params`.
|
|
- For multi-step DB writes, use Prisma transactions.
|
|
- Prefer backward-compatible API changes unless a breaking change is explicitly requested.
|
|
- Prefer `@/` imports when available.
|
|
|
|
## Security issues
|
|
|
|
Do not open public issues for vulnerabilities.
|
|
Follow [SECURITY.md](SECURITY.md).
|
|
|
|
## Code of conduct
|
|
|
|
Follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
|
|
|
|
## Need help?
|
|
|
|
If you are unsure where to start, open an issue with context and a proposed approach.
|