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.

tests/factories/approval.ts

@@ -0,0 +1,44 @@
+import {
+  ApprovalDecisionStatus,
+  ApprovalRequestStatus,
+  type ApprovalDecision,
+  type ApprovalRequest,
+} from '@prisma/client';
+import { db } from '@/lib/db';
+import { nextSeq } from './seq';
+
+export interface CreateApprovalRequestInput {
+  versionId: string;
+  requestedById: string;
+  /** Users who get a PENDING decision row, i.e. the ones allowed to decide. */
+  approverIds?: string[];
+  message?: string | null;
+  status?: ApprovalRequestStatus;
+  resolvedAt?: Date | null;
+  canceledAt?: Date | null;
+  canceledById?: string | null;
+}
+
+export async function createApprovalRequest(
+  input: CreateApprovalRequestInput
+): Promise<ApprovalRequest & { decisions: ApprovalDecision[] }> {
+  const seq = nextSeq();
+  return db.approvalRequest.create({
+    data: {
+      versionId: input.versionId,
+      requestedById: input.requestedById,
+      message: input.message === undefined ? `Please review, round ${seq}` : input.message,
+      status: input.status ?? ApprovalRequestStatus.PENDING,
+      resolvedAt: input.resolvedAt ?? null,
+      canceledAt: input.canceledAt ?? null,
+      canceledById: input.canceledById ?? null,
+      decisions: {
+        create: (input.approverIds ?? []).map((approverId) => ({
+          approverId,
+          status: ApprovalDecisionStatus.PENDING,
+        })),
+      },
+    },
+    include: { decisions: true },
+  });
+}

tests/factories/comment.ts

@@ -0,0 +1,46 @@
+import type { Comment } from '@prisma/client';
+import { db } from '@/lib/db';
+import { nextSeq } from './seq';
+
+export interface CreateCommentInput {
+  versionId: string;
+  authorId?: string | null;
+  guestName?: string | null;
+  guestEmail?: string | null;
+  guestIdentityId?: string | null;
+  content?: string | null;
+  timestamp?: number;
+  timestampEnd?: number | null;
+  parentId?: string | null;
+  tagId?: string | null;
+  annotationData?: string | null;
+  imageUrl?: string | null;
+  voiceUrl?: string | null;
+  voiceDuration?: number | null;
+  isResolved?: boolean;
+  resolvedAt?: Date | null;
+}
+
+export async function createComment(input: CreateCommentInput): Promise<Comment> {
+  const seq = nextSeq();
+  return db.comment.create({
+    data: {
+      versionId: input.versionId,
+      authorId: input.authorId ?? null,
+      guestName: input.guestName ?? null,
+      guestEmail: input.guestEmail ?? null,
+      guestIdentityId: input.guestIdentityId ?? null,
+      content: input.content === undefined ? `Comment ${seq}` : input.content,
+      timestamp: input.timestamp ?? 10,
+      timestampEnd: input.timestampEnd ?? null,
+      parentId: input.parentId ?? null,
+      tagId: input.tagId ?? null,
+      annotationData: input.annotationData ?? null,
+      imageUrl: input.imageUrl ?? null,
+      voiceUrl: input.voiceUrl ?? null,
+      voiceDuration: input.voiceDuration ?? null,
+      isResolved: input.isResolved ?? false,
+      resolvedAt: input.resolvedAt ?? null,
+    },
+  });
+}

tests/factories/index.ts

@@ -0,0 +1,42 @@
+// Test-database row builders. Every value that must be unique comes from the
+// module-level counter in ./seq.ts, never from a random source.
+//
+// All of them insert through `@/lib/db`, so a test file that imports this
+// transitively imports the Prisma singleton and therefore depends on
+// tests/setup/api.ts having loaded .env.test first. That is arranged by the
+// `api` project's setupFiles.
+
+export { nextSeq, uniqueName } from './seq';
+
+export { createUser, createExpiredUser, createSubscribedUser } from './user';
+export type { CreateUserInput } from './user';
+
+export { createWorkspace, addWorkspaceMember, createInvitation } from './workspace';
+export type {
+  CreateWorkspaceInput,
+  AddWorkspaceMemberInput,
+  CreateInvitationInput,
+} from './workspace';
+
+export { createProject, addProjectMember, createCommentTag } from './project';
+export type { CreateProjectInput, AddProjectMemberInput, CreateCommentTagInput } from './project';
+
+export { createVideo, createVersion, createVideoAsset, createUploadReservation } from './video';
+export type {
+  CreateVideoInput,
+  CreateVersionInput,
+  CreateVideoAssetInput,
+  CreateUploadReservationInput,
+} from './video';
+
+export { createComment } from './comment';
+export type { CreateCommentInput } from './comment';
+
+export { createShareLink } from './share';
+export type { CreateShareLinkInput } from './share';
+
+export { createApprovalRequest } from './approval';
+export type { CreateApprovalRequestInput } from './approval';
+
+export { seedProject, seedVersion } from './scenario';
+export type { ProjectScenario, VersionScenario } from './scenario';

tests/factories/project.ts

@@ -0,0 +1,69 @@
+import {
+  ProjectMemberRole,
+  ProjectVisibility,
+  type CommentTag,
+  type Project,
+  type ProjectMember,
+} from '@prisma/client';
+import { db } from '@/lib/db';
+import { nextSeq } from './seq';
+
+export interface CreateProjectInput {
+  ownerId: string;
+  workspaceId: string;
+  name?: string;
+  slug?: string;
+  description?: string | null;
+  visibility?: ProjectVisibility;
+  allowDownloads?: boolean;
+}
+
+export async function createProject(input: CreateProjectInput): Promise<Project> {
+  const seq = nextSeq();
+  return db.project.create({
+    data: {
+      name: input.name ?? `Project ${seq}`,
+      slug: input.slug ?? `project-${seq}`,
+      description: input.description ?? null,
+      visibility: input.visibility ?? ProjectVisibility.PRIVATE,
+      allowDownloads: input.allowDownloads ?? false,
+      ownerId: input.ownerId,
+      workspaceId: input.workspaceId,
+    },
+  });
+}
+
+export interface AddProjectMemberInput {
+  projectId: string;
+  userId: string;
+  role?: ProjectMemberRole;
+}
+
+export async function addProjectMember(input: AddProjectMemberInput): Promise<ProjectMember> {
+  return db.projectMember.create({
+    data: {
+      projectId: input.projectId,
+      userId: input.userId,
+      role: input.role ?? ProjectMemberRole.COMMENTATOR,
+    },
+  });
+}
+
+export interface CreateCommentTagInput {
+  projectId: string;
+  name?: string;
+  color?: string;
+  position?: number;
+}
+
+export async function createCommentTag(input: CreateCommentTagInput): Promise<CommentTag> {
+  const seq = nextSeq();
+  return db.commentTag.create({
+    data: {
+      projectId: input.projectId,
+      name: input.name ?? `Tag ${seq}`,
+      color: input.color ?? '#3B82F6',
+      position: input.position ?? 0,
+    },
+  });
+}

tests/factories/scenario.ts

@@ -0,0 +1,73 @@
+// Two composite builders for the arrangement almost every api test needs: an
+// owner with billing access, their workspace, a project inside it, and
+// optionally a video with one version.
+//
+// These are a shorthand, not shared state. Each call inserts fresh rows, and
+// resetDb() wipes them after the test, so nothing here creates an ordering
+// dependency between tests.
+
+import type {
+  Project,
+  ProjectVisibility,
+  User,
+  Video,
+  VideoVersion,
+  Workspace,
+} from '@prisma/client';
+import { createProject } from './project';
+import { createUser, type CreateUserInput } from './user';
+import { createVersion, createVideo } from './video';
+import { createWorkspace } from './workspace';
+
+export interface ProjectScenario {
+  owner: User;
+  workspace: Workspace;
+  project: Project;
+}
+
+export interface SeedProjectInput {
+  visibility?: ProjectVisibility;
+  allowDownloads?: boolean;
+  projectName?: string;
+  owner?: CreateUserInput;
+  /** Reuse an existing user as the workspace and project owner. */
+  ownerUser?: User;
+}
+
+export async function seedProject(input: SeedProjectInput = {}): Promise<ProjectScenario> {
+  const owner = input.ownerUser ?? (await createUser(input.owner));
+  const workspace = await createWorkspace({ ownerId: owner.id });
+  const project = await createProject({
+    ownerId: owner.id,
+    workspaceId: workspace.id,
+    visibility: input.visibility,
+    allowDownloads: input.allowDownloads,
+    name: input.projectName,
+  });
+
+  return { owner, workspace, project };
+}
+
+export interface VersionScenario extends ProjectScenario {
+  video: Video;
+  version: VideoVersion;
+}
+
+export interface SeedVersionInput extends SeedProjectInput {
+  providerId?: string;
+  sizeBytes?: bigint;
+  duration?: number | null;
+}
+
+export async function seedVersion(input: SeedVersionInput = {}): Promise<VersionScenario> {
+  const scenario = await seedProject(input);
+  const video = await createVideo({ projectId: scenario.project.id });
+  const version = await createVersion({
+    videoParentId: video.id,
+    providerId: input.providerId,
+    sizeBytes: input.sizeBytes,
+    duration: input.duration,
+  });
+
+  return { ...scenario, video, version };
+}

tests/factories/seq.ts

@@ -0,0 +1,19 @@
+// A monotonic counter, shared by every factory in this directory.
+//
+// Deliberately not random and deliberately not faker: a failing test must
+// reproduce byte for byte from its own source, and a randomly generated slug
+// that happens to collide once a week is worse than no test. The counter is
+// module scoped, so it restarts at 1 for each test file, which is enough because
+// resetDb() empties the database between tests.
+
+let counter = 0;
+
+export function nextSeq(): number {
+  counter += 1;
+  return counter;
+}
+
+/** e.g. `uniqueName('project')` -> `'project-1'`. */
+export function uniqueName(prefix: string): string {
+  return `${prefix}-${nextSeq()}`;
+}

tests/factories/share.ts

@@ -0,0 +1,38 @@
+import bcrypt from 'bcryptjs';
+import { SharePermission, type ShareLink } from '@prisma/client';
+import { db } from '@/lib/db';
+import { nextSeq } from './seq';
+
+// Matches tests/factories/user.ts: low cost, because bcrypt.compare() works
+// against any cost factor and the production one is pure test latency.
+const TEST_BCRYPT_ROUNDS = 4;
+
+export interface CreateShareLinkInput {
+  projectId: string;
+  /** Null (the default) is a project-wide link; a video id scopes it. */
+  videoId?: string | null;
+  permission?: SharePermission;
+  token?: string;
+  /** Plain text. Hashed into passwordHash, so the row never holds it. */
+  password?: string;
+  expiresAt?: Date | null;
+  allowGuests?: boolean;
+  allowDownloads?: boolean;
+}
+
+export async function createShareLink(input: CreateShareLinkInput): Promise<ShareLink> {
+  const seq = nextSeq();
+  return db.shareLink.create({
+    data: {
+      projectId: input.projectId,
+      videoId: input.videoId ?? null,
+      permission: input.permission ?? SharePermission.VIEW,
+      token: input.token ?? `share-token-${seq}`,
+      passwordHash:
+        input.password === undefined ? null : await bcrypt.hash(input.password, TEST_BCRYPT_ROUNDS),
+      expiresAt: input.expiresAt ?? null,
+      allowGuests: input.allowGuests ?? true,
+      allowDownloads: input.allowDownloads ?? false,
+    },
+  });
+}

tests/factories/user.ts

@@ -0,0 +1,95 @@
+import bcrypt from 'bcryptjs';
+import { BillingSubscriptionStatus, type Prisma, type User } from '@prisma/client';
+import { db } from '@/lib/db';
+import { nextSeq } from './seq';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+// Cheap on purpose. bcrypt at the production cost factor takes ~100ms, which is
+// dead time repeated across every test that needs a user with a password.
+const TEST_BCRYPT_ROUNDS = 4;
+
+export interface CreateUserInput {
+  name?: string;
+  email?: string;
+  /** Plain text. Hashed before insert, so the row never holds it. */
+  password?: string;
+  emailVerified?: Date | null;
+  onboardingCompletedAt?: Date | null;
+  trialEndsAt?: Date | null;
+  billingTrialConsumedAt?: Date | null;
+  subscriptionStatus?: BillingSubscriptionStatus;
+  stripeCustomerId?: string | null;
+  stripeSubscriptionId?: string | null;
+  stripePriceId?: string | null;
+  stripeCurrentPeriodEnd?: Date | null;
+  stripeCancelAtPeriodEnd?: boolean;
+  stripeCancelAt?: Date | null;
+  billingAccessEndedAt?: Date | null;
+}
+
+/**
+ * A user with billing access, via a trial that ends in seven days.
+ *
+ * That default matters: OPENFRAME_ENABLE_STRIPE is true in .env.test, so
+ * hasBillingAccess() is armed and a user without any of trialEndsAt /
+ * stripeCurrentPeriodEnd / an active status is locked out of their own
+ * workspaces. Pass `trialEndsAt` in the past (or use createExpiredUser) to test
+ * that gate.
+ */
+export async function createUser(input: CreateUserInput = {}): Promise<User> {
+  const seq = nextSeq();
+
+  const data: Prisma.UserCreateInput = {
+    name: input.name ?? `User ${seq}`,
+    email: input.email ?? `user-${seq}@example.com`,
+    emailVerified: input.emailVerified === undefined ? new Date() : input.emailVerified,
+    onboardingCompletedAt:
+      input.onboardingCompletedAt === undefined ? new Date() : input.onboardingCompletedAt,
+    trialEndsAt:
+      input.trialEndsAt === undefined ? new Date(Date.now() + 7 * DAY_MS) : input.trialEndsAt,
+    billingTrialConsumedAt: input.billingTrialConsumedAt ?? null,
+    subscriptionStatus: input.subscriptionStatus ?? BillingSubscriptionStatus.FREE,
+    stripeCustomerId: input.stripeCustomerId ?? null,
+    stripeSubscriptionId: input.stripeSubscriptionId ?? null,
+    stripePriceId: input.stripePriceId ?? null,
+    stripeCurrentPeriodEnd: input.stripeCurrentPeriodEnd ?? null,
+    stripeCancelAtPeriodEnd: input.stripeCancelAtPeriodEnd ?? false,
+    stripeCancelAt: input.stripeCancelAt ?? null,
+    billingAccessEndedAt: input.billingAccessEndedAt ?? null,
+  };
+
+  if (input.password !== undefined) {
+    data.password = await bcrypt.hash(input.password, TEST_BCRYPT_ROUNDS);
+  }
+
+  return db.user.create({ data });
+}
+
+/**
+ * A user whose trial ran out 30 days ago and who has no subscription, so
+ * hasBillingAccess() is false and buildBillingAccessWhereInput() excludes them.
+ */
+export function createExpiredUser(input: CreateUserInput = {}): Promise<User> {
+  const trialEndsAt = new Date(Date.now() - 30 * DAY_MS);
+  return createUser({
+    ...input,
+    trialEndsAt,
+    billingTrialConsumedAt: input.billingTrialConsumedAt ?? trialEndsAt,
+    billingAccessEndedAt: input.billingAccessEndedAt ?? trialEndsAt,
+  });
+}
+
+/** A user on a paid, active subscription rather than a trial. */
+export function createSubscribedUser(input: CreateUserInput = {}): Promise<User> {
+  const seq = nextSeq();
+  return createUser({
+    ...input,
+    subscriptionStatus: input.subscriptionStatus ?? BillingSubscriptionStatus.ACTIVE,
+    trialEndsAt: input.trialEndsAt ?? null,
+    stripeCustomerId: input.stripeCustomerId ?? `cus_test_${seq}`,
+    stripeSubscriptionId: input.stripeSubscriptionId ?? `sub_test_${seq}`,
+    stripePriceId: input.stripePriceId ?? process.env.STRIPE_PRICE_ID ?? 'price_test',
+    stripeCurrentPeriodEnd: input.stripeCurrentPeriodEnd ?? new Date(Date.now() + 30 * DAY_MS),
+  });
+}

tests/factories/video.ts

@@ -0,0 +1,120 @@
+import {
+  VideoAssetKind,
+  VideoAssetProvider,
+  type UploadReservation,
+  type Video,
+  type VideoAsset,
+  type VideoVersion,
+} from '@prisma/client';
+import { db } from '@/lib/db';
+import { nextSeq } from './seq';
+
+export interface CreateVideoInput {
+  projectId: string;
+  title?: string;
+  description?: string | null;
+  position?: number;
+}
+
+export async function createVideo(input: CreateVideoInput): Promise<Video> {
+  const seq = nextSeq();
+  return db.video.create({
+    data: {
+      projectId: input.projectId,
+      title: input.title ?? `Video ${seq}`,
+      description: input.description ?? null,
+      position: input.position ?? 0,
+    },
+  });
+}
+
+export interface CreateVersionInput {
+  /** The parent Video row. Maps to VideoVersion.videoParentId. */
+  videoParentId: string;
+  versionNumber?: number;
+  versionLabel?: string | null;
+  /** 'youtube' | 'r2' | 'bunny' | ... Maps to VideoVersion.providerId. */
+  providerId?: string;
+  /** The id the provider knows the media by. Maps to VideoVersion.videoId. */
+  providerVideoId?: string;
+  originalUrl?: string;
+  title?: string | null;
+  thumbnailUrl?: string | null;
+  duration?: number | null;
+  sizeBytes?: bigint;
+  isActive?: boolean;
+}
+
+export async function createVersion(input: CreateVersionInput): Promise<VideoVersion> {
+  const seq = nextSeq();
+  const providerVideoId = input.providerVideoId ?? `provider-video-${seq}`;
+  return db.videoVersion.create({
+    data: {
+      videoParentId: input.videoParentId,
+      versionNumber: input.versionNumber ?? 1,
+      versionLabel: input.versionLabel ?? null,
+      providerId: input.providerId ?? 'youtube',
+      videoId: providerVideoId,
+      originalUrl: input.originalUrl ?? `https://www.youtube.com/watch?v=${providerVideoId}`,
+      title: input.title ?? `Version ${seq}`,
+      thumbnailUrl: input.thumbnailUrl ?? null,
+      duration: input.duration ?? 120,
+      sizeBytes: input.sizeBytes ?? BigInt(0),
+      isActive: input.isActive ?? true,
+    },
+  });
+}
+
+export interface CreateVideoAssetInput {
+  videoId: string;
+  billedUserId: string;
+  kind?: VideoAssetKind;
+  provider?: VideoAssetProvider;
+  displayName?: string;
+  sourceUrl?: string;
+  providerVideoId?: string | null;
+  thumbnailUrl?: string | null;
+  uploadedByUserId?: string | null;
+  uploadedByGuestIdentityId?: string | null;
+  uploadedByGuestName?: string | null;
+  sizeBytes?: bigint;
+}
+
+export async function createVideoAsset(input: CreateVideoAssetInput): Promise<VideoAsset> {
+  const seq = nextSeq();
+  return db.videoAsset.create({
+    data: {
+      videoId: input.videoId,
+      billedUserId: input.billedUserId,
+      kind: input.kind ?? VideoAssetKind.IMAGE,
+      provider: input.provider ?? VideoAssetProvider.R2_IMAGE,
+      displayName: input.displayName ?? `asset-${seq}.png`,
+      sourceUrl: input.sourceUrl ?? `/api/upload/image/asset-${seq}.png`,
+      providerVideoId: input.providerVideoId ?? null,
+      thumbnailUrl: input.thumbnailUrl ?? null,
+      uploadedByUserId: input.uploadedByUserId ?? null,
+      uploadedByGuestIdentityId: input.uploadedByGuestIdentityId ?? null,
+      uploadedByGuestName: input.uploadedByGuestName ?? null,
+      sizeBytes: input.sizeBytes ?? BigInt(0),
+    },
+  });
+}
+
+export interface CreateUploadReservationInput {
+  billedUserId: string;
+  sizeBytes: bigint;
+  /** Milliseconds from now. Negative values produce an already-expired row. */
+  expiresInMs?: number;
+}
+
+export async function createUploadReservation(
+  input: CreateUploadReservationInput
+): Promise<UploadReservation> {
+  return db.uploadReservation.create({
+    data: {
+      billedUserId: input.billedUserId,
+      sizeBytes: input.sizeBytes,
+      expiresAt: new Date(Date.now() + (input.expiresInMs ?? 30 * 60 * 1000)),
+    },
+  });
+}

tests/factories/workspace.ts

@@ -0,0 +1,79 @@
+import {
+  InvitationRole,
+  InvitationScope,
+  InvitationStatus,
+  WorkspaceMemberRole,
+  type Invitation,
+  type Workspace,
+  type WorkspaceMember,
+} from '@prisma/client';
+import { db } from '@/lib/db';
+import { nextSeq } from './seq';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export interface CreateWorkspaceInput {
+  ownerId: string;
+  name?: string;
+  slug?: string;
+  description?: string | null;
+}
+
+export async function createWorkspace(input: CreateWorkspaceInput): Promise<Workspace> {
+  const seq = nextSeq();
+  return db.workspace.create({
+    data: {
+      name: input.name ?? `Workspace ${seq}`,
+      slug: input.slug ?? `workspace-${seq}`,
+      description: input.description ?? null,
+      ownerId: input.ownerId,
+    },
+  });
+}
+
+export interface AddWorkspaceMemberInput {
+  workspaceId: string;
+  userId: string;
+  role?: WorkspaceMemberRole;
+}
+
+export async function addWorkspaceMember(input: AddWorkspaceMemberInput): Promise<WorkspaceMember> {
+  return db.workspaceMember.create({
+    data: {
+      workspaceId: input.workspaceId,
+      userId: input.userId,
+      role: input.role ?? WorkspaceMemberRole.COMMENTATOR,
+    },
+  });
+}
+
+export interface CreateInvitationInput {
+  invitedById: string;
+  email?: string;
+  scope: InvitationScope;
+  role?: InvitationRole;
+  status?: InvitationStatus;
+  workspaceId?: string | null;
+  projectId?: string | null;
+  token?: string;
+  expiresAt?: Date;
+  acceptedAt?: Date | null;
+}
+
+export async function createInvitation(input: CreateInvitationInput): Promise<Invitation> {
+  const seq = nextSeq();
+  return db.invitation.create({
+    data: {
+      token: input.token ?? `invitation-token-${seq}`,
+      email: input.email ?? `invitee-${seq}@example.com`,
+      scope: input.scope,
+      role: input.role ?? InvitationRole.COMMENTATOR,
+      status: input.status ?? InvitationStatus.PENDING,
+      workspaceId: input.workspaceId ?? null,
+      projectId: input.projectId ?? null,
+      invitedById: input.invitedById,
+      expiresAt: input.expiresAt ?? new Date(Date.now() + 7 * DAY_MS),
+      acceptedAt: input.acceptedAt ?? null,
+    },
+  });
+}