What the agent does
The agent reads the site before it installs anything. In a site like gatsbyjs/gatsby-starter-blog, package.json pins gatsby to the 5.14 line with react and react-dom on 18, a package-lock.json, Prettier as the only dev dependency, and a test script that prints a reminder to write tests with a link to the Gatsby unit-testing guide and exits with code 1. There is no Jest, no Babel config and no .github directory. gatsby-browser.js imports two font packages, normalize.css, style.css and the Prism theme, which tells the agent that CSS and font imports must be mapped away under Jest. .prettierrc sets semi: false and arrowParens: avoid, so new files follow that style.
Then it reads what there is to test. src/components/layout.js renders an h1 with the site title on the root path and a plain home link elsewhere, deciding with the __PATH_PREFIX__ global that Gatsby injects at build time. src/components/bio.js calls useStaticQuery for the author name, summary and Twitter handle and renders a StaticImage. src/components/seo.js builds the document title as title | siteTitle and falls back to the site description. src/templates/blog-post.js renders the post, a Bio and previous and next links from previous and next in its data. src/pages/index.js shows a notice when there are no posts and an ordered list otherwise, and src/pages/404.js and src/pages/using-typescript.tsx are small pages with their own Head exports. gatsby-node.js holds the logic worth most: createPages queries posts sorted by date and passes each one its previousPostId and nextPostId, onCreateNode adds a slug field to every MarkdownRemark node with createFilePath, and createSchemaCustomization declares the types.
The setup follows the guide the test script links to. The agent installs jest, babel-jest, babel-preset-gatsby, jest-environment-jsdom, identity-obj-proxy, @testing-library/react and @testing-library/jest-dom with npm install --save-dev so the lockfile is updated by the same tool that made it. jest.config.js transforms .js, .jsx, .ts and .tsx through a jest-preprocess.js that uses babel-preset-gatsby, maps .css imports to identity-obj-proxy and image and font imports to a file mock, ignores node_modules, .cache and public, sets testEnvironment to jsdom and defines __PATH_PREFIX__ as an empty string in globals. A __mocks__/gatsby.js keeps the real graphql tag and replaces Link with an anchor and useStaticQuery and navigate with jest.fn(), and a __mocks__/gatsby-plugin-image.js renders StaticImage as a plain img. The test script becomes jest.
The tests are about behaviour, not snapshots. layout.test.js renders Layout with a root location and a nested one and asserts the heading appears only on the root. bio.test.js sets useStaticQuery to return an author with a name and asserts the "Written by" sentence and the Twitter link, then returns an author with no name and asserts the sentence is absent. seo.test.js asserts the composed title and the description fallback. blog-post.test.js renders the template with and without previous and next and checks the rel="prev" and rel="next" links. index.test.js covers the empty notice and the list of titles. gatsby-node.test.js calls the exported createPages with a fake graphql that returns three post ids in date order and a createPage spy, and asserts each call's path, component and the previousPostId and nextPostId chain, including the null ends; it calls onCreateNode with a MarkdownRemark node and a non-Markdown node and asserts createNodeField ran once. The agent runs npm test and npm run build before it pushes, so the Jest config and Gatsby's own Babel setup are shown not to conflict.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Set up Jest and write unit tests for this Gatsby blog, then open a pull request. Read package.json, package-lock.json, .prettierrc, gatsby-config.js, gatsby-node.js, gatsby-browser.js, gatsby-ssr.js, src/components/layout.js, src/components/bio.js, src/components/seo.js, src/templates/blog-post.js, src/pages/index.js, src/pages/404.js and src/pages/using-typescript.tsx first. Follow the Gatsby unit-testing guide the test script links to: add jest, babel-jest, babel-preset-gatsby, jest-environment-jsdom, identity-obj-proxy, @testing-library/react and @testing-library/jest-dom with npm install --save-dev, add jest.config.js with jest-preprocess.js, a file mock for images and fonts, identity-obj-proxy for css, __PATH_PREFIX__ in globals and jsdom as the environment, and add __mocks__/gatsby.js and __mocks__/gatsby-plugin-image.js. Replace the failing test script with jest. Write tests under src/__tests__ for Layout on the root and a nested path, Bio with and without an author name, Seo's title and description fallback, the blog-post template's previous and next links, the index page's empty state and post list, and gatsby-node's createPages previous and next id chain and onCreateNode slug field, using a fake graphql and spies for the actions. Match the repository's Prettier style with no semicolons. Run npm test and npm run build and paste both outputs in the pull request. Do not change any component, page or gatsby-node logic.",
"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. It adds jest.config.js, jest-preprocess.js, the loadershim.js the guide includes for the Gatsby loader global, __mocks__/file-mock.js, __mocks__/gatsby.js, __mocks__/gatsby-plugin-image.js and the test files under src/__tests__, changes the test script and the dev dependencies in package.json, and updates package-lock.json. No component, page or gatsby-node.js line changes, which a reviewer can confirm from the diff's file list.
The pull request description shows the npm test output with each test file and its cases named, and the npm run build output, so a reviewer sees that Jest's Babel transform and Gatsby's build do not fight over the same files. The run's full record at GET /o/{org}/sessions/{id}/messages keeps every install and every test run, including any first attempt the agent corrected, and GET /o/{org}/p/{project}/sessions/{id}/changes lists the changed files with their diffs.
Before merging, a reviewer checks three things: that __mocks__/gatsby.js keeps graphql as a pass-through so page queries still parse, that the gatsby-node.js test calls the real exported functions rather than a copy of their logic, and that the file mock covers the font packages imported in gatsby-browser.js. Nothing is deployed and nothing reaches the default branch until the pull request merges.
Run it on every Gatsby site with no test suite
A team with several Gatsby sites sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own package.json and components, so a site that already has Jest gets tests only, a site on gatsby-plugin-mdx gets its MDX imports mocked, and a TypeScript site gets ts-jest left out because babel-preset-gatsby already strips types. Each run opens its own pull request. A request_id per repository makes the script safe to run twice.
Give the key a webhook_url and Rush POSTs run.completed when each turn ends, with a session_url to read the pull request from; a run.failed names a run that ends in failure. A batch across many Gatsby sites can be posted at once; a key keeps max_concurrent runs in progress, four by default and up to 100, and answers the rest 202 with status: "queued", starting them oldest first when a slot frees.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
The Gatsby Jest setup is the part people put off: a Babel preset that must match the build, a gatsby mock, a global for the path prefix, and image and CSS imports that break the first run. On a laptop that is an afternoon of reading the guide between other work. On Rush the agent does it in a sandbox of its own, runs npm test and npm run build there, and pushes only when both pass.
The pull request carries its own proof. The test names say what was checked, the pasted output shows them passing, and the trajectory keeps every command, so a reviewer who has never configured Jest for Gatsby can still judge the change from the diff and the record rather than by cloning and running it.
Frequently asked questions
Why Babel and not ts-jest?
Gatsby compiles the site with its own Babel preset, and babel-preset-gatsby gives Jest the same transform, including the JSX runtime and the TypeScript syntax used by using-typescript.tsx. Adding ts-jest would mean a second compiler with its own config and a second place for the two to disagree. The agent follows the guide the repository's own test script points at.
How are useStaticQuery and StaticImage handled?
__mocks__/gatsby.js replaces useStaticQuery with jest.fn(), so each test sets the return value it needs: bio.test.js gives it an author object and seo.test.js gives it site metadata. __mocks__/gatsby-plugin-image.js renders StaticImage as an img, because the real component expects data that only the Gatsby build produces. graphql stays a pass-through so page queries continue to parse.
Does this test gatsby-node.js without running Gatsby?
Yes. gatsby-node.js exports plain functions, so the test requires the file and calls createPages with a fake graphql that resolves to three posts and an actions object whose createPage is a spy. The assertions check the path, the component and the previous and next id chain, which is where a mistake would leave a post without its neighbour links. onCreateNode is called with two node types to show the slug field is added only for Markdown.
Will it add snapshot tests?
No. Snapshots of this starter would change with every style edit and tell a reviewer nothing about behaviour. The tests assert visible text, link targets and rel attributes through Testing Library queries. If you want a snapshot of the rendered post for regression purposes, say so in the prompt and the agent adds one beside the behavioural tests.