@bhofstaetter/payloadcms-integration-test-utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benedikt Hofstätter
+
+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,180 @@
+# payloadcms-integration-test-utils
+
+Opinionated integration test helpers providing a ready-to-use Payload instance for vitest.
+
+## Installation
+
+```sh
+npm install -D @bhofstaetter/payloadcms-integration-test-utils
+```
+
+Depending on your used database
+
+```sh
+npm install -D @testcontainers/mongodb
+```
+
+or
+
+```sh
+npm install -D @testcontainers/postgresql
+```
+
+## Usage
+
+### 1. Create a global setup file
+
+Create a file that re-exports the `setup` and `teardown` functions:
+
+```ts
+// test/setupIntegrationTest.ts
+export {setup, teardown} from '@bhofstaetter/payloadcms-integration-test-utils';
+```
+
+### 2. Configure Vitest
+
+Reference the global setup file and set `DB_TYPE` plus the corresponding Docker image `MONGO_DB_IMAGE|POSTGRES_IMAGE`.
+
+```ts
+// vitest.config.ts
+import {defineConfig} from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        projects: [
+            {
+                test: {
+                    name: 'mongodb',
+                    include: ['./test/integration/**/*.test.ts'],
+                    globalSetup: './test/setupIntegrationTest.ts',
+                    testTimeout: 30000,
+                    hookTimeout: 30000,
+                    fileParallelism: false,
+                    env: {
+                        DB_TYPE: 'mongodb',
+                        MONGO_DB_IMAGE: 'mongo:8.0',
+                    },
+                },
+            },
+        ],
+    },
+});
+```
+
+### 3. Write tests
+
+Use `getTestContextFor` to get a Payload Local API instance wired to the containerized database:
+
+```ts
+// test/integration/posts.test.ts
+import type {CollectionConfig} from 'payload';
+import {expect, it} from 'vitest';
+import {getTestContextFor} from '@bhofstaetter/payloadcms-integration-test-utils';
+
+const Posts: CollectionConfig = {
+    slug: 'posts',
+    fields: [{type: 'text', name: 'title'}],
+};
+
+const ctx = getTestContextFor({collections: [Posts]});
+
+it('creates and retrieves a document', async () => {
+    const created = await ctx.payload.create({
+        collection: 'posts',
+        data: {title: 'Hello World'},
+    });
+
+    const result = await ctx.payload.find({collection: 'posts'});
+
+    expect(result.totalDocs).toBe(1);
+    expect(result.docs[0].id).toBe(created.id);
+});
+
+it('starts each test with a clean database', async () => {
+    const count = await ctx.payload.count({collection: 'posts'});
+    expect(count.totalDocs).toBe(0);
+});
+```
+
+You can also test globals, or combine both:
+
+```ts
+import type {CollectionConfig, GlobalConfig} from 'payload';
+import {getTestContextFor} from '@bhofstaetter/payloadcms-integration-test-utils';
+
+const Posts: CollectionConfig = {
+    slug: 'posts',
+    fields: [{type: 'text', name: 'title'}],
+};
+
+const Settings: GlobalConfig = {
+    slug: 'settings',
+    fields: [{type: 'text', name: 'siteTitle'}],
+};
+
+// collections only
+const ctx = getTestContextFor({collections: [Posts]});
+
+// globals only
+const ctx = getTestContextFor({globals: [Settings]});
+
+// both
+const ctx = getTestContextFor({collections: [Posts], globals: [Settings]});
+```
+
+## How It Works
+
+### Global Setup (`setup` / `teardown`)
+
+The `setup` function reads `DB_TYPE` from the Vitest project env and starts the corresponding Testcontainer:
+
+| `DB_TYPE`  | Container image env | Container             |
+|------------|---------------------|-----------------------|
+| `mongodb`  | `MONGO_DB_IMAGE`    | `MongoDBContainer`    |
+| `postgres` | `POSTGRES_IMAGE`    | `PostgreSqlContainer` |
+
+It sets `DATABASE_URL` and `DATABASE_TYPE` as process environment variables so the Payload adapter can connect. The
+`teardown` function stops the container.
+
+### `getTestContextFor(options)`
+
+Registers Vitest lifecycle hooks and returns a context object.
+
+**Options:**
+
+| Property       | Type                 | Default    | Description                        |
+|----------------|----------------------|------------|------------------------------------|
+| `collections`  | `CollectionConfig[]` | `[]`       | Collections to register and clean  |
+| `globals`      | `GlobalConfig[]`     | `[]`       | Globals to register                |
+| `tsOutputFile` | `string`             | `/dev/null`| Path to generate Payload types to  |
+
+**Lifecycle hooks:**
+
+- **`beforeAll`** — initializes a Payload instance with the given collections and globals using the database from the global setup
+- **`beforeEach`** — deletes all documents from every provided collection
+- **`afterAll`** — deletes all documents from every provided collection
+- **`ctx.payload`** — getter that returns the `BasePayload` instance for Local API calls
+
+### `getPayloadInstance(collections, globals, tsOutputFile?)`
+
+Lower-level function used by `getTestContextFor`. Creates (or returns a cached) Payload instance based on
+`DATABASE_TYPE` and `DATABASE_URL` environment variables. Caches by URL so repeated calls in the same test file reuse
+the same instance.
+
+### Type Generation
+
+Pass `tsOutputFile` to generate Payload types:
+
+```ts
+const ctx = getTestContextFor({collections: [Posts], tsOutputFile: './test/payload-types.ts'});
+```
+
+Defaults to `/dev/null` (disabled).
+
+## License
+
+MIT
+
+## Todo
+
+- [ ] Github Actions

package/dist/getPayloadInstance.d.ts

@@ -0,0 +1,2 @@
+import { type BasePayload, type CollectionConfig, type GlobalConfig } from 'payload';
+export declare const getPayloadInstance: (collections: CollectionConfig[], globals: GlobalConfig[], tsOutputFile?: string) => Promise<BasePayload>;

package/dist/getPayloadInstance.js

@@ -0,0 +1,43 @@
+import { buildConfig, getPayload } from 'payload';
+import { generateTypes } from 'payload/node';
+let cachedPayload = null;
+let cachedForUrl = null;
+const getDbAdapter = async () => {
+    const dbType = process.env.DATABASE_TYPE;
+    if (dbType === 'mongodb') {
+        const { mongooseAdapter } = await import('@payloadcms/db-mongodb');
+        return mongooseAdapter({
+            url: process.env.DATABASE_URL || '',
+        });
+    }
+    else if (dbType === 'postgres') {
+        const { postgresAdapter } = await import('@payloadcms/db-postgres');
+        return postgresAdapter({
+            pool: {
+                connectionString: process.env.DATABASE_URL || '',
+            },
+        });
+    }
+    throw new Error('No or wrong DB_TYPE set. Check your vitest project setup.');
+};
+export const getPayloadInstance = async (collections, globals, tsOutputFile) => {
+    const currentUrl = process.env.DATABASE_URL || '';
+    if (cachedPayload && cachedForUrl === currentUrl) {
+        return cachedPayload;
+    }
+    const config = buildConfig({
+        collections,
+        globals,
+        secret: 'test-secret',
+        db: await getDbAdapter(),
+        typescript: {
+            outputFile: tsOutputFile ?? '/dev/null',
+        },
+    });
+    cachedPayload = await getPayload({ config });
+    cachedForUrl = currentUrl;
+    if (tsOutputFile) {
+        await generateTypes(cachedPayload.config);
+    }
+    return cachedPayload;
+};

package/dist/getTestContextFor.d.ts

@@ -0,0 +1,10 @@
+import type { BasePayload, CollectionConfig, GlobalConfig } from 'payload';
+type TestContextOptions = {
+    collections?: CollectionConfig[];
+    globals?: GlobalConfig[];
+    tsOutputFile?: string;
+};
+export declare const getTestContextFor: (options: TestContextOptions) => {
+    readonly payload: BasePayload;
+};
+export {};

package/dist/getTestContextFor.js

@@ -0,0 +1,24 @@
+import { afterAll, beforeAll, beforeEach } from 'vitest';
+import { getPayloadInstance } from './getPayloadInstance.js';
+export const getTestContextFor = (options) => {
+    const { collections = [], globals = [], tsOutputFile } = options;
+    let payload;
+    beforeAll(async () => {
+        payload = await getPayloadInstance(collections, globals, tsOutputFile);
+    });
+    beforeEach(async () => {
+        for (const collection of collections) {
+            await payload.delete({ collection: collection.slug, where: {} });
+        }
+    });
+    afterAll(async () => {
+        for (const collection of collections) {
+            await payload.delete({ collection: collection.slug, where: {} });
+        }
+    });
+    return {
+        get payload() {
+            return payload;
+        },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { getPayloadInstance } from './getPayloadInstance.js';
+export { getTestContextFor } from './getTestContextFor.js';
+export { setup, teardown } from './setup.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { getPayloadInstance } from './getPayloadInstance.js';
+export { getTestContextFor } from './getTestContextFor.js';
+export { setup, teardown } from './setup.js';

package/dist/setup.d.ts

@@ -0,0 +1,3 @@
+import type { TestProject } from 'vitest/node';
+export declare const setup: (project: TestProject) => Promise<void>;
+export declare const teardown: () => Promise<void>;

package/dist/setup.js

@@ -0,0 +1,29 @@
+let container;
+export const setup = async (project) => {
+    const dbType = project.config.env.DB_TYPE;
+    process.env.DATABASE_TYPE = dbType;
+    if (dbType === 'mongodb') {
+        const mongoImage = project.config.env.MONGO_DB_IMAGE;
+        if (!mongoImage) {
+            throw new Error('MONGO_DB_IMAGE is not set. Check your vitest project setup.');
+        }
+        const { MongoDBContainer } = await import('@testcontainers/mongodb');
+        container = await new MongoDBContainer(mongoImage).start();
+        process.env.DATABASE_URL = `${container.getConnectionString?.()}?directConnection=true`;
+    }
+    else if (dbType === 'postgres') {
+        const postgresImage = project.config.env.POSTGRES_IMAGE;
+        if (!postgresImage) {
+            throw new Error('POSTGRES_IMAGE is not set. Check your vitest project setup.');
+        }
+        const { PostgreSqlContainer } = await import('@testcontainers/postgresql');
+        container = await new PostgreSqlContainer(postgresImage).start();
+        process.env.DATABASE_URL = container.getConnectionUri?.();
+    }
+    else {
+        throw new Error('No or wrong DB_TYPE set. Check your vitest project setup.');
+    }
+};
+export const teardown = async () => {
+    await container?.stop();
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+    "name": "@bhofstaetter/payloadcms-integration-test-utils",
+    "version": "1.0.0",
+    "description": "Opinionated integration test helpers providing a ready-to-use Payload instance for vitest.",
+    "license": "MIT",
+    "author": "Benedikt Hofstätter",
+    "homepage": "https://github.com/bhofstaetter/payloadcms-integration-test-utils",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/bhofstaetter/payloadcms-integration-test-utils.git"
+    },
+    "keywords": [
+        "payload",
+        "payloadcms",
+        "local api",
+        "testing",
+        "integration test",
+        "mongodb",
+        "postgres",
+        "vitest"
+    ],
+    "type": "module",
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "rm -rf dist && tsc -p tsconfig.build.json",
+        "typecheck": "tsc",
+        "lint": "biome check",
+        "lint:fix": "biome check --fix",
+        "test": "vitest run",
+        "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build"
+    },
+    "peerDependencies": {
+        "payload": ">=3",
+        "vitest": ">=4"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.4.4",
+        "@payloadcms/db-postgres": "3.78.0",
+        "@payloadcms/db-mongodb": "3.78.0",
+        "@testcontainers/postgresql": "^11.12.0",
+        "@testcontainers/mongodb": "^11.12.0",
+        "payload": "3.78.0",
+        "typescript": "^5",
+        "vite-tsconfig-paths": "^6.1.1",
+        "vitest": "^4.0.18"
+    },
+    "engines": {
+        "node": ">=22.0.0"
+    }
+}