# Test and debug your game

Check game logic, run browser tests, diagnose blank canvases, and reproduce production-only failures.

Combine automated checks with a short playthrough of the production build. A successful build alone does not verify gameplay.

<a id="baseline"></a>

## Start with the available checks

**Every generated kit**

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

**When the test add-ons are installed**

```sh
pnpm test
pnpm e2e
```

Use [Updating an existing game](https://spawnkit.cloud/docs/updating) to add missing test tools safely. A missing script is a configuration issue, not a failing game test.

<a id="browser-setup"></a>

## Prepare the test environment

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.

**Optional setup before the first test**

```sh
pnpm run setup
```

**Interactive Playwright tests**

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

**Linux CI runner; both test add-ons selected**

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

<a id="logic"></a>

## Test a game rule

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.

**src/score.test.ts; requires the Vitest add-on**

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

<a id="browser"></a>

## Verify behavior in a real browser

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.

**e2e/smoke.spec.ts; requires the Playwright add-on**

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

<a id="diagnosis"></a>

## Diagnose the first failure

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.

<a id="report"></a>

## Make a useful failure report

Open [Dashboard → Deployments → release → Build logs](https://spawnkit.cloud/docs/dashboard#deployments) for the working browser path. Use [CLI installation](https://spawnkit.cloud/docs/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.

**Retrieve deployment diagnostics**

```sh
pnpm dlx @spawnkit/cli status DEPLOYMENT_ID --project YOUR_PROJECT_ID
pnpm dlx @spawnkit/cli logs DEPLOYMENT_ID --project YOUR_PROJECT_ID
```