What the agent does
The agent starts from what the app customises, because that is the code a test can protect. In a project like strapi/LaunchPad the backend under strapi/ has twelve content types, nine collections and three single types, and every controller and service is the unmodified core factory. The custom behaviour is elsewhere: six route files attach a populate middleware, config/api.ts sets a default page size of 25 and a maximum of 100 with counts on, and config/admin.ts maps a document to a preview URL. There is no test file, no test script and no test runner in package.json.
It adds a runner and a way to boot the app. Jest and Supertest go into devDependencies with a TypeScript transform, since the sources are .ts compiled as CommonJS, and a helper compiles and loads a Strapi instance once per run and hands its HTTP server to Supertest. The database needs no new config file: config/database.ts already builds the SQLite path from DATABASE_FILENAME, so the test setup points that at a file under .tmp/, which .gitignore covers, and deletes it afterwards. tsconfig.json already excludes **/*.test.*, so the tests do not end up in the production build.
The populate middlewares get the first tests because of how they work. Each one assigns a fixed tree to ctx.query.populate before the core controller runs, so whatever populate a caller sends is replaced. The tests create an article with an image, a category and an SEO component through the Document Service, request it with no query string and again with a deliberately narrow populate, and assert that both answers carry the same relations. The six types with no middleware, such as redirection and faq, are asserted the other way round: their relations come back only when asked for.
Then the rules that are easy to break without noticing. A draft article is absent from the public list and present once published. A request for locale=fr returns the French entry. A page size of 500 comes back as 100, and meta.pagination.total is present. An unauthenticated POST to a collection is refused, and so is a GET for a type whose public permission the test did not grant. The preview handler returns / for the page whose slug is homepage, /blog/<slug> for an article and nothing for a type it does not know. The tests seed their own few records and never import the demo export, which AGENTS.md says wipes existing data.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add API tests to the Strapi backend in strapi/ and open a pull request. Read AGENTS.md, strapi/package.json, strapi/tsconfig.json, strapi/.env.example, strapi/.gitignore, every file under strapi/config, and for every content type under strapi/src/api its schema.json, routes and middlewares first. List which routes attach a middleware and what each one does. Enable Corepack, yarn install at the root and in strapi/, copy .env.example to .env and run yarn build once before changing anything. Add Jest, Supertest and a TypeScript transform as devDependencies of strapi/ only, a jest config, and a test script. Write a helper that compiles and loads one Strapi instance for the run, uses a SQLite file under .tmp set through DATABASE_FILENAME, and destroys the instance and deletes the file at the end. Do not import the demo export; create the few records each test needs through the Document Service, and grant the public role find and findOne on the types under test in the helper. Write tests under strapi/tests for: each populate middleware returning its relations with no query string and overriding a narrower populate sent by the caller; a type without a middleware returning relations only when asked; drafts hidden and published entries listed; locale=fr returning the localized entry; the default page size, the maximum page size and the total count from config/api.ts; an unauthenticated write refused; a type with no public permission refused; and the preview handler in config/admin.ts for the homepage, an article and an unknown type. Do not change files under strapi/src or strapi/config; where behaviour looks unintended, test what the code does and list it. Run yarn test and yarn build in strapi/ until both pass, run yarn check:format at the root, and open a pull request with the test output and a table of route, behaviour and test.",
"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 tests folder under strapi/, a Jest config, the new devDependencies with the lockfile change that follows, and a test script. No file under strapi/src or strapi/config changes. The description has a table with one row per behaviour: the route, what the app promises there and the test that holds it to that. Below it is the output of yarn test, of yarn build in strapi/, and of yarn check:format at the root, since the repository formats with Prettier and a pre-commit hook.
A second list holds what the reading turned up and the tests now record. In this project that includes the fact that a client cannot narrow populate on six content types, so every list request for pages carries the full dynamic-zone tree, and that the preview path mapping exists twice, once in config/admin.ts and once in config/env/production/admin.ts, where only the first is exercised when the tests run in the default environment. Whether either should change is your call; the pull request names the files and lines.
A reviewer checks that the helper really uses a separate database file and tears it down, that permissions are granted in the test setup and not by loosening anything in the app, and that no test depends on record ids or on the order tests run in. It is worth running yarn test twice locally. A suite that passes once and fails the second time has left state behind.
Run it on every issue labelled needs-tests
Content types arrive one at a time, usually with a route tweak and no test. In the Project that holds the repository, create an automation with a github trigger on issues.labeled and needs-tests in its labels, and this page's request as the prompt with one more sentence: write tests only for the content type the issue names, in a new file, reusing the existing helper. The trigger puts the issue after the prompt and fills in nothing. It fires only for an issue that an owner, member or collaborator opened, so a label on an outside user's issue starts nothing.
To cover an existing backend in one go, start one run per content type from a script: POST /o/{org}/sessions with the type's name written into input, the repository in resources, and a request_id that is a UUID v5 of the repository's full name and the type's API id. Run the helper-and-config pull request first and merge it, so the per-type runs each add one file and do not all create the same Jest config.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
Most of a Strapi backend is configuration, and configuration is exactly what breaks silently. A populate tree edited for one front-end page changes every response for that type. A permission ticked in the admin panel exists only in a database. A page-size cap is one line nobody rereads. None of these has a compiler to complain, and with four front ends reading the same API, the first sign is a blank section on a site. Tests that boot the real app and make real HTTP requests are the only check that sees them, and setting that up is the dull part: a runner, a boot helper, a disposable database, permissions for the test role.
The agent does the setup and the first round of tests in its own sandbox, where a fresh yarn install and a clean .tmp folder show whether the suite stands on its own. Each command and its output stays in the run's transcript, so when the pull request says a suite passed you can read the run that showed it. And because one run handles one content type, a backlog of twelve can be worked through by several runs at once.
Frequently asked questions
Do the tests need a running Strapi server or Postgres?
No. The helper loads Strapi inside the Jest process and passes its HTTP server to Supertest, so nothing listens on port 1337. The database is a SQLite file created for the run through the DATABASE_FILENAME variable the app's own config already reads. If production runs on Postgres and you want the suite to match, ask for it and the agent installs PostgreSQL in its sandbox and sets DATABASE_CLIENT.
Why not load the demo data and test against that?
The export holds 191 entities and 115 assets according to the repository's notes, and importing it wipes whatever is there. Tests that depend on it are slow and break when an editor changes the demo. Each test creates the two or three records it asserts on, which also documents what the behaviour depends on.
How does it handle permissions, which live in the database?
A fresh test database has no public permissions, so every content route answers 403 until one is granted. The helper grants the public role find and findOne on the types under test, and one test leaves a type ungranted on purpose to assert the refusal. That keeps the suite independent of whatever your admin panel has ticked.
Can it use Vitest instead of Jest?
Yes, say so in the prompt. The backend compiles to CommonJS and Strapi's own guidance uses Jest with Supertest, so that is the default here. With Vitest the helper is the same; only the config file and the transform differ.
Does it add the tests to CI?
This request stops at a test script, because the repository's only workflow triggers a deploy and adding a checks workflow is its own decision. If you already have one, name it in the prompt and the agent adds a step that runs yarn test in strapi/ after the install.
More Strapi jobs
The same job on other stacks
- Write API Tests for an Axum App (Axum)
- Write API Tests for a Django REST Framework API (Django REST Framework)
- Write API Tests for a Flask-HTTPAuth Token API (Flask-HTTPAuth)