Skip to content

armgit / dub

Public Imported from GitHub
0

The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.

Organize Playwright API specs by resource and add a writing skill.

Kiran K90fb865b3263
diff --git a/.agents/skills/playwright-api-tests/SKILL.md b/.agents/skills/playwright-api-tests/SKILL.md
new file mode 100644
index 0000000000..0eccc69d5d
--- /dev/null
+++ b/.agents/skills/playwright-api-tests/SKILL.md
@@ -0,0 +1,153 @@
+---
+name: playwright-api-tests
+description: Add or extend Playwright HTTP API specs under apps/web/playwright/api using the shared api/workspace fixtures and Bearer auth from globalSetup. Use when writing Playwright API tests, e2e API specs, or testing /api routes with the api project (not Vitest under apps/web/tests, not browser UI e2e).
+---
+
+# Playwright API tests
+
+HTTP API coverage lives in `apps/web/playwright/api/<resource>/*.spec.ts`. Auth is seeded once by Playwright `globalSetup` (`apps/web/global-setup.ts` → `setup-test-workspace.ts`) into `playwright/.auth/api.json`. Specs use the custom `test` from `../fixtures` — not `@playwright/test` directly for `test`.
+
+Do **not** put these under `apps/web/tests/` (Vitest) or under `playwright/partners` / `playwright/workspaces` (browser e2e).
+
+## Before writing
+
+1. Find the route handler and response shape (Zod schemas under `apps/web/lib/zod`, types under `@/lib/types` or Prisma).
+2. Prefer mirroring an existing nearby resource folder: `tags/`, `folders/`, `customers/`, `workspaces/`.
+3. Confirm the endpoint is workspace-scoped Bearer API (most `/api/*` routes). The fixture already sends `Authorization: Bearer …`.
+
+## File layout
+
+```
+apps/web/playwright/api/
+├── fixtures.ts # api + workspace fixtures (reuse; don't duplicate)
+├── setup-test-workspace.ts # globalSetup seed only — extend only if auth/workspace setup must change
+└── <resource>/
+ ├── <resource>.spec.ts
+ └── <resource>-pagination.spec.ts # optional split for heavy pagination suites
+```
+
+One folder per resource. Name files `kebab-case.spec.ts` (`tags/tags.spec.ts`, `customers/customers-pagination.spec.ts`).
+
+## Spec template
+
+```ts
+import { expect } from "@playwright/test";
+import { randomName } from "../../utils";
+import { test, type ApiClient } from "../fixtures";
+
+test.describe.configure({
+ mode: "parallel",
+});
+
+async function createThing(
+ api: ApiClient,
+ overrides: Record<string, unknown> = {},
+) {
+ return api.post<YourType>("/api/things", {
+ name: randomName("thing"),
+ ...overrides,
+ });
+}
+
+async function deleteThing(api: ApiClient, id: string | undefined) {
+ if (!id) return;
+ await api.delete(`/api/things/${id}`);
+}
+
+test("POST /things", async ({ api }) => {
+ let id: string | undefined;
+
+ try {
+ const body = { name: randomName("thing") };
+ const { status, data } = await api.post<YourType>("/api/things", body);
+ id = data.id;
+
+ expect(status).toEqual(201);
+ expect(data).toStrictEqual({
+ id: expect.any(String),
+ ...body,
+ // stable nulls / defaults from the API
+ });
+ } finally {
+ await deleteThing(api, id);
+ }
+});
+```
+
+## Required conventions
+
+| Rule | Detail |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Import `test` from `../fixtures` | Provides `api` and `workspace` |
+| `test.describe.configure({ mode: "parallel" })` | At top of every API spec file |
+| Cleanup in `finally` | Create → assert → always delete created rows |
+| Unique names/ids | Use `randomName` / `randomCustomer` from `../../utils` — never fixed colliding names across parallel workers |
+| Assert status + body | Prefer `toStrictEqual` / `toEqual` on full shapes; use `expect.any(String)` for ids/timestamps |
+| Error responses | Match `{ error: { code, message, doc_url } }` exactly |
+| Typed generics | `api.get<T>`, `api.post<T>`, etc. |
+| Workspace fixture | Use `{ workspace }` for id/slug from seed (`workspaces/workspaces.spec.ts`) — do not hardcode slug |
+
+### Fixtures (`api` / `workspace`)
+
+- `api.get/post/patch/delete(url, data?)` → `{ status, data }` (JSON parsed).
+- Paths are app-relative (`/api/...`); `baseURL` is `http://localhost:8888`.
+- `workspace.id` / `workspace.slug` come from `.auth/api.json`.
+
+### Helpers
+
+- Shared randomizers / sort assertions: `apps/web/playwright/utils.ts`.
+- Local `createX` / `deleteX` helpers in the spec file when the same setup repeats.
+- Prisma direct seed is allowed for bulk fixtures (see `customers/customers-pagination.spec.ts`); still clean up in `finally` / after hooks.
+
+### Error / table-driven cases
+
+```ts
+const errorCases = [
+ {
+ name: "POST /things – missing name",
+ body: {},
+ expected: {
+ status: 422,
+ data: {
+ error: {
+ code: "unprocessable_entity",
+ message: "…",
+ doc_url:
+ "https://dub.co/docs/api-reference/errors#unprocessable-entity",
+ },
+ },
+ },
+ },
+];
+
+for (const { name, body, expected } of errorCases) {
+ test(name, async ({ api }) => {
+ expect(await api.post("/api/things", body)).toEqual(expected);
+ });
+}
+```
+
+Optional: validate richer payloads with Zod (`.parse(...)`) like `workspaces/workspaces.spec.ts` / enriched customer fields.
+
+## Do not
+
+- Call `setupTestWorkspace` from specs (only `globalSetup`).
+- Import browser `page` / storage-state auth for API specs.
+- Commit secrets or change the fixed Playwright token unless intentionally rotating local/CI test auth.
+- Skip cleanup (parallel API project will leak / flake).
+- Run `pnpm build` after adding tests.
+
+## Run
+
+Dev server on port 8888 (local), then:
+
+```sh
+pnpm --filter web test:e2e --project=api
+pnpm --filter web test:e2e --project=api playwright/api/tags/tags.spec.ts
+pnpm --filter web test:e2e --project=api playwright/api/tags/tags.spec.ts -g "POST /tags"
+```
+
+`-g` / `--grep` matches the test title (regex). Combine with a file path to narrow further.
+In CI, `playwright.config.ts` starts `pnpm start -p 8888` via `webServer`.
+
+More context: `apps/web/playwright/README.md` (API section).
diff --git a/apps/web/playwright/README.md b/apps/web/playwright/README.md
index c8ce929d3f..a4fbe6ac15 100644
--- a/apps/web/playwright/README.md
+++ b/apps/web/playwright/README.md
@@ -36,8 +36,12 @@ API specs under `playwright/api` use a Bearer token. `globalSetup` upserts a ded
```sh
pnpm --filter web test:e2e --project=api
+pnpm --filter web test:e2e --project=api playwright/api/tags/tags.spec.ts
+pnpm --filter web test:e2e --project=api playwright/api/tags/tags.spec.ts -g "POST /tags"
```
+`-g` / `--grep` matches the test title (regex). Combine with a file path to narrow further.
+
## Running tests
Make sure the dev server is running first (`pnpm dev`), then:
diff --git a/apps/web/playwright/api/customers-pagination.spec.ts b/apps/web/playwright/api/customers/customers-pagination.spec.ts
similarity index 99%
rename from apps/web/playwright/api/customers-pagination.spec.ts
rename to apps/web/playwright/api/customers/customers-pagination.spec.ts
index 12b5e0115a..9792aad5a8 100644
--- a/apps/web/playwright/api/customers-pagination.spec.ts
+++ b/apps/web/playwright/api/customers/customers-pagination.spec.ts
@@ -7,8 +7,8 @@ import {
expectNoOverlap,
expectSortedByCreatedAt,
expectSortedById,
-} from "../utils";
-import { test } from "./fixtures";
+} from "../../utils";
+import { test } from "../fixtures";
const PAGE_SIZE = 5;
const SEED_COUNT = 25;
diff --git a/apps/web/playwright/api/customers.spec.ts b/apps/web/playwright/api/customers/customers.spec.ts
similarity index 97%
rename from apps/web/playwright/api/customers.spec.ts
rename to apps/web/playwright/api/customers/customers.spec.ts
index fdbd5ce66d..ed492a90a8 100644
--- a/apps/web/playwright/api/customers.spec.ts
+++ b/apps/web/playwright/api/customers/customers.spec.ts
@@ -1,8 +1,8 @@
import type { Customer } from "@/lib/types";
import { CustomerEnrichedSchema } from "@/lib/zod/schemas/customers";
import { expect } from "@playwright/test";
-import { randomCustomer } from "../utils";
-import { test, type ApiClient } from "./fixtures";
+import { randomCustomer } from "../../utils";
+import { test, type ApiClient } from "../fixtures";
const expectedCustomerShape = {
id: expect.any(String),
diff --git a/apps/web/playwright/api/folders.spec.ts b/apps/web/playwright/api/folders/folders.spec.ts
similarity index 96%
rename from apps/web/playwright/api/folders.spec.ts
rename to apps/web/playwright/api/folders/folders.spec.ts
index 5567838328..ca1dcede7f 100644
--- a/apps/web/playwright/api/folders.spec.ts
+++ b/apps/web/playwright/api/folders/folders.spec.ts
@@ -1,7 +1,7 @@
import { expect } from "@playwright/test";
import type { Folder } from "@prisma/client";
-import { randomName } from "../utils";
-import { test, type ApiClient } from "./fixtures";
+import { randomName } from "../../utils";
+import { test, type ApiClient } from "../fixtures";
const expectedFolder = {
id: expect.any(String),
diff --git a/apps/web/playwright/api/tags.spec.ts b/apps/web/playwright/api/tags/tags.spec.ts
similarity index 97%
rename from apps/web/playwright/api/tags.spec.ts
rename to apps/web/playwright/api/tags/tags.spec.ts
index 05aebd2b04..7a51fe5adb 100644
--- a/apps/web/playwright/api/tags.spec.ts
+++ b/apps/web/playwright/api/tags/tags.spec.ts
@@ -1,7 +1,7 @@
import { expect } from "@playwright/test";
import type { Tag } from "@prisma/client";
-import { randomName } from "../utils";
-import { test } from "./fixtures";
+import { randomName } from "../../utils";
+import { test } from "../fixtures";
test.describe.configure({
mode: "parallel",
diff --git a/apps/web/playwright/api/workspaces.spec.ts b/apps/web/playwright/api/workspaces/workspaces.spec.ts
similarity index 94%
rename from apps/web/playwright/api/workspaces.spec.ts
rename to apps/web/playwright/api/workspaces/workspaces.spec.ts
index 969871dd8c..524c4d98ab 100644
--- a/apps/web/playwright/api/workspaces.spec.ts
+++ b/apps/web/playwright/api/workspaces/workspaces.spec.ts
@@ -2,8 +2,8 @@ import { WorkspaceSchema } from "@/lib/zod/schemas/workspaces";
import { expect } from "@playwright/test";
import type { Project } from "@prisma/client";
import * as z from "zod/v4";
-import { test } from "./fixtures";
-import { TEST_WORKSPACE } from "./setup-test-workspace";
+import { test } from "../fixtures";
+import { TEST_WORKSPACE } from "../setup-test-workspace";
test.describe.configure({
mode: "parallel",