# Write Vitest Tests for an Astro Site

Yes. An agent adds Vitest to your Astro site with Astro's own test config, writes unit tests for the utilities behind your posts, tags and URLs, and opens a PR.

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

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

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

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

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

- [Add Analytics to an Astro Blog](https://getrush.ai/run/add-analytics/astro/)
- [Add Author Pages to an Astro Blog](https://getrush.ai/run/add-author-pages/astro/)
- [Add Giscus Comments to an Astro Blog](https://getrush.ai/run/add-giscus-comments/astro/)

## The same job on other stacks

- [Write Vitest Tests for a discord.js Bot](https://getrush.ai/run/write-vitest-tests/discord-js/)
- [Write Vitest Tests for a Next.js App](https://getrush.ai/run/write-vitest-tests/nextjs/)
- [Write Vitest Tests for Pinia Stores](https://getrush.ai/run/write-vitest-tests/pinia/)

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