What the agent does
The agent starts by separating what needs a database from what does not. In an app like payloadcms/website there is no test runner and no test script; the scripts are dev, build, lint and Payload's generators. A full integration suite would need MongoDB and the environment that .env.example lists. But the logic that decides who can read what is plain TypeScript: src/access/isAdmin.ts, isAdminOrSelf.ts and publishedOnly.ts are functions of { req: { user } }, src/access.ts holds checkRole and canUserMangeProject, and src/utilities has helpers such as formatSlug, deepMerge, getRelativeDate and checkTeamRoles. Those can be tested today.
It adds Vitest as a dev dependency with the Node environment and a config that resolves the path aliases in tsconfig.json, since modules import each other through names like @root/ and @cloud/. Test files are named *.spec.ts beside their module. tsconfig.json includes every .ts file, so the type-aware lint and the type-check cover the new files with no config change. A test script runs the suite. Install uses pnpm at the version pinned in packageManager and the Node major from mise.toml.
The access tests assert on what the functions return, not just whether it is truthy. isAdminOrSelf returns true for an admin, false for an anonymous request, and for any other signed-in user a query object limiting id to their own; a test that only checked for a truthy result would pass if someone replaced the query with true. publishedOnly returns a query on _status for everyone but admins. canUserMangeProject allows an admin, allows a team member only with the owner role, accepts the team as an id or as a populated object, and refuses when the project has no team.
The helpers get their boundaries. formatSlug replaces spaces, strips other punctuation and lowercases, and falls back to another field only on create. deepMerge replaces arrays and merges a nested object only when the first argument already has that key. getRelativeDate reads the clock, so the tests freeze time and walk the thresholds between days, weeks, months and years, including a date in the future. extractDescription strips tags and keeps the first twenty words. The docs-feedback vote handler takes a request object, so it is called with a stub: a bad body answers 400 without touching the model, a good one issues a single increment with upsert, and a thrown error answers 500. The agent runs pnpm test, pnpm lint and pnpm exec tsc.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add unit tests to this Payload CMS app and open a pull request. Read package.json, pnpm-workspace.yaml, mise.toml, tsconfig.json (the paths aliases), eslint.config.js, src/access.ts, every file under src/access, src/utilities and src/hooks, src/scripts/docsFeedbackVote.ts, src/collections/CommunityHelp/extract-description.ts, src/collections/Docs/branchForVersion.ts and the access block of every collection first. List the modules that can be tested without a database, a network call or Next.js, and the ones that cannot and why. Install pnpm at the version in packageManager and the Node major in mise.toml, run pnpm install, and run pnpm lint and pnpm exec tsc once before changing anything, keeping the output. Add Vitest as a devDependency with the node environment, a config that resolves the tsconfig path aliases, and a test script; add nothing else unless the alias resolution needs one plugin. Name test files *.spec.ts beside the module they test. Write tests for: isAdmin, isAdminOrSelf and publishedOnly and their field-level variants, asserting the exact return value for an admin, another signed-in user and an anonymous request; checkRole and canUserMangeProject for every branch; formatSlug for a string value, the create fallback and an update with no value; deepMerge for nested objects, arrays and a key missing from the first argument; getRelativeDate with the clock frozen at each threshold and for a future date; checkTeamRoles; extractDescription; the functions in branchForVersion.ts; and the docs-feedback vote handler with a stubbed request for an invalid body, a valid vote and a thrown error. Do not start MongoDB, do not import payload.config.ts, and do not change files outside the tests, the config and package.json. Where behaviour looks unintended, test what the code does and list it. Run pnpm test, pnpm lint and pnpm exec tsc until they pass or match the baseline, and open a pull request with their output and a table of module and cases.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds a Vitest config, a test script, the dev dependency with its lockfile change, and *.spec.ts files next to the modules they cover. No source file changes. The description has a table of module, cases and what each case pins, then the output of pnpm test, pnpm lint and the type-check, with the lint and type-check results compared against the baseline taken before any edit so a pre-existing warning is not blamed on the tests.
A second list records what the reading found. In this project that would include extractDescription holding twenty words in a variable named for fifteen, getRelativeDate answering with a calendar date for anything in the future, and deepMerge dropping the first argument's array when the second has the same key. None is necessarily wrong. Each has a test that states the current behaviour and a line reference, so a later change to it is visible in a diff.
It also lists what it did not cover and why: collection hooks that call req.payload, the endpoints that fetch from GitHub or Discord, and anything that imports the full config need a database or a network and belong to an integration suite. A reviewer checks that the access tests compare whole return values, that the frozen clock is restored after each test, and that no spec imports payload.config.ts, which would pull the whole app and its environment into a unit run.
Run it on every week
Access functions and helpers accumulate quietly, so a weekly pass keeps the suite level with the code. In the Project that holds the repository, create an automation with a schedule trigger, cron set to 0 3 * * 1 with your timezone, and this page's request as the prompt with one more sentence: cover only modules under src/access, src/utilities and src/hooks that have no *.spec.ts beside them, and if every one has, end with one line saying so and open nothing. The automation has its own max runs per hour.
The first run is better started by hand, because it adds the runner and you will want to review that choice once. Send the body to POST /o/{org}/sessions with your repository in resources and a request_id that is a fresh UUID, so a retried request returns the same run. After that pull request merges, the scheduled runs only add spec files.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
Projects with a CMS and a front end in one folder often have no tests at all, because the obvious kind, booting the whole app against a database, is heavy to set up and slow to run. The cheap kind gets skipped along with it. Yet the access functions are a few lines each, take a plain object and return a value, and are the code where a one-word change exposes data. Testing them takes no infrastructure. It takes someone to read each branch and write down what it returns, which is unglamorous and exactly what an agent can do without supervision.
Running it in a Rush sandbox keeps the result honest. The install is clean, with the pinned pnpm and Node, so alias resolution and ESM settings either work from scratch or fail where you can see them, not on a machine with a warm cache. The lint and type-check baseline is taken before the first edit and kept in the transcript with every later command. The pull request comes back with that evidence attached, and the sandbox parks afterwards so a follow-up asking for one more module starts where the run left off.
Frequently asked questions
Why Vitest and not Jest?
The app is an ESM package, type is module in package.json, written in TypeScript with path aliases. Vitest runs that without a transform to configure. If your team standardises on Jest, say so in the prompt; the tests themselves barely change. Note that the ESLint config in this repository ignores jest.config.js, which suggests either would fit.
Do these tests need MongoDB?
No. They call exported functions with plain objects: a req with a user, a field hook's arguments, a stubbed request for the vote handler. The request forbids importing payload.config.ts or starting a database. That keeps the suite fast enough to run on every commit.
How do you test an access function without Payload running?
An Access function is called by Payload with an object that contains the request, and returns a boolean or a query. A test builds that object by hand, with a user that has the admin role, a user without it, or no user, and compares the return value. That is the same contract Payload uses, so the test is faithful without the framework.
Can it add integration tests for collections and hooks as well?
Yes, as a separate run. Those need a MongoDB, so the agent installs Docker in its sandbox, starts dockerd, runs a MongoDB container and boots Payload against it with a test secret. That suite is slower and needs a decision about seed data, which is why this request keeps to unit tests.
Will the tests run in CI?
They will once a workflow calls pnpm test. This repository's only workflow reacts to Payload releases, so the request stops at the script. Name a workflow in the prompt, or ask for a new one, and the agent adds a job that installs with pnpm and runs lint, the type-check and the tests.