What the agent does
The agent reads what the site computes before it tests anything. In an Astro site like satnaing/astro-paper, package.json pins astro 7, @astrojs/mdx, @astrojs/rss and @astrojs/sitemap, with pnpm as the package manager, and its scripts are dev, build (astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/), lint and format:check; there is no test script and no test runner in the dev dependencies. .github/workflows/ci.yml runs pnpm run lint, pnpm run format:check and pnpm run build on Node 24 with a three-minute timeout, so the only thing that checks the logic under src/utils today is the build succeeding.
That logic is small, pure and worth pinning down. src/utils/slugify.ts sends Latin strings through slugify with lower: true and strings with non-Latin characters through lodash.kebabcase, a branch chosen by a regular expression. src/utils/postFilter.ts excludes drafts always and, outside import.meta.env.DEV, excludes posts whose pubDatetime is further ahead than config.posts.scheduledPostMargin, which astro-paper.config.ts sets to fifteen minutes. getSortedPosts.ts sorts by modDatetime falling back to pubDatetime, truncated to whole seconds. getUniqueTags.ts de-duplicates tags by slug so differently cased labels collapse, then sorts with localeCompare. withBase.ts has stripLocale, stripBase and getAssetPath, all driven by import.meta.env.BASE_URL. getPostPaths.ts turns a content id and file path into a route, dropping folder segments that start with _. toTransitionName.ts makes a CSS identifier out of any title, hex-encoding non-ASCII characters and prefixing a leading digit. i18n/format.ts fills {{key}} placeholders. Each of these has edge cases the comments describe and nothing asserts.
The setup follows Astro rather than a generic Vite config. The agent adds vitest as a dev dependency and a vitest.config.ts built with getViteConfig from astro/config, so the @/* path alias from tsconfig.json, the astro:content and astro:i18n virtual modules and import.meta.env resolve the way they do in the site, and a test script in package.json. Tests go in src/utils/__tests__ and src/i18n/__tests__, one file per module. Posts are built as plain objects shaped like CollectionEntry<"posts"> with the fields src/content.config.ts declares, pubDatetime, modDatetime, draft, tags, because the collection schema is the contract; Date.now is stubbed with vi.useFakeTimers to test the scheduled-post margin on both sides, and import.meta.env.DEV and BASE_URL are stubbed with vi.stubEnv to test postFilter and withBase under a sub-path deployment.
Then the agent runs pnpm test --run, pnpm lint and pnpm format:check, since the ESLint config turns no-console into an error and Prettier runs with the Astro and Tailwind plugins, and finally pnpm build to confirm the new config does not disturb astro check. It adds a test step to ci.yml between lint and build so the suite runs on every pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Vitest to this Astro site and write unit tests for its utilities. Read package.json, astro.config.ts, astro-paper.config.ts, src/config.ts, src/content.config.ts, tsconfig.json, eslint.config.js, .prettierrc, .github/workflows/ci.yml and every file under src/utils and src/i18n first. Add vitest as a dev dependency with pnpm, a vitest.config.ts that uses getViteConfig from astro/config so the @ alias, the astro: virtual modules and import.meta.env resolve as in the site, and a test script. Write one test file per module under src/utils/__tests__ and src/i18n/__tests__: slugify for Latin and non-Latin input, postFilter for drafts and the scheduled-post margin with fake timers on both sides of the boundary and with DEV stubbed, getSortedPosts for modDatetime over pubDatetime and the whole-second truncation, getUniqueTags for case collapsing and ordering, withBase with BASE_URL stubbed to a sub-path and to the root, getPostPaths for nested folders and folders beginning with an underscore, toTransitionName for non-ASCII and leading digits, and tplStr for missing keys. Build posts as plain objects with the fields content.config.ts declares. Run pnpm test --run, pnpm lint, pnpm format:check and pnpm build, fix what they report in files you added, and add a test step to ci.yml between lint and build. Do not change any file under src other than the new test folders. Open a pull request listing each module, its cases and anything left untested with the reason.",
"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 that adds vitest.config.ts, a test script and the vitest dev dependency to package.json with the matching pnpm-lock.yaml change, a test step in .github/workflows/ci.yml, and test files under src/utils/__tests__ and src/i18n/__tests__: slugify.test.ts, postFilter.test.ts, getSortedPosts.test.ts, getUniqueTags.test.ts, withBase.test.ts, getPostPaths.test.ts, toTransitionName.test.ts and format.test.ts. No component, layout, page or utility changes.
The description lists each module with its cases, including the boundary cases the fake timers and env stubs make possible, quotes the pnpm test --run summary and the lint, format and build results, and names anything left out, such as resolveDefaultOgImagePath, which reads public/ through import.meta.glob and is better covered by the build.
A reviewer reads vitest.config.ts to confirm it is Astro's getViteConfig and not a second Vite setup, skims two test files for assertions that would catch a real regression, and merges once CI passes with its new step. The transcript keeps every test run, including any attempt where the config did not resolve an alias before the agent fixed it.
Run it on every new utility under src/utils
After the first pull request lands, a schedule trigger on an automation with this prompt, every set to 1d in your timezone, looks each night for utilities without a test file and opens a pull request only when it finds one. A github trigger on pull_request.closed.merged with branch_patterns on main does the same after each merge.
From your own server, POST /o/{org}/sessions with the repository in resources starts a run on demand; the key's webhook_url receives run.completed with data.session_url when the pull request is open.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
Adding a test runner to an Astro site is mostly about getting the virtual modules and aliases to resolve, which is a few false starts on a laptop and the same few in a sandbox, except that the sandbox keeps them in the transcript and the pull request arrives working. The utilities themselves are pure and quick to test once the config is right.
The tests pin behaviour the comments only describe: which strings go to which slug function, where the scheduled-post boundary falls, what a sub-path deployment does to asset URLs. The next change to any of those files gets a failing test instead of a broken build or a wrong URL in the sitemap.
Frequently asked questions
Why getViteConfig instead of a plain Vitest config?
Because postFilter.ts, getPostPaths.ts and withBase.ts import astro:content, astro:i18n and import.meta.env.BASE_URL, which only Astro's Vite plugin provides. getViteConfig from astro/config loads astro.config.ts and its integrations, so the tests run in the same module graph as the site.
Does it test the Astro components or pages?
Not in this run. The prompt is about the utilities, which have the logic and no coverage. Astro's container API can render .astro components in Vitest, and a follow-up prompt can add tests for Layout.astro's head tags or Pagination.astro on top of this config.
Will the scheduled-post test be flaky around the margin?
No. vi.useFakeTimers fixes Date.now, and the test sets pubDatetime just inside and just outside config.posts.scheduledPostMargin relative to that fixed time, so the boundary is asserted exactly and the test does not depend on when it runs.
Does the CI step slow the three-minute job?
The suite is a handful of pure functions and runs in seconds; the step sits between lint and build so a failing test is reported before the longer build runs. The pull request quotes the run time from the sandbox so a reviewer can judge it against the workflow's timeout-minutes.
More Astro jobs
The same job on other stacks
- Write Vitest Tests for a discord.js Bot (discord.js)
- Write Vitest Tests for a Next.js App (Next.js)
- Write Vitest Tests for Pinia Stores (Pinia)