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 with this body:
{
"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"
}
]
}- 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
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.
The use case this job follows, with its automation and trigger: Write the missing tests.
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.