test: reorganize helpers into shared/e2e/int subdirectories

.github/actions/start-database/action.yml

@@ -25,23 +25,23 @@ runs:
       if: contains(fromJSON('["mongodb", "cosmosdb", "documentdb", "firestore"]'), inputs.database)
       shell: bash
       run: |
-        docker compose -f test/helpers/db/mongodb/docker-compose.yml up -d --wait
+        docker compose -f test/__helpers/shared/db/mongodb/docker-compose.yml up -d --wait
         echo "url=mongodb://payload:payload@localhost:27018/payload?authSource=admin&directConnection=true&replicaSet=rs0" >> $GITHUB_OUTPUT
 
     - name: Start MongoDB Atlas Local
       id: mongodb-atlas
       if: inputs.database == 'mongodb-atlas'
       shell: bash
       run: |
-        docker compose -f test/helpers/db/mongodb-atlas/docker-compose.yml up -d --wait
+        docker compose -f test/__helpers/shared/db/mongodb-atlas/docker-compose.yml up -d --wait
         echo "url=mongodb://localhost:27019/payload?directConnection=true&replicaSet=mongodb-atlas-local" >> $GITHUB_OUTPUT
 
     - name: Start PostgreSQL
       id: postgres
       if: startsWith(inputs.database, 'postgres')
       shell: bash
       run: |
-        docker compose -f test/helpers/db/postgres/docker-compose.yml up -d --wait
+        docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml up -d --wait
         echo "url=postgresql://payload:payload@localhost:5433/payload" >> $GITHUB_OUTPUT
 
     - name: Configure PostgreSQL custom schema

package.json

@@ -82,20 +82,20 @@
     "dev:vercel-postgres": "cross-env PAYLOAD_DATABASE=vercel-postgres pnpm runts ./test/dev.ts",
     "devsafe": "node ./scripts/delete-recursively.js '**/.next' && pnpm dev",
     "docker:mongodb-atlas:restart": "pnpm docker:mongodb-atlas:stop && pnpm docker:mongodb-atlas:start",
-    "docker:mongodb-atlas:restart:clean": "docker rm -f mongodb-atlas-payload-test 2>/dev/null; docker compose -f test/helpers/db/mongodb-atlas/docker-compose.yml down -v && pnpm docker:mongodb-atlas:start",
-    "docker:mongodb-atlas:start": "docker compose -f test/helpers/db/mongodb-atlas/docker-compose.yml up -d --wait",
-    "docker:mongodb-atlas:stop": "docker compose -f test/helpers/db/mongodb-atlas/docker-compose.yml down",
-    "docker:mongodb-atlas:test": "pnpm runts test/helpers/db/mongodb-atlas/run-test-connection.ts",
+    "docker:mongodb-atlas:restart:clean": "docker rm -f mongodb-atlas-payload-test 2>/dev/null; docker compose -f test/__helpers/shared/db/mongodb-atlas/docker-compose.yml down -v && pnpm docker:mongodb-atlas:start",
+    "docker:mongodb-atlas:start": "docker compose -f test/__helpers/shared/db/mongodb-atlas/docker-compose.yml up -d --wait",
+    "docker:mongodb-atlas:stop": "docker compose -f test/__helpers/shared/db/mongodb-atlas/docker-compose.yml down",
+    "docker:mongodb-atlas:test": "pnpm runts test/__helpers/shared/db/mongodb-atlas/run-test-connection.ts",
     "docker:mongodb:restart": "pnpm docker:mongodb:stop && pnpm docker:mongodb:start",
-    "docker:mongodb:restart:clean": "docker rm -f mongodb-payload-test mongot-payload-test 2>/dev/null; docker compose -f test/helpers/db/mongodb/docker-compose.yml down -v && pnpm docker:mongodb:start",
-    "docker:mongodb:start": "docker compose -f test/helpers/db/mongodb/docker-compose.yml up -d --wait",
-    "docker:mongodb:stop": "docker rm -f mongodb-payload-test mongot-payload-test 2>/dev/null; docker compose -f test/helpers/db/mongodb/docker-compose.yml down",
-    "docker:mongodb:test": "pnpm runts test/helpers/db/mongodb/run-test-connection.ts",
+    "docker:mongodb:restart:clean": "docker rm -f mongodb-payload-test mongot-payload-test 2>/dev/null; docker compose -f test/__helpers/shared/db/mongodb/docker-compose.yml down -v && pnpm docker:mongodb:start",
+    "docker:mongodb:start": "docker compose -f test/__helpers/shared/db/mongodb/docker-compose.yml up -d --wait",
+    "docker:mongodb:stop": "docker rm -f mongodb-payload-test mongot-payload-test 2>/dev/null; docker compose -f test/__helpers/shared/db/mongodb/docker-compose.yml down",
+    "docker:mongodb:test": "pnpm runts test/__helpers/shared/db/mongodb/run-test-connection.ts",
     "docker:postgres:restart": "pnpm docker:postgres:stop && pnpm docker:postgres:start",
-    "docker:postgres:restart:clean": "docker rm -f postgres-payload-test 2>/dev/null; docker compose -f test/helpers/db/postgres/docker-compose.yml down -v && pnpm docker:postgres:start",
-    "docker:postgres:start": "docker compose -f test/helpers/db/postgres/docker-compose.yml up -d --wait",
-    "docker:postgres:start:clean": "docker pull ghcr.io/payloadcms/postgis-vector:latest && docker compose -f test/helpers/db/postgres/docker-compose.yml down -v && docker compose -f test/helpers/db/postgres/docker-compose.yml up -d --wait",
-    "docker:postgres:stop": "docker rm -f postgres-payload-test 2>/dev/null; docker compose -f test/helpers/db/postgres/docker-compose.yml down",
+    "docker:postgres:restart:clean": "docker rm -f postgres-payload-test 2>/dev/null; docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml down -v && pnpm docker:postgres:start",
+    "docker:postgres:start": "docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml up -d --wait",
+    "docker:postgres:start:clean": "docker pull ghcr.io/payloadcms/postgis-vector:latest && docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml down -v && docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml up -d --wait",
+    "docker:postgres:stop": "docker rm -f postgres-payload-test 2>/dev/null; docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml down",
     "docker:restart": "pnpm docker:stop --remove-orphans && pnpm docker:start",
     "docker:start": "docker compose -f test/docker-compose.yml up -d",
     "docker:stop": "docker compose -f test/docker-compose.yml down",

test/helpers/e2e/auth/login.ts → test/__helpers/e2e/auth/login.ts

@@ -4,10 +4,10 @@ import type { Page } from 'playwright/test'
 import { formatAdminURL, wait } from 'payload/shared'
 import { expect } from 'playwright/test'
 
-import type { AdminRoutes } from '../../../helpers.js'
+import type { AdminRoutes } from '../helpers.js'
 
 import { devUser } from '../../../credentials.js'
-import { getRoutes } from '../../../helpers.js'
+import { getRoutes } from '../helpers.js'
 import { POLL_TOPASS_TIMEOUT } from '../../../playwright.config.js'
 import { openNav } from '../toggleNav.js'
 

test/helpers/e2e/auth/logout.ts → test/__helpers/e2e/auth/logout.ts

@@ -1,10 +1,10 @@
 import type { Page } from 'playwright'
 
-import { getRoutes } from 'helpers.js'
 import { formatAdminURL } from 'payload/shared'
 import { POLL_TOPASS_TIMEOUT } from 'playwright.config.js'
 import { expect } from 'playwright/test'
 
+import { getRoutes } from '../helpers.js'
 import { openNav } from '../toggleNav.js'
 
 export const logout = async (page: Page, serverURL: string) => {

test/helpers/e2e/columns/reorderColumns.ts → test/__helpers/e2e/columns/reorderColumns.ts

@@ -3,7 +3,7 @@ import type { Page } from '@playwright/test'
 import { expect } from '@playwright/test'
 import { wait } from 'payload/shared'
 
-import { exactText } from '../../../helpers.js'
+import { exactText } from '../helpers.js'
 
 export const reorderColumns = async (
   page: Page,

test/helpers/e2e/columns/toggleColumn.ts → test/__helpers/e2e/columns/toggleColumn.ts

@@ -2,7 +2,7 @@ import type { Locator, Page } from '@playwright/test'
 
 import { expect } from '@playwright/test'
 
-import { exactText } from '../../../helpers.js'
+import { exactText } from '../helpers.js'
 import { openListColumns } from './openListColumns.js'
 import { waitForColumnInURL } from './waitForColumnsInURL.js'
 

test/helpers/e2e/copyPasteField.ts → test/__helpers/e2e/copyPasteField.ts

@@ -3,7 +3,7 @@ import type { Page } from '@playwright/test'
 import { expect } from '@playwright/test'
 import { wait } from 'payload/shared'
 
-import { closeAllToasts } from '../../helpers.js'
+import { closeAllToasts } from './helpers.js'
 
 export async function copyPasteField({
   fieldName,

test/helpers/e2e/fields/blocks/addBlock.ts → test/__helpers/e2e/fields/blocks/addBlock.ts

@@ -1,8 +1,8 @@
 import type { Locator, Page } from '@playwright/test'
 
 import { expect } from '@playwright/test'
-import { exactText } from 'helpers.js'
 
+import { exactText } from '../../helpers.js'
 import { openArrayRowActions } from '../array/openArrayRowActions.js'
 import { openBlocksDrawer } from './openBlocksDrawer.js'
 

test/helpers/folders/createFolderDoc.ts → test/__helpers/e2e/folders/createFolderDoc.ts

@@ -1,7 +1,7 @@
 import { expect, type Page } from '@playwright/test'
 
-import { closeAllToasts } from '../../helpers.js'
-import { selectInput } from '../../helpers/e2e/selectInput.js'
+import { closeAllToasts } from '../helpers.js'
+import { selectInput } from '../selectInput.js'
 export const createFolderDoc = async ({
   folderName,
   page,

test/helpers/e2e/goToListDoc.ts → test/__helpers/e2e/goToListDoc.ts

@@ -2,7 +2,7 @@ import type { Page } from '@playwright/test'
 
 import { formatAdminURL } from 'payload/shared'
 
-import type { AdminUrlUtil } from '../../helpers/adminUrlUtil.js'
+import type { AdminUrlUtil } from '../shared/adminUrlUtil.js'
 
 import { getRowByCellValueAndAssert } from './getRowByCellValueAndAssert.js'
 

test/helpers/e2e/groupBy/addGroupBy.ts → test/__helpers/e2e/groupBy/addGroupBy.ts

@@ -1,8 +1,8 @@
 import type { Locator, Page } from '@playwright/test'
 
 import { expect } from '@playwright/test'
-import { exactText } from 'helpers.js'
 
+import { exactText } from '../helpers.js'
 import { openGroupBy } from './openGroupBy.js'
 
 export const addGroupBy = async (

test/helpers.ts → test/__helpers/e2e/helpers.ts

@@ -13,7 +13,7 @@ import { defaults } from 'payload'
 import { formatAdminURL, wait } from 'payload/shared'
 import { setTimeout } from 'timers/promises'
 
-import { POLL_TOPASS_TIMEOUT } from './playwright.config.js'
+import { POLL_TOPASS_TIMEOUT } from '../../playwright.config.js'
 
 export type AdminRoutes = NonNullable<NonNullable<Config['admin']>['routes']>
 

test/helpers/e2e/live-preview/selectLivePreviewZoom.ts → test/__helpers/e2e/live-preview/selectLivePreviewZoom.ts

@@ -1,9 +1,10 @@
 import type { Page } from 'playwright'
 
-import { exactText } from 'helpers.js'
 import { POLL_TOPASS_TIMEOUT } from 'playwright.config.js'
 import { expect } from 'playwright/test'
 
+import { exactText } from '../helpers.js'
+
 export const selectLivePreviewZoom = async (page: Page, zoomLabel: string) => {
   const zoomSelector = page.locator('.live-preview-toolbar-controls__zoom button.popup-button')
 

test/helpers/e2e/navigateToDoc.ts → test/__helpers/e2e/navigateToDoc.ts

@@ -1,8 +1,8 @@
 import type { Page } from '@playwright/test'
 
-import type { AdminUrlUtil } from '../adminUrlUtil.js'
+import type { AdminUrlUtil } from '../shared/adminUrlUtil.js'
 
-import { waitForFormReady } from '../../helpers.js'
+import { waitForFormReady } from './helpers.js'
 
 export const goToFirstCell = async (page: Page, serverURL: string) => {
   const cellLink = page.locator(`tbody tr:first-child td a`).first()

test/helpers/e2e/preferences.ts → test/__helpers/e2e/preferences.ts

@@ -1,7 +1,8 @@
-import type { PayloadTestSDK } from 'helpers/sdk/index.js'
-import type { GeneratedTypes } from 'helpers/sdk/types.js'
 import type { TypedUser, User } from 'payload'
 
+import type { PayloadTestSDK } from '../shared/sdk/index.js'
+import type { GeneratedTypes } from '../shared/sdk/types.js'
+
 export const upsertPreferences = async <
   TConfig extends GeneratedTypes<any>,
   TGeneratedTypes extends GeneratedTypes<any>,

test/helpers/e2e/selectInput.ts → test/__helpers/e2e/selectInput.ts

@@ -1,6 +1,6 @@
 import { expect, type Locator } from '@playwright/test'
 
-import { exactText } from '../../helpers.js'
+import { exactText } from './helpers.js'
 
 type SelectReactOptionsParams = {
   filter?: string // Optional filter text to narrow down options

test/helpers/e2e/sort/moveRow.ts → test/__helpers/e2e/sort/moveRow.ts

@@ -2,7 +2,7 @@ import type { Locator, Page } from 'playwright'
 
 import { expect } from 'playwright/test'
 
-import { closeAllToasts } from '../../../helpers.js'
+import { closeAllToasts } from '../helpers.js'
 
 export async function moveRow(
   page: Page,

test/helpers/e2e/toggleListMenu.ts → test/__helpers/e2e/toggleListMenu.ts

@@ -1,7 +1,8 @@
 import type { Page } from '@playwright/test'
 
 import { expect } from '@playwright/test'
-import { exactText } from 'helpers.js'
+
+import { exactText } from './helpers.js'
 
 export async function openListMenu({ page }: { page: Page }) {
   const listMenu = page.locator('#list-menu')

test/helpers/e2e/waitForAutoSaveToRunAndComplete.ts → test/__helpers/e2e/waitForAutoSaveToRunAndComplete.ts

@@ -4,7 +4,7 @@ import { expect } from '@playwright/test'
 import { wait } from 'payload/shared'
 import { POLL_TOPASS_TIMEOUT } from 'playwright.config.js'
 
-import { closeAllToasts } from '../../helpers.js'
+import { closeAllToasts } from './helpers.js'
 
 export async function waitForAutoSaveToRunAndComplete(
   page: Locator | Page,

test/helpers/vitest.ts → test/__helpers/int/vitest.ts

@@ -2,8 +2,11 @@ import type { SuiteFactory, TestFunction } from 'vitest'
 
 import { describe as vitestDescribe, it as vitestIt } from 'vitest'
 
-import { type DatabaseAdapterType, getCurrentDatabaseAdapter } from '../generateDatabaseAdapter.js'
-import { mongooseList } from './isMongoose.js'
+import {
+  type DatabaseAdapterType,
+  getCurrentDatabaseAdapter,
+} from '../../generateDatabaseAdapter.js'
+import { mongooseList } from '../shared/isMongoose.js'
 
 type ItOptions = {
   /**

test/helpers/NextRESTClient.ts → test/__helpers/shared/NextRESTClient.ts

@@ -11,7 +11,7 @@ import {
 } from '@payloadcms/next/routes'
 import * as qs from 'qs-esm'
 
-import { devUser } from '../credentials.js'
+import { devUser } from '../../credentials.js'
 import { getFormDataSize } from './getFormDataSize.js'
 
 type ValidPath = `/${string}`

test/helpers/adminUrlUtil.ts → test/__helpers/shared/adminUrlUtil.ts

@@ -1,8 +1,8 @@
 import type { Config } from 'payload'
+import { formatAdminURL } from 'payload/shared'
 
 // IMPORTANT: ensure that imports do not contain React components, etc. as this breaks Playwright tests
 // Instead of pointing to the bundled code, which will include React components, use direct import paths
-import { formatAdminURL } from '../../packages/ui/src/utilities/formatAdminURL.js' // eslint-disable-line payload/no-relative-monorepo-imports
 
 export class AdminUrlUtil {
   account: string

test/helpers/assertToastErrors.ts → test/__helpers/shared/assertToastErrors.ts

@@ -2,7 +2,7 @@ import type { Page } from '@playwright/test'
 
 import { expect } from '@playwright/test'
 
-import { closeAllToasts } from '../helpers.js'
+import { closeAllToasts } from '../e2e/helpers.js'
 
 export async function assertToastErrors({
   page,

test/helpers/reset.ts → test/__helpers/shared/clearAndSeed/reset.ts

@@ -1,7 +1,7 @@
 import type { DrizzleAdapter } from '@payloadcms/drizzle/types'
 import type { Payload } from 'payload'
 
-import { isMongoose } from './isMongoose.js'
+import { isMongoose } from '../isMongoose.js'
 
 export async function resetDB(_payload: Payload, collectionSlugs: string[]) {
   if (isMongoose(_payload) && 'collections' in _payload.db && collectionSlugs.length > 0) {

test/helpers/seed.ts → test/__helpers/shared/clearAndSeed/seed.ts

@@ -3,7 +3,7 @@ import * as os from 'node:os'
 import path from 'path'
 import { type Payload } from 'payload'
 
-import { isErrorWithCode } from './isErrorWithCode.js'
+import { isErrorWithCode } from '../isErrorWithCode.js'
 import { resetDB } from './reset.js'
 import { createSnapshot, dbSnapshot, restoreFromSnapshot, uploadsDirCache } from './snapshot.js'
 

test/helpers/snapshot.ts → test/__helpers/shared/clearAndSeed/snapshot.ts

@@ -6,7 +6,7 @@ import type { Payload } from 'payload'
 
 import { sql } from 'drizzle-orm'
 
-import { isMongoose } from './isMongoose.js'
+import { isMongoose } from '../isMongoose.js'
 
 export const uploadsDirCache: {
   [key: string]: {

test/helpers/db/mongodb-atlas/run-test-connection.ts → test/__helpers/shared/db/mongodb-atlas/run-test-connection.ts

@@ -2,7 +2,7 @@
  * Test script to verify MongoDB Atlas Local connection and vector search functionality
  *
  * Usage:
- *   pnpm tsx test/helpers/db/mongodb-atlas/test-connection.ts
+ *   pnpm tsx test/__helpers/shared/db/mongodb-atlas/test-connection.ts
  */
 
 import { testConnection } from '../mongodb/test-connection.js'

test/helpers/db/mongodb/run-test-connection.ts → test/__helpers/shared/db/mongodb/run-test-connection.ts

@@ -2,7 +2,7 @@
  * Test script to verify MongoDB connection, replica set, and transaction functionality
  *
  * Usage:
- *   pnpm tsx test/helpers/db/mongodb/run-test-connection.ts
+ *   pnpm tsx test/__helpers/shared/db/mongodb/run-test-connection.ts
  */
 
 import { testConnection } from './test-connection.js'

test/helpers/getNextRootDir.ts → test/__helpers/shared/getNextRootDir.ts

@@ -2,7 +2,7 @@ import fs from 'fs'
 import path, { resolve } from 'path'
 import { fileURLToPath } from 'url'
 
-import { adminRoute as rootAdminRoute } from '../admin-root/shared.js'
+import { adminRoute as rootAdminRoute } from '../../admin-root/shared.js'
 
 const filename = fileURLToPath(import.meta.url)
 const dirname = path.dirname(filename)
@@ -17,7 +17,7 @@ export function getNextRootDir(testSuite?: string) {
    * Handle test suites that have their own app directory
    */
   if (testSuite) {
-    const testSuiteDir = resolve(dirname, `../${testSuite}`)
+    const testSuiteDir = resolve(dirname, `../../${testSuite}`)
 
     let hasNextConfig = false
 
@@ -56,13 +56,13 @@ export function getNextRootDir(testSuite?: string) {
    */
   if (process.env.PAYLOAD_TEST_PROD === 'true') {
     return {
-      rootDir: path.resolve(dirname, '..'),
+      rootDir: path.resolve(dirname, '..', '..'),
       adminRoute,
     }
   }
 
   return {
-    rootDir: path.resolve(dirname, '..', '..'),
+    rootDir: path.resolve(dirname, '..', '..', '..'),
     adminRoute,
   }
 }

test/helpers/initPayloadInt.ts → test/__helpers/shared/initPayloadInt.ts

@@ -4,7 +4,7 @@ import type { GeneratedTypes, Payload, SanitizedConfig } from 'payload'
 import path from 'path'
 import { getPayload } from 'payload'
 
-import { runInit } from '../runInit.js'
+import { runInit } from '../../runInit.js'
 import { getSDK } from './getSDK.js'
 import { NextRESTClient } from './NextRESTClient.js'
 

test/__helpers/shared/removeFiles.ts

@@ -0,0 +1,15 @@
+import fs from 'fs'
+
+/**
+ * Remove all files in a directory recursively, but keep the directory itself
+ * if it exists.
+ */
+export const removeFiles = (dir: string) => {
+  if (!fs.existsSync(dir)) {
+    return
+  }
+
+  fs.readdirSync(dir).forEach((f) => {
+    return fs.rmSync(`${dir}/${f}`, { recursive: true })
+  })
+}

test/helpers/rest.ts → test/__helpers/shared/rest.ts

@@ -3,7 +3,7 @@ import type { PaginatedDocs, TypedUser, Where } from 'payload'
 
 import * as qs from 'qs-esm'
 
-import { devUser } from '../credentials.js'
+import { devUser } from '../../credentials.js'
 
 type Args = {
   defaultSlug: string