pnpm lint
pnpm build
pnpm preview
Read package.json before running optional scripts. The Vitest add-on provides test; the Playwright add-on provides e2e and e2e:ui. Both use Chromium. New kits prepare the matching browser automatically when you run tests locally; later runs reuse the download.
Use Updating an existing game to add missing test tools safely. A missing script is a configuration issue, not a failing game test.
With either test add-on selected, pnpm run setup prepares local HTTPS and Chromium together. Your operating system may ask you to trust a local development certificate. This does not create a cloud project or register a public domain. To prepare only the browser, run pnpm test:setup. Dependency installation itself does not download browsers or change certificate trust.
pnpm e2e:ui
pnpm e2e --grep keyboard
These commands require the Playwright add-on. The test server starts automatically at http://127.0.0.1:4173; you do not need domain setup or a running pnpm dev. Set SPAWN_E2E_HTTPS=1 to test a named HTTPS origin after local domain setup; CI always uses loopback. Change e2e/game.spec.ts to test your game's behavior.
pnpm install --frozen-lockfile
pnpm test:setup --with-deps
pnpm test
pnpm e2e
Commit your lockfile before using this CI example. CI skips automatic browser downloads and uses a loopback test server. On supported Linux runners, --with-deps installs system libraries and may require administrator access. For an already prepared offline machine, set SPAWN_SKIP_BROWSER_INSTALL=1. If a download fails, tests stop: check network/proxy access and retry pnpm test:setup.
The generated src/score.ts exports advanceScore. Its test belongs in src/score.test.ts. Test behavior players depend on, including boundary values, rather than copying the function's implementation.
import { expect, it } from "vitest"
import { advanceScore } from "./score"
it("awards the first collectible", () => {
expect(advanceScore(0)).toBe(1)
})
it("preserves the accumulated score", () => {
expect(advanceScore(41)).toBe(42)
})
Run pnpm test. Both assertions should pass with the generated score function. If you change the scoring rules, update the expected behavior deliberately. Keep coverage checks enabled and add cases for new branches.
Use the generated Playwright configuration and existing test location as your starting point. It supplies the application's test origin and server. Canvas presence is a useful smoke check, but it does not prove the player moved or the game rules worked.
import { expect, test } from "@playwright/test"
test("opens the game without an uncaught error", async ({ page }) => {
const errors: string[] = []
page.on("pageerror", error => errors.push(error.message))
await page.goto("/")
await expect(page.locator("canvas")).toBeVisible()
await page.keyboard.press("ArrowRight")
expect(errors).toEqual([])
})
Save the example as e2e/smoke.spec.ts and run pnpm e2e. Extend it with observable outcomes specific to your game: a score label changes, a restart button resets the scene, or a level-complete screen appears. Test touch controls on a phone-sized viewport when you advertise mobile support. Check audio after a user gesture.
To find a browser error, open your browser's developer tools from its menu, choose Console, and reload the game. Start with the first red error. In Network, reload again and look for failed file requests; their URLs can reveal a wrong asset path. Share the error text with your agent, without credentials.
| Symptom | Check next |
|---|
| Blank canvas | Read the first console error. Confirm the renderer initializes, the canvas has a size, and required assets load. |
|---|
| Missing artwork or sound | Inspect the failed network URL, filename case, and whether the file exists in dist. A public/ prefix is not part of the browser URL. |
|---|
| Local HTTPS does not open | Run pnpm exec dev-domains doctor and pnpm exec dev-domains urls. Follow certificate setup; check the printed origin. |
|---|
| Browser executable missing | Retry pnpm test:setup. Check network/proxy access if the download fails. |
|---|
| Works in development only | Rebuild and use pnpm preview. Check browser-visible environment variables and production asset paths. |
|---|
| Hosted source install fails | Commit an up-to-date pnpm lockfile. Check for private registries, Git dependencies, or required install scripts. |
|---|
| Old behavior after deployment | Confirm the project, active release, and URL; inspect cache/service-worker behavior in the browser. |
|---|
Fix the earliest actionable error, then rerun the same steps. Avoid changing multiple unrelated systems before you can reproduce the failure.
Open Dashboard → Deployments → release → Build logs for the working browser path. Use CLI installation to run the deployment commands below. Record the exact steps, expected result, actual result, browser/device, and whether it happens in development, preview, or the hosted release. Include the first console error and relevant failed request. For hosted builds, include the project and deployment IDs plus the failing log excerpt. Remove tokens and credentials before sharing.
pnpm dlx @spawnkit/cli status DEPLOYMENT_ID --project YOUR_PROJECT_ID
pnpm dlx @spawnkit/cli logs DEPLOYMENT_ID --project YOUR_PROJECT_ID