# Write Pytest Tests for a Litestar App

Yes. The agent reads the suite's fixtures and factories, finds the controllers and services with no tests, writes pytest tests that pass on Postgres and opens a PR.

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

## What the agent does

The agent reads how the suite is built before it writes a test, because in a Litestar app the fixtures decide whether a new test file runs at all. In an app laid out like litestar-org/litestar-fullstack, `pyproject.toml` puts the code under `src/py/app` and the tests under `src/py/tests`, runs pytest with `--strict-markers`, `-n auto` through pytest-xdist and `--cov-fail-under=65`, and declares markers such as `integration`, `endpoints`, `services` and `teams` that every test module sets in `pytestmark`. `src/py/tests/conftest.py` sets the environment before any app import, `SECRET_KEY`, `EMAIL_BACKEND=memory`, `SAQ_PROCESSES=1`, then loads `pytest_databases.docker.postgres` and builds a session-scoped async engine on the asyncpg driver against that container. `tests/integration/conftest.py` adds `seeded_db`, which loads the `role` fixture file and the `raw_users` and `raw_teams` lists from `data_fixtures.py`, a `client` built from `AsyncTestClient` with the database patched in, and `superuser_token_headers` and `user_token_headers` made with `create_access_token`. `factories.py` holds Polyfactory classes such as `UserFactory` and `TeamFactory` with helpers like `create_user_with_team`.

Then it maps what is tested against what exists. The `accounts` and `teams` domains have route and service tests under `tests/integration`, `system` has `test_health.py` and `test_health_resilience.py`, and `tests/unit` covers `lib`, `utils`, the guards and the CLI. Nothing exercises the `tags` domain: `app/domain/tags/controllers.py` serves `/api/tags` with list, get, create, update and delete, the last three behind `requires_superuser`, with filters for `id`, a `search` on `name`, limit-offset pagination of 20 and a sort on `name`, over a `TagService` whose repository is `SQLAlchemyAsyncSlugRepository` with `match_fields = ["name"]`. Nothing exercises the `admin` domain either: `/api/admin/users`, `/api/admin/teams` and `/api/admin/audit`, all guarded by `requires_superuser`, and `/api/admin/dashboard/stats` and `/activity` in `_dashboard.py`, which count users, verified users, teams and the last 24 hours of audit events through `AuditLogService.get_stats`. The services `RoleService`, `UserRoleService` and `UserOAuthAccountService` have no service tests of their own.

The agent writes tests where the existing ones live and in their style. `tests/integration/tags/routes/test_tags.py` marks `integration`, `endpoints` and a new `tags` marker added to `pyproject.toml`, uses `seeded_client` for reads and `superuser_token_headers` for writes, and covers the slug a `TagCreate` gets, the 403 a plain user receives on create, the `search` filter, the page size and the 404 after delete. `tests/integration/admin/routes/test_dashboard.py` seeds a few users and audit rows with the factories and asserts the counts `DashboardStats` returns, including that `new_users_today` moves with `created_at`. `tests/integration/accounts/services/test_role_service.py` checks `get_or_upsert` on `name`, which `seeded_db` already relies on. Each test is async under `pytest.mark.anyio` like its neighbours, and none touches production code.

The suite needs Postgres, and `pytest-databases` starts it with Docker. The sandbox has no Docker, so the agent installs it with `sudo apt-get install -y docker.io`, starts `dockerd`, then runs `uv sync --all-groups`, `make build-emails` as `.github/workflows/ci.yaml` does, and `uv run pytest src/py/tests --cov=src/py/app --cov-report=xml`. It runs `uv run pre-commit run --all-files` so ruff's `select = ["ALL"]` with the test-file exceptions in `per-file-ignores` and codespell pass before the pull request opens, and it reports the coverage line before and after.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Write the missing pytest tests for this Litestar app. Read pyproject.toml, src/py/tests/conftest.py, src/py/tests/integration/conftest.py, src/py/tests/data_fixtures.py and src/py/tests/factories.py first, then list every controller and service under src/py/app/domain and match each against src/py/tests. Write tests for the untested ones, starting with the tags controller and service, the admin dashboard, users, teams and audit controllers, and the role and user-role services, in the same directories, markers and async style as the existing tests, using the seeded_client, token header and factory fixtures. The suite needs Postgres through pytest-databases, so install Docker in the sandbox and start it first. Run `uv sync --all-groups`, `make build-emails`, `uv run pytest src/py/tests --cov=src/py/app` and `uv run pre-commit run --all-files`. Keep production code unchanged except for a new marker in pyproject.toml if you add one. Open a pull request that lists each new test file, what it covers and the coverage line before and after.",
  "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

What comes back is a pull request on its own branch that adds test modules under `src/py/tests/integration/tags/`, `src/py/tests/integration/admin/` and `src/py/tests/integration/accounts/services/`, each with its `pytestmark`, and at most one line in `pyproject.toml` for a new marker, since `--strict-markers` refuses an undeclared one. The description lists each file with the endpoints or methods it covers, quotes the final pytest summary and the coverage total before and after, and notes the pre-commit result. The repository's own `ci.yaml` runs on the branch with its Python 3.12 and 3.13 matrix.

The session keeps the record: the Docker install, the Postgres container `pytest-databases` started, every `uv run pytest` invocation with its full output, including any test that failed on a first attempt and how it was corrected, and the pre-commit run. `GET /o/{org}/sessions/{id}/messages` returns that transcript.

Before merging, a reviewer reads the new tests for two things the runner cannot judge: that an assertion checks behaviour rather than restating the implementation, and that a test which seeds audit rows cleans up through the suite's `db_cleanup` fixture so it stays independent under `-n auto`. A follow-up message to the same session, such as asking for the team invitation service next, continues on the same branch with the database still running.

## Run it on every night

In the console, add an automation to the Project with this prompt and a `schedule` trigger, a `cron` of `0 2 * * *` and your `timezone`. Each night one run reads what changed since the last, writes tests for the untested paths it finds and opens one pull request on its own branch, so the morning review is a diff of tests rather than a request to write them. A run whose new tests cannot be made to pass ends `needs_review` instead of opening a pull request that fails.

The same body sent to `POST /o/{org}/sessions` with the repository in `resources` starts one run by hand, for instance before a release, and a `request_id` that is a UUID v5 of the release tag makes a retried call return that run rather than a second pull request.

## Why run it on Rush?

Writing tests for a Litestar app is mostly plumbing: the right markers, the right client fixture, a token with the right claims, a Postgres the fixtures can reach. In a Rush sandbox the agent installs Docker for `pytest-databases`, runs the suite exactly as `ci.yaml` does, and keeps iterating until the new files pass under `-n auto`, with nothing installed on anyone's laptop.

The pull request carries its proof: the pytest summary, the coverage line and the transcript of every run, failures included. Several services in the same style can get their missing tests at the same time in separate sandboxes, and the reviewer's job shrinks to reading assertions.

## Frequently asked questions

### Does it need Docker for Postgres?

Yes, because the suite's `conftest.py` loads `pytest_databases.docker.postgres`. The sandbox has no Docker, so the agent installs `docker.io`, starts `dockerd` and lets the plugin start its container as it would on a developer machine. It does not rewrite the fixtures to use SQLite, since `aiosqlite` is in the test group only for the unit tests that need no database.

### Will it change production code to make tests pass?

No. The prompt forbids it, and the pull request contains test files plus, at most, a marker line in `pyproject.toml`. If a test exposes a bug, the agent writes the test to show the current behaviour, marks it with a comment that names the bug, and reports it in the description for a separate fix.

### What does it do about the coverage floor?

`--cov-fail-under=65` runs on every invocation, so the agent reports the total before and after its changes. New integration tests over the tags and admin controllers raise it; a run that somehow lowered it would fail its own pytest command and end `needs_review`.

### Can it write unit tests instead of integration tests?

Where the code allows it. `tests/unit` already covers guards, settings and utilities without a database, and a service method with no query, such as the slug helper in `AutoSlugServiceMixin`, fits there. Controllers that read through a repository are tested through the client against Postgres, as the existing `accounts` and `teams` tests are.

## More Litestar jobs

- [Add API Key Authentication to a Litestar App](https://getrush.ai/run/add-api-key-auth/litestar/)
- [Add Background Jobs to a Litestar App](https://getrush.ai/run/add-background-jobs/litestar/)
- [Add Response Compression to a Litestar App](https://getrush.ai/run/add-compression/litestar/)

## The same job on other stacks

- [Write Pytest Tests for a Reflex App](https://getrush.ai/run/write-pytest-tests/reflex/)
- [Write Pytest Tests for a Textual Terminal App](https://getrush.ai/run/write-pytest-tests/textual/)
- [Write pytest Tests for Celery Tasks](https://getrush.ai/run/write-pytest-tests/celery/)

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