payload-test-api-route-handler 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MaDz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+<div align="center">
+
+# payload-test-api-route-handler
+
+**Test Payload CMS API routes without a running server.**
+
+[![npm version](https://img.shields.io/npm/v/payload-test-api-route-handler.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/payload-test-api-route-handler)
+[![npm downloads](https://img.shields.io/npm/dm/payload-test-api-route-handler.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/payload-test-api-route-handler)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178c6.svg?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Payload CMS](https://img.shields.io/badge/Payload_CMS-v3-000000.svg?style=flat-square)](https://payloadcms.com/)
+
+An in-process test utility for [Payload CMS](https://payloadcms.com) v3+ that lets you exercise API route handlers, authentication, database transactions, and custom endpoints using a standard [Axios](https://axios-http.com) client — **without starting a live HTTP server**.
+
+</div>
+
+---
+
+## Why?
+
+Testing Payload CMS endpoints typically requires spinning up a full Next.js dev server. This is **slow**, **flaky**, and makes CI pipelines painful.
+
+This package gives you a drop-in Axios client that routes requests **directly** into Payload's handler pipeline in-process. Your tests run in milliseconds, not seconds.
+
+```
+Traditional approach          This package
+┌──────────┐                  ┌──────────┐
+│  Test     │ ── HTTP ──►     │  Test     │
+│  Suite    │                 │  Suite    │
+└──────────┘                  └─────┬────┘
+     │                              │
+     ▼                              ▼  (in-process)
+┌──────────┐                  ┌──────────┐
+│  HTTP    │                  │  Payload │
+│  Server  │                  │  Handler │
+└─────┬────┘                  └──────────┘
+      │                       No network. No server.
+      ▼                       Just fast tests.
+┌──────────┐
+│  Payload │
+│  Handler │
+└──────────┘
+```
+
+## Features
+
+- 🚀 **Zero Server** — No HTTP server, no port conflicts, no startup delay
+- 🔐 **Full Auth Pipeline** — JWT login, token resolution, `req.user` — it all works
+- 🗄️ **Real Transactions** — Database transaction context flows through hooks exactly like production
+- 🧬 **Request Patching** — Inject custom user sessions, override route params, mock anything
+- 📦 **Standard Axios** — Interceptors, defaults, `client.defaults.headers` — everything you expect
+- 🧪 **Framework Agnostic** — Works with Vitest, Jest, or any test runner
+- 🎯 **Full Endpoint Coverage** — Config endpoints, collection endpoints, global endpoints, and built-in CRUD
+
+## Installation
+
+```bash
+# npm
+npm install --save-dev payload-test-api-route-handler
+
+# yarn
+yarn add -D payload-test-api-route-handler
+
+# pnpm
+pnpm add -D payload-test-api-route-handler
+```
+
+> **Peer dependency:** Requires `payload` v3.85.1 or later.
+
+## Quick Start
+
+```typescript
+import { describe, it, expect, beforeAll } from 'vitest';
+import { getPayload } from 'payload';
+import { buildConfig } from 'payload';
+import { sqliteAdapter } from '@payloadcms/db-sqlite';
+import { lexicalEditor } from '@payloadcms/richtext-lexical';
+import { createTesterAxios } from 'payload-test-api-route-handler';
+
+describe('My API', () => {
+  let config;
+
+  beforeAll(async () => {
+    config = await buildConfig({
+      db: sqliteAdapter({ client: { url: 'file::memory:' } }),
+      editor: lexicalEditor({}),
+      secret: 'test-secret-at-least-32-chars-long!!',
+      collections: [
+        {
+          slug: 'posts',
+          fields: [{ name: 'title', type: 'text', required: true }],
+          endpoints: [
+            {
+              path: '/featured',
+              method: 'get',
+              handler: async () =>
+                Response.json({ featured: true }),
+            },
+          ],
+        },
+      ],
+    });
+
+    await getPayload({ config });
+  });
+
+  it('hits a custom endpoint', async () => {
+    const client = createTesterAxios(config);
+    const res = await client.get('/api/posts/featured');
+
+    expect(res.status).toBe(200);
+    expect(res.data).toEqual({ featured: true });
+  });
+
+  it('creates a post via built-in CRUD', async () => {
+    const client = createTesterAxios(config);
+    const res = await client.post('/api/posts', {
+      title: 'Hello World',
+    });
+
+    expect(res.status).toBe(201);
+    expect(res.data.doc.title).toBe('Hello World');
+  });
+});
+```
+
+## Usage Recipes
+
+### Authentication Flow
+
+```typescript
+const client = createTesterAxios(config);
+
+// Login
+const { data } = await client.post('/api/users/login', {
+  email: 'admin@example.com',
+  password: 'password',
+});
+
+// Set token for all subsequent requests
+client.defaults.headers.common['Authorization'] = `JWT ${data.token}`;
+
+// Now all requests are authenticated
+const res = await client.get('/api/users/me');
+expect(res.data.user.email).toBe('admin@example.com');
+```
+
+### Request Patching
+
+Inject a mock user, override route parameters, or modify the request before it hits the handler:
+
+```typescript
+const client = createTesterAxios(config, {
+  requestPatcher: (req) => {
+    // Force a specific user for all requests
+    req.user = { id: '1', email: 'mock@test.com' };
+    return req;
+  },
+});
+```
+
+### Custom Axios Configuration
+
+```typescript
+const client = createTesterAxios(config, {
+  axiosConfig: {
+    timeout: 5000,
+    // Don't throw on 4xx/5xx — useful for testing error responses
+    validateStatus: () => true,
+  },
+});
+
+const res = await client.get('/api/nonexistent');
+expect(res.status).toBe(404);
+```
+
+## API Reference
+
+### `createTesterAxios(config, options?)`
+
+Creates an Axios instance that routes requests in-process to Payload CMS handlers.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config` | `SanitizedConfig` | The sanitized config returned by `buildConfig()` |
+| `options.requestPatcher` | `(req: PayloadRequest) => PayloadRequest \| Promise<PayloadRequest>` | Mutate the request before handler execution |
+| `options.axiosConfig` | `AxiosRequestConfig` | Default Axios configuration for the instance |
+
+**Returns:** `AxiosInstance` — a standard Axios client.
+
+---
+
+### Exported Utilities
+
+| Export | Description |
+|--------|-------------|
+| `createTesterAxios` | Main entry point — creates the test Axios client |
+| `createAxiosAdapter` | Lower-level adapter if you need custom Axios setup |
+| `matchEndpoint` | Manually match a path/method to a Payload endpoint |
+| `matchRoute` | Pattern matching utility for Express-style `:param` routes |
+| `buildPayloadRequest` | Construct a `PayloadRequest` from raw URL, method, headers |
+| `EndpointNotFoundError` | Thrown when no matching endpoint is found |
+| `HandlerExecutionError` | Thrown when a handler throws during execution |
+
+## How It Works
+
+```
+createTesterAxios(config)
+        │
+        ▼
+   Axios Instance
+   (custom adapter)
+        │
+   client.get('/api/posts/featured')
+        │
+        ▼
+  ┌─────────────────┐
+  │ matchEndpoint()  │  ← Resolves handler + route params
+  └────────┬────────┘
+           ▼
+  ┌─────────────────┐
+  │ buildPayload     │  ← Creates PayloadRequest with
+  │ Request()        │    auth, headers, body, transaction
+  └────────┬────────┘
+           ▼
+  ┌─────────────────┐
+  │ requestPatcher() │  ← Optional mutation hook
+  └────────┬────────┘
+           ▼
+  ┌─────────────────┐
+  │ handler(req)     │  ← Your endpoint handler runs
+  └────────┬────────┘
+           ▼
+  ┌─────────────────┐
+  │ Response →       │  ← Converted to AxiosResponse
+  │ AxiosResponse    │
+  └─────────────────┘
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to open an issue or submit a pull request.
+
+```bash
+# Clone and install
+git clone https://github.com/000MaDz000/payload-test-api-route-handler.git
+cd payload-test-api-route-handler
+pnpm install
+
+# Run tests
+pnpm test
+
+# Build
+pnpm build
+
+# Lint & format
+pnpm lint
+pnpm format
+```
+
+## License
+
+[MIT](LICENSE) © MaDz

package/dist/axios-adapter.d.ts

@@ -0,0 +1,11 @@
+import type { AxiosRequestConfig, AxiosResponse } from 'axios';
+import type { SanitizedConfig, PayloadRequest } from 'payload';
+export interface AxiosAdapterOptions {
+    config: SanitizedConfig;
+    requestPatcher?: (req: PayloadRequest) => PayloadRequest | Promise<PayloadRequest>;
+}
+/**
+ * Creates an axios-compatible adapter that dynamically matches and routes requests to Payload CMS handlers
+ */
+export declare function createAxiosAdapter(options: AxiosAdapterOptions): (axiosConfig: AxiosRequestConfig) => Promise<AxiosResponse>;
+//# sourceMappingURL=axios-adapter.d.ts.map

package/dist/axios-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axios-adapter.d.ts","sourceRoot":"","sources":["../src/axios-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK/D,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,eAAe,CAAC;IACxB,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACpF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,iBAClC,kBAAkB,KAAG,OAAO,CAAC,aAAa,CAAC,CAwIvE"}

package/dist/axios-adapter.js

@@ -0,0 +1,112 @@
+import { matchEndpoint } from './match-endpoint.js';
+import { buildPayloadRequest } from './build-request.js';
+import { HandlerExecutionError } from './errors.js';
+/**
+ * Creates an axios-compatible adapter that dynamically matches and routes requests to Payload CMS handlers
+ */
+export function createAxiosAdapter(options) {
+    return async (axiosConfig) => {
+        // 1. Build the full URL
+        const urlStr = axiosConfig.url ?? '';
+        const urlObj = new URL(urlStr, 'http://localhost');
+        if (axiosConfig.params) {
+            for (const [key, value] of Object.entries(axiosConfig.params)) {
+                if (value !== undefined && value !== null) {
+                    urlObj.searchParams.append(key, typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+                        ? String(value)
+                        : JSON.stringify(value));
+                }
+            }
+        }
+        // 2. Resolve request method and headers
+        const method = axiosConfig.method ?? 'GET';
+        const headersMap = {};
+        if (axiosConfig.headers) {
+            const headersObj = typeof axiosConfig.headers.toJSON === 'function'
+                ? axiosConfig.headers.toJSON()
+                : axiosConfig.headers;
+            for (const [key, value] of Object.entries(headersObj)) {
+                if (value !== undefined &&
+                    value !== null &&
+                    (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')) {
+                    headersMap[key] = String(value);
+                }
+            }
+        }
+        // 3. Resolve the endpoint handler and matching route parameters dynamically
+        const match = matchEndpoint(options.config, urlObj.pathname, method);
+        const activeHandler = match.endpoint.handler;
+        const matchedParams = match.params;
+        let collectionSlug = undefined;
+        let globalSlug = undefined;
+        if (match.source === 'collection' && match.sourceName) {
+            collectionSlug = match.sourceName;
+        }
+        else if (match.source === 'global' && match.sourceName) {
+            globalSlug = match.sourceName;
+        }
+        // 4. Build standard PayloadRequest
+        let req = await buildPayloadRequest(options.config, urlObj.toString(), method, headersMap, axiosConfig.data);
+        // 5. Populate route parameters
+        req.routeParams = {
+            ...matchedParams,
+        };
+        if (collectionSlug) {
+            req.routeParams.collection = collectionSlug;
+            req.collection =
+                req.payload.collections[collectionSlug];
+        }
+        if (globalSlug) {
+            req.routeParams.global = globalSlug;
+        }
+        // 6. Run patcher if provided
+        if (options.requestPatcher) {
+            req = await options.requestPatcher(req);
+        }
+        // 7. Execute the handler
+        let response;
+        try {
+            response = await activeHandler(req);
+        }
+        catch (err) {
+            throw new HandlerExecutionError(err instanceof Error ? err.message : String(err));
+        }
+        // 8. Convert response headers
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        // 9. Convert response body
+        let responseData;
+        const contentType = response.headers.get('content-type');
+        if (contentType?.includes('application/json')) {
+            const text = await response.text();
+            try {
+                responseData = JSON.parse(text);
+            }
+            catch {
+                responseData = text;
+            }
+        }
+        else {
+            responseData = await response.text();
+        }
+        const axiosResponse = {
+            data: responseData,
+            status: response.status,
+            statusText: response.statusText,
+            headers: responseHeaders,
+            config: axiosConfig,
+        };
+        // 10. Validate status to reject promise (simulating Axios's validateStatus behavior)
+        const validateStatus = axiosConfig.validateStatus ?? ((status) => status >= 200 && status < 300);
+        if (!validateStatus(response.status)) {
+            const error = new Error(`Request failed with status code ${String(response.status)}`);
+            error.config = axiosConfig;
+            error.response = axiosResponse;
+            error.isAxiosError = true;
+            throw error;
+        }
+        return axiosResponse;
+    };
+}

package/dist/build-request.d.ts

@@ -0,0 +1,6 @@
+import type { PayloadRequest, SanitizedConfig } from 'payload';
+/**
+ * Build a PayloadRequest from standard URL, method, headers and body
+ */
+export declare function buildPayloadRequest(config: SanitizedConfig, url: string, method: string, headersMap: Record<string, string>, body?: unknown): Promise<PayloadRequest>;
+//# sourceMappingURL=build-request.d.ts.map

package/dist/build-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-request.d.ts","sourceRoot":"","sources":["../src/build-request.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/D;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,cAAc,CAAC,CA6BzB"}

package/dist/build-request.js

@@ -0,0 +1,32 @@
+import { createPayloadRequest } from 'payload';
+/**
+ * Build a PayloadRequest from standard URL, method, headers and body
+ */
+export async function buildPayloadRequest(config, url, method, headersMap, body) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(headersMap)) {
+        headers.set(key, value);
+    }
+    let bodyInit = undefined;
+    if (body !== undefined && body !== null) {
+        if (typeof body === 'string' || typeof body === 'number' || typeof body === 'boolean') {
+            bodyInit = String(body);
+        }
+        else {
+            bodyInit = JSON.stringify(body);
+            if (!headers.has('content-type')) {
+                headers.set('content-type', 'application/json');
+            }
+        }
+    }
+    // Create standard web Request
+    const webRequest = new Request(url, {
+        method: method.toUpperCase(),
+        headers,
+        body: bodyInit,
+    });
+    return await createPayloadRequest({
+        config,
+        request: webRequest,
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class EndpointNotFoundError extends Error {
+    constructor(message: string);
+}
+export declare class HandlerExecutionError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,12 @@
+export class EndpointNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EndpointNotFoundError';
+    }
+}
+export class HandlerExecutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HandlerExecutionError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import type { AxiosInstance, AxiosRequestConfig } from 'axios';
+import type { SanitizedConfig, PayloadRequest } from 'payload';
+export * from './errors.js';
+export * from './match-endpoint.js';
+export * from './build-request.js';
+export * from './axios-adapter.js';
+export interface CreateTesterAxiosOptions {
+    /**
+     * Optional patcher function to mutate standard PayloadRequest before handler execution
+     */
+    requestPatcher?: (req: PayloadRequest) => PayloadRequest | Promise<PayloadRequest>;
+    /**
+     * Optional default configuration for the created Axios instance
+     */
+    axiosConfig?: AxiosRequestConfig;
+}
+/**
+ * Creates an AxiosInstance routed directly to Payload CMS handlers in-process
+ */
+export declare function createTesterAxios(config: SanitizedConfig, options?: CreateTesterAxiosOptions): AxiosInstance;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG/D,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AAEnC,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAEnF;;OAEG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE,wBAAwB,GACjC,aAAa,CAUf"}

package/dist/index.js

@@ -0,0 +1,19 @@
+import axios from 'axios';
+import { createAxiosAdapter } from './axios-adapter.js';
+export * from './errors.js';
+export * from './match-endpoint.js';
+export * from './build-request.js';
+export * from './axios-adapter.js';
+/**
+ * Creates an AxiosInstance routed directly to Payload CMS handlers in-process
+ */
+export function createTesterAxios(config, options) {
+    const adapter = createAxiosAdapter({
+        config,
+        requestPatcher: options?.requestPatcher,
+    });
+    return axios.create({
+        adapter,
+        ...options?.axiosConfig,
+    });
+}

package/dist/match-endpoint.d.ts

@@ -0,0 +1,17 @@
+import type { SanitizedConfig, Endpoint } from 'payload';
+export interface MatchResult {
+    endpoint: Endpoint;
+    params: Record<string, string>;
+    source: 'config' | 'collection' | 'global';
+    sourceName?: string;
+}
+/**
+ * Match a pattern path with a pathname and extract parameters
+ * e.g. pattern="/api/users/:id", pathname="/api/users/123" -> { id: "123" }
+ */
+export declare function matchRoute(pattern: string, pathname: string): Record<string, string> | null;
+/**
+ * Traverse Payload config endpoints to find a match for pathname and method
+ */
+export declare function matchEndpoint(config: SanitizedConfig, pathname: string, method: string): MatchResult;
+//# sourceMappingURL=match-endpoint.d.ts.map

package/dist/match-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match-endpoint.d.ts","sourceRoot":"","sources":["../src/match-endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGzD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,QAAQ,GAAG,YAAY,GAAG,QAAQ,CAAC;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAuB3F;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,WAAW,CA+Db"}

package/dist/match-endpoint.js

@@ -0,0 +1,86 @@
+import { EndpointNotFoundError } from './errors.js';
+/**
+ * Match a pattern path with a pathname and extract parameters
+ * e.g. pattern="/api/users/:id", pathname="/api/users/123" -> { id: "123" }
+ */
+export function matchRoute(pattern, pathname) {
+    const patternParts = pattern.replace(/^\/+/, '').replace(/\/+$/, '').split('/');
+    const pathParts = pathname.replace(/^\/+/, '').replace(/\/+$/, '').split('/');
+    if (patternParts.length !== pathParts.length) {
+        return null;
+    }
+    const params = {};
+    for (let i = 0; i < patternParts.length; i++) {
+        const patternPart = patternParts[i];
+        const pathPart = pathParts[i];
+        if (patternPart.startsWith(':')) {
+            const paramName = patternPart.slice(1);
+            params[paramName] = decodeURIComponent(pathPart);
+        }
+        else if (patternPart.toLowerCase() !== pathPart.toLowerCase()) {
+            return null;
+        }
+    }
+    return params;
+}
+/**
+ * Traverse Payload config endpoints to find a match for pathname and method
+ */
+export function matchEndpoint(config, pathname, method) {
+    const apiRoute = config.routes.api;
+    const reqMethod = method.toLowerCase();
+    // 1. Check Global Config Endpoints
+    for (const endpoint of config.endpoints) {
+        if (endpoint.method.toLowerCase() === reqMethod) {
+            let cleanPath = endpoint.path;
+            if (cleanPath !== '/' && !cleanPath.startsWith('/')) {
+                cleanPath = `/${cleanPath}`;
+            }
+            const endPath = cleanPath === '/' ? '' : cleanPath;
+            const pattern = `${apiRoute}${endPath}`;
+            const params = matchRoute(pattern, pathname);
+            if (params) {
+                return { endpoint, params, source: 'config' };
+            }
+        }
+    }
+    // 2. Check Collection Endpoints
+    for (const collection of config.collections) {
+        if (collection.endpoints) {
+            for (const endpoint of collection.endpoints) {
+                if (endpoint.method.toLowerCase() === reqMethod) {
+                    let cleanPath = endpoint.path;
+                    if (cleanPath !== '/' && !cleanPath.startsWith('/')) {
+                        cleanPath = `/${cleanPath}`;
+                    }
+                    const endPath = cleanPath === '/' ? '' : cleanPath;
+                    const pattern = `${apiRoute}/${collection.slug}${endPath}`;
+                    const params = matchRoute(pattern, pathname);
+                    if (params) {
+                        return { endpoint, params, source: 'collection', sourceName: collection.slug };
+                    }
+                }
+            }
+        }
+    }
+    // 3. Check Global Config Collection/Global Endpoints
+    for (const globalConfig of config.globals) {
+        if (globalConfig.endpoints) {
+            for (const endpoint of globalConfig.endpoints) {
+                if (endpoint.method.toLowerCase() === reqMethod) {
+                    let cleanPath = endpoint.path;
+                    if (cleanPath !== '/' && !cleanPath.startsWith('/')) {
+                        cleanPath = `/${cleanPath}`;
+                    }
+                    const endPath = cleanPath === '/' ? '' : cleanPath;
+                    const pattern = `${apiRoute}/globals/${globalConfig.slug}${endPath}`;
+                    const params = matchRoute(pattern, pathname);
+                    if (params) {
+                        return { endpoint, params, source: 'global', sourceName: globalConfig.slug };
+                    }
+                }
+            }
+        }
+    }
+    throw new EndpointNotFoundError(`No matching endpoint found for pathname "${pathname}" with method "${method.toUpperCase()}"`);
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "payload-test-api-route-handler",
+  "version": "1.0.0",
+  "description": "Test Payload CMS v3+ API route handlers in-process using Axios — no HTTP server needed. Supports auth, transactions, request patching, built-in CRUD endpoints, and custom endpoints.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "payload-cms",
+    "test",
+    "testing",
+    "api",
+    "route-handler",
+    "in-process",
+    "axios",
+    "vitest",
+    "jest",
+    "integration-test",
+    "endpoint",
+    "headless-cms"
+  ],
+  "author": "MaDz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/000MaDz000/payload-test-api-route-handler.git"
+  },
+  "bugs": {
+    "url": "https://github.com/000MaDz000/payload-test-api-route-handler/issues"
+  },
+  "homepage": "https://github.com/000MaDz000/payload-test-api-route-handler#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "pnpm lint && tsc",
+    "dev": "tsc --watch",
+    "lint": "pnpm format:check && pnpm lint:eslint && tsc --noEmit",
+    "lint:eslint": "eslint \"src/**/*.{ts,tsx}\" --max-warnings=0",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\" \"tests/**/*.ts\"",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "dependencies": {
+    "axios": "^1.17.0"
+  },
+  "peerDependencies": {
+    "payload": "^3.85.1"
+  },
+  "devDependencies": {
+    "@payloadcms/db-sqlite": "^3.85.1",
+    "@payloadcms/richtext-lexical": "^3.85.1",
+    "@types/node": "^22.5.4",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "payload": "^3.85.1",
+    "prettier": "^3.7.4",
+    "typescript": "5.7.3",
+    "vitest": "4.1.8"
+  }
+}