The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.
TypeScript clickhousemysqlnextjsopen-sourceplanetscaleprismatailwindcsstinybirdtypescriptupstashvercel
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.mdnew file mode 100644index 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.mdindex 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```shpnpm --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 testsMake 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.tssimilarity index 99%rename from apps/web/playwright/api/customers-pagination.spec.tsrename to apps/web/playwright/api/customers/customers-pagination.spec.tsindex 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.tssimilarity index 97%rename from apps/web/playwright/api/customers.spec.tsrename to apps/web/playwright/api/customers/customers.spec.tsindex 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.tssimilarity index 96%rename from apps/web/playwright/api/folders.spec.tsrename to apps/web/playwright/api/folders/folders.spec.tsindex 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.tssimilarity index 97%rename from apps/web/playwright/api/tags.spec.tsrename to apps/web/playwright/api/tags/tags.spec.tsindex 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.tssimilarity index 94%rename from apps/web/playwright/api/workspaces.spec.tsrename to apps/web/playwright/api/workspaces/workspaces.spec.tsindex 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",