# Write API Tests for a Strapi App

Yes. An agent adds Jest and Supertest tests that boot your Strapi app on a throwaway SQLite file and check routes, populate rules and permissions, in a PR.

[Run this on Rush](https://cloud.getrush.ai/run/write-api-tests/strapi/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Set Up GitHub Actions CI for a Strapi App](https://getrush.ai/run/add-github-actions-ci/strapi/)
- [Migrate a Strapi App From SQLite to PostgreSQL](https://getrush.ai/run/migrate-sqlite-to-postgres/strapi/)
- [Upgrade Strapi to the Latest Version](https://getrush.ai/run/upgrade-strapi/strapi/)

## The same job on other stacks

- [Write API Tests for an Axum App](https://getrush.ai/run/write-api-tests/axum/)
- [Write API Tests for a Django REST Framework API](https://getrush.ai/run/write-api-tests/django-rest-framework/)
- [Write API Tests for a Flask-HTTPAuth Token API](https://getrush.ai/run/write-api-tests/flask-httpauth/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
