You do not need a browser to verify that your Payload CMS access control, validation rules, and Admin Panel permissions actually work. Every capability the Admin UI exposes — who can see a collection, who can edit a field, what happens when a required field is missing — is backed by the REST API, and you can assert against all of it with plain fetch calls in milliseconds instead of minutes. This guide walks through a zero-dependency REST test client for Payload CMS v3, nine concrete testing use cases (including two REST surfaces most teams never touch: document-level access probing and bulk-operation safety), and a runnable node:test suite you can drop into a real project.
I built this after watching a Payload project's Playwright suite balloon past eight minutes just to check that editors couldn't delete other people's posts. The assertion had nothing to do with rendering — it was a permissions question, and permissions questions belong at the API layer, not the DOM.
When building and testing applications powered by Payload CMS, developers often assume that testing Admin Panel features requires driving a real headless browser (via Playwright, Cypress, or Puppeteer). Browser tests are valuable for visual regression and rich text canvas interactions, but using them for business logic, access rules, and form validation creates significant friction:
REST is not the only alternative to the browser, though. Payload also exposes a Local API — direct function calls (payload.find, payload.create) that run inside the same Node process as your app, skipping HTTP entirely. Each layer tests a different thing:
The Admin Panel itself decides what to render by calling the same REST (or GraphQL) endpoints your tests will call — most notably GET /api/access. Testing at this layer means you're testing exactly what governs the UI, not a proxy for it.
What You Can Test via REST
Diagram
2. Complete, Standalone REST Client
This zero-dependency HTTP client, built on native Node.js fetch and AbortSignal.timeout, provides everything needed to interact with Payload CMS programmatically.
Two details worth calling out, both drawn from how Payload actually authenticates requests, not assumptions:
The users API-Key <key> header format is collection-specific — the prefix must match the slug of whichever auth-enabled collection has useAPIKey: true, not always users. If your API key collection is called service-accounts, the header is Authorization: service-accounts API-Key <key>. Getting this prefix wrong is the single most common cause of a 403 that looks like a permissions bug but is really a header bug.
An earlier version of this client normalized every path to end with a trailing slash before hitting fetch. Don't do that — Payload's REST routes are exact matches (/api/posts, /api/posts/:id), and forcing a trailing slash on collection or document paths risks a 404 depending on how your framework's router handles it. Send paths exactly as documented.
3. Core Testing Use Cases
Use Case 1: Fast CRUD, Fixture Seeding & Deterministic Teardown
In test suites, you frequently need to create temporary collections (articles, categories, products), update them, verify their presence, and ensure they are reliably deleted after tests finish.
One of the most effective uses of REST testing is verifying that Payload's validation rules, custom validators, and required field constraints properly reject bad input with the right errors.
Negative tests are only as good as the where queries and payloads you construct for them, so it helps to know the full operator set Payload's query language supports:
These same operators are what you'll use to construct the where clauses for the bulk-operation and fixture-scoping tests later in this guide, so it's worth testing that your own custom validators respect them correctly — not just that Payload's built-in required-field checks work.
Use Case 3: Testing Type-Level Access & Permission Probing (GET /api/access)
Payload's Admin UI determines whether to render navigation menus, collection list buttons ("Create New", "Delete"), and editable inputs by querying GET /api/access, which executes every Access Control function at the top level, across all collections, globals, and fields, and returns a full permission reflection for the current user. You can verify these permissions without rendering the UI:
: when Payload executes your access control functions via the Access Operation (i.e. through , not against a real document), the , , , , and arguments are all , because there's no specific document in context. If any of your access control functions dereference or similar without a defined-check first, they'll throw or behave unpredictably during a probe test even though the same function works fine on a real request. Worse, if your access control function normally returns a query object (row-level, per-document access) rather than a plain boolean, that query is never evaluated here — Payload assumes "no access" instead. That means a type-level probe can legitimately report for a user who actually can read some documents, just not all of them. Don't treat as the full picture for row-level access; treat it as what the Admin UI uses to decide navigation and button visibility, and pair it with Use Case 4 below when you need to verify access to a specific document.
Use Case 4: Document-Level & Global Access Probing
GET /api/access only tells you what a user can do at the collection type level. Payload separately exposes per-document and per-global access checks, which is what actually answers "can this specific user read/update/delete this specific document" — the question row-level access control functions are usually written to answer.
This is the pair that closes the gap left by Use Case 3: use the type-level probe to test what shows up in the Admin UI's navigation and buttons, and use the document-level probe to test the row-level rules your access control functions actually enforce.
Use Case 5: Field-Level Access & Field Mutation
When certain fields should only be visible or editable by admins (internalNotes, approvedBy, commissionRate), assert both the permission probe and a real field mutation attempt, so a passing probe test can't mask a hook or access function that silently fails to enforce the same rule on write.
Payload's REST API supports bulk PATCH and DELETE directly on a collection endpoint (no ), taking a query in the same shape a list request would use — for example updates every matching document in one request. This is genuinely useful for fast fixture cleanup (delete every document your test run created by tagging them with a shared prefix and deleting by ), but it is also the single riskiest REST surface to get wrong, because a malformed clause historically matched — and mutated or deleted — every document in the collection instead of failing closed. That specific bug was fixed upstream, but the failure mode it represents (an invalid filter silently expanding to "everything") is exactly the kind of thing worth a permanent regression test in your own suite, regardless of which Payload version you're on:
Treat that malformed-where assertion as non-negotiable in any suite that uses bulk PATCH/DELETE for teardown — it is the difference between a fast cleanup helper and a script that can silently wipe a collection because a fixture prefix variable was undefined.
Use Case 7: Drafts & Version History
If your collection has versions: { drafts: true } enabled, Payload maintains a separate draft state alongside the published document and exposes both a ?draft=true query param on the standard read endpoint and a dedicated versions endpoint. Testing this is where a lot of "why does the live site show old content" bugs actually live.
The assertion that matters most here isn't that the draft saved — it's that a normal (non-draft) read stays pinned to the last published version while the draft edit is in flight. That's the exact guarantee editorial teams depend on, and it's easy to break with a caching layer or a hook that doesn't check _status correctly.
Use Case 8 (Advanced): Multi-Tier Approval & State Workflows
For applications implementing complex editorial workflows (Draft → Submitted → In Review → Approved → Published), you can test state machines and custom action endpoints cleanly over REST. Note that approval-requests and its submit/action endpoints below are not something Payload ships out of the box — they're a custom collection with custom endpoints you'd build for this workflow, shown here to demonstrate that REST testing scales cleanly to app-specific logic, not just Payload's built-in operations.
Do I need a running Next.js/Payload server to run these tests, or can I use the Local API instead?
These patterns require a running server, since they go over real HTTP and exercise the same auth middleware and serialization the Admin UI depends on. If you only need to test hooks or business logic in isolation without HTTP overhead, Payload's Local API (payload.find, payload.create) is faster for that narrower purpose, but it skips REST-layer concerns like header parsing and status codes.
Why does GET /api/access return read: false for a user who can clearly read some documents in the Admin UI?
This is the access-operation gotcha from Use Case 3: when your access control function returns a Where query (row-level access) instead of a plain boolean, the Access Operation can't evaluate that query without a real document in context, so it defaults to "no access." Test row-level rules against /api/<collection>/access/:id instead.
Can bulk PATCH/DELETE really wipe an entire collection from one bad request?
Historically yes, if an invalid where clause was silently dropped instead of rejected — a bug that has since been fixed upstream. Regardless of which Payload version you're running, keep a permanent regression test asserting that a malformed where clause returns 400 rather than matching every document, especially if you use bulk delete for test teardown.
How do I test that a field is read-only in the Admin UI without a browser?
Combine the field-level access probe (canEditField in Use Case 3) with a real PATCH attempt on that field (Use Case 5). The probe tells you what the Admin UI will render as editable; the mutation attempt tells you whether the same rule is actually enforced server-side, which is the assertion that matters.
Do I need to test drafts separately from published documents?
Yes, if your collection has versions: { drafts: true } enabled. A standard read and a ?draft=true read can diverge, and that divergence is exactly what protects your live site from showing unpublished edits — it's worth its own test rather than assuming the draft flag "just works."
Conclusion
Browser automation earns its keep for the parts of Payload's Admin Panel that are genuinely visual — rich text editing, drag-and-drop, live preview. Everything else the Admin UI does is a reflection of what the REST API returns, from GET /api/access deciding which buttons render to a 400 deciding whether a form shows a validation error. Testing at that layer directly, with a plain fetch client and try/finally teardown, turns a permissions or validation suite that used to take minutes into one that takes seconds, and it lets you cover negative cases and bulk-operation safety that would be painfully slow to click through by hand.
Let me know in the comments if you have questions, and subscribe for more practical development guides.
Thanks, Matija
Execution Speed: Running 50 browser tests can take several minutes due to browser launches, network idle waits, and React/Next.js hydration. The equivalent REST API suite executes in seconds, typically 20–50ms per request.
Comprehensive Negative & Validation Testing: Testing 20 variations of invalid input (missing required fields, duplicate slugs, invalid email formats, unauthorized role updates) in a browser requires slow form filling and DOM queries. Over REST, it is a loop of JSON payloads asserting 400 Bad Request responses.
Immediate Precision: REST responses provide exact HTTP status codes (200, 201, 400, 403, 500), typed JSON error arrays, and document IDs immediately, with no need to infer state from what rendered on screen.
Layer
What it actually verifies
When to use it
Browser (Playwright/Cypress)
Rendered UI, client-side JS, rich text canvas, visual regressions
Admin UI interactions a human actually clicks through: drag-and-drop, live preview, upload dropzones
REST API
HTTP-layer behavior: auth middleware, serialization, access control as the Admin UI itself calls it, status codes, real network round-trip
Access control, validation, CRUD, anything the Admin UI decides to render/hide based on a REST or GraphQL response
Local API
Business logic and hooks in isolation, without HTTP or auth middleware in the loop
Fast unit-style tests of hooks, field-level logic, or seeding large fixture sets in CI setup
// File: test/lib/rest-client.ts
export
type
ClientResponse
unknown
json
status
number
export
type
RawHttpClient
delete
unknown
path
string
Promise
ClientResponse
unknown
path
string
Promise
ClientResponse
unknown
path
string
body
unknown
Promise
ClientResponse
unknown
path
string
body
unknown
Promise
ClientResponse
readonly
authHeader
string
const
REQUEST_TIMEOUT_MS
30_000
async
function
baseUrl
string
method
string
path
string
authHeader
string
body
unknown
Promise
ClientResponse
const
headers
Record
string
string
"Content-Type"
"application/json"
if
"Authorization"
const
await
fetch
`${baseUrl}${path}`
body
undefined
undefined
JSON
stringify
signal
AbortSignal
timeout
REQUEST_TIMEOUT_MS
const
await
text
let
json
unknown
null
if
try
JSON
parse
catch
return
json
as
status
status
/** Creates an HTTP client bound to a specific Authorization header. */
export
function
createHttpClient
baseUrl: string, authHeader?: string
RawHttpClient
return
delete
(path: string) =>
"DELETE"
get
(path: string) =>
"GET"
patch
(path: string, body?: unknown) =>
"PATCH"
post
(path: string, body?: unknown) =>
"POST"
/** Creates an Admin Client authenticated via API Key (for fixture setup & cleanup). */
export
function
createAdminClient
baseUrl: string, adminApiKey: string
RawHttpClient
return
createHttpClient
`users API-Key ${adminApiKey}`
/** Logs in with user credentials and returns a client bound to their JWT. */
export
async
function
loginAsClient
baseUrl: string,
email: string,
password: string,
Promise
RawHttpClient
const
await
fetch
`${baseUrl}/api/users/login`
method
"POST"
headers
"Content-Type"
"application/json"
body
JSON
stringify
signal
AbortSignal
timeout
REQUEST_TIMEOUT_MS
if
ok
throw
new
Error
`Login failed for ${email}: ${res.status}${await res.text()}`
Pass ?locale=${DEFAULT_LOCALE} explicitly on all mutation (POST, PATCH) and localized read (GET) requests when localization.fallback is false, to avoid silent field drops.
Use the Admin Client exclusively for setup/cleanup. Keep assertions strictly tied to editorClient or viewerClient so a test can't pass because the admin bypassed the rule you meant to check.
Clean up in finally blocks. Wrap test mutations in try/finally so test databases stay clean even if an assertion fails midway.
Use random UUIDs for slugs and prefixes, and prefer where[slug][like]=<prefix> bulk deletes for teardown over deleting by ID one at a time — but always pair bulk teardown with the malformed-where regression test from Use Case 6.
Enforce request timeouts. Wrap HTTP requests in AbortSignal.timeout(30_000) so a hanging request fails fast instead of hanging your test run.
Don't treat GET /api/access as row-level truth. It reflects type-level, UI-facing permissions with id/data/doc undefined; use the document-level /access/:id endpoint (Use Case 4) whenever you're testing a rule that depends on document ownership or state.
