Przejdź do treści
Biblioteka skilli
Programowanie · Testowanie

game-qa

/game-qa

Pisze i uruchamia testy gier w przeglądarce przez protokół DevTools: testy regresji wizualnej, rozgrywki i wydajności.

Repozytorium
game-creator ↗
Licencja
MIT
Ostatnia zmiana repozytorium
04.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
8
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
2
Przestarzałość

Brak sygnałów. Repozytorium zmienione 04.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pisze i uruchamia testy gier w przeglądarce przez protokół DevTools: testy regresji wizualnej, rozgrywki i wydajności.

Argumenty

/game-qa [topic]
Oryginalny opis (EN)

Game QA testing with browser tests (Chrome over the DevTools protocol, no npm dependency) — visual regression, gameplay verification and performance for browser games. Use when writing or running game tests, debugging test failures, or building QA infrastructure. This is the reference skill — use qa-game for the user-facing command.

Jak działa

  1. Performance Notes
  2. Reference Files
  3. Tech Stack
  4. Project Setup
  5. Required Directory Structure
  6. Browser Test Config
  7. Testability Requirements
  8. When Adding QA to a Game
  9. What NOT to Test (Automated)
Sekcje z nagłówków SKILL.md, w oryginale · 215 linii, 1 088 słów
Podgląd SKILL.md
---
name: game-qa
description: Game QA testing with browser tests (Chrome over the DevTools protocol, no npm dependency) — visual regression, gameplay verification and performance for browser games. Use when writing or running game tests, debugging test failures, or building QA infrastructure. This is the reference skill — use qa-game for the user-facing command.
argument-hint: "[topic]"
license: MIT
compatibility: Requires Node.js 22+ (or Bun) and Google Chrome for browser-based game testing.
metadata:
  author: OpusGameLabs
  version: 1.3.0
  tags: [game, qa, testing, cdp]
---

# Game QA with Browser Tests

You are an expert QA engineer for browser games. You use the plugin's dependency-free browser helpers (`scripts/cdp.mjs` and `scripts/browser-test.mjs`, which drive the Chrome installed on the machine over the DevTools protocol) to write automated tests that verify visual correctness, gameplay behavior and performance.

## Performance Notes

- Take your time with each step. Quality is more important than speed.
- Do not skip validation steps — they catch issues early.
- Read the full context of each file before making changes.
- Write tests that verify gameplay, not just that the page loads.

## Reference Files

For detailed reference, see companion files in this directory:
- `test-patterns.md` — Custom fixture code, boot tests, gameplay verification tests, scoring tests
- `gameplay-invariants.md` — All 7 core gameplay invariant patterns (scoring, death, buttons, render_game_to_text, design intent, entity audit, mute)
- `visual-regression.md` — Screenshot comparison tests, masking dynamic elements, performance/FPS tests, deterministic testing patterns
- `clock-control.md` — `page.clock` API patterns for frame-precise testing
- `visual-inspection.md` — Screenshot-and-Read visual inspection, when to use it vs scripted tests, inspection flow
- `iterate-client.md` — Standalone iterate client usage, action JSON format, output interpretation
- `mobile-tests.md` — Mobile input simulation and responsive layout test patterns

## Tech Stack

- **Test Runner**: `scripts/browser-test.mjs` (`test`/`expect` on `node --test`), driving Chrome through `scripts/cdp.mjs`
- **Visual Regression**: `toHaveScreenshot()` from `browser-test.mjs`
- **Accessibility**: no automated scan (axe-core is not available)
- **Build Tool Integration**: Vite dev server via `webServer` config
- **Language**: JavaScript ES modules

## Project Setup

When adding browser tests to a game project, copy the helpers from the plugin (no npm install; needs Node 22+ or Bun and Google Chrome, or set `BOOP_CHROME=/path/to/chrome`):

```bash
mkdir -p scripts
cp <plugin-root>/scripts/cdp.mjs <plugin-root>/scripts/browser-test.mjs scripts/
```

Add to `package.json` scripts:

```json
{
  "scripts": {
    "test": "node --test --test-concurrency=1 \"tests/**/*.spec.js\"",
    "test:headed": "BROWSER_TEST_HEADED=1 node --test --test-concurrency=1 \"tests/**/*.spec.js\"",
    "test:update-snapshots": "BROWSER_TEST_UPDATE_SNAPSHOTS=1 node --test --test-concurrency=1 \"tests/**/*.spec.js\""
  }
}
```

## Required Directory Structure

```
tests/
├── e2e/
│   ├── game.spec.js       # Core game tests (boot, scenes, input, score)
│   ├── visual.spec.js     # Visual regression screenshots
│   └── perf.spec.js       # Performance and FPS tests
├── fixtures/
│   ├── game-test.js       # Custom test fixture with game helpers
│   └── screenshot.css     # CSS to mask dynamic elements for visual tests
├── helpers/
│   └── seed-random.js     # Seeded PRNG for deterministic game behavior
scripts/
├── cdp.mjs                # Chrome over the DevTools protocol (copied from the plugin)
└── browser-test.mjs       # test/expect on node --test (copied from the plugin)
browser.config.mjs
```

## Browser Test Config

`browser-test.mjs` reads `timeout`, `expect`, `use`, `projects` and `webServer` (retries, workers, reporters and traces are not supported).

```js
export default {
  testDir: './tests',
  timeout: 30000,

  use: {
    baseURL: 'http://localhost:3000',
    screenshot: 'only-on-failure',
  },

  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 200,
      threshold: 0.3,
    },
  },

  projects: [
    { name: 'chromium', use: { viewport: { width: 1280, height: 720 } } },
    { name: 'mobile-chrome', use: { viewport: { width: 393, height: 851 }, deviceScaleFactor: 2.75, isMobile: true, hasTouch: true } },
  ],

  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: true,
  },
};
```

Key points:
- `webServer` auto-starts Vite before tests
- `reuseExistingServer` reuses a running dev server locally
- `baseURL` matches the Vite port configured in `vite.config.js`
- Screenshot tolerance is generous (games have minor render variance)

## Testability Requirements

For browser tests to inspect game state, the game MUST expose these globals on `window` in `main.js`:

### 1. Core globals (required)

```js
// Expose for browser QA
window.__GAME__ = game;
window.__GAME_STATE__ = gameState;
window.__EVENT_BUS__ = eventBus;
window.__EVENTS__ = Events;
```

### 2. `render_game_to_text()` (required)

Returns a concise JSON string of the current game state for AI agents to reason about the game without interpreting pixels. Must include coordinate system, game mode, score, and player state.

```js
window.render_game_to_text = () => {
  if (!game || !gameState) return JSON.stringify({ error: 'not_ready' });

  const activeScenes = game.scene.getScenes(true).map(s => s.scene.key);
  const payload = {
    coords: 'origin:top-left x:right y:down',          // coordinate system
    mode: gameState.gameOver ? 'game_over' : 'playing',
    scene: activeScenes[0] || null,
    score: gameState.score,
    bestScore: gameState.bestScore,
  };

  // Add player info when in gameplay
  const gameScene = game.scene.getScene('GameScene');
  if (gameState.started && gameScene?.player?.sprite) {
    const s = gameScene.player.sprite;
    const body = s.body;
    payload.player = {
      x: Math.round(s.x), y: Math.round(s.y),
      vx: Math.round(body.velocity.x), vy: Math.round(body.velocity.y),
      onGround: body.blocked.down,
    };
  }

  // Extend with visible entities as you add them:
  // payload.entities = obstacles.map(o => ({ x: o.x, y: o.y, type: o.type }));

  return JSON.stringify(payload);
};
```

Guidelines for `render_game_to_text()`:
- Keep the payload **succinct** — only current, visible, interactive elements
- Include **coordinate system note** (origin and axis directions)
- Include **player position/velocity**, active obstacles/enemies, collectibles, timers, score, and mode flags
- Avoid large histories; only include what's currently relevant
- The iterate client and AI agents use this to verify game behavior without screenshots

### 3. `advanceTime(ms)` (required)

Lets test scripts advance the game by a precise duration. The game loop runs normally via RAF; this waits for real time to elapse.

```js
window.advanceTime = (ms) => {
  return new Promise((resolve) => {
    const start = performance.now();
    function step() {
      if (performance.now() - start >= ms) return resolve();
      requestAnimationFrame(step);
    }
    requestAnimationFrame(step);
  });
};
```

For frame-precise control in browser tests, prefer `page.clock.install()` + `page.clock.runFor()`. The `advanceTime` hook is primarily used by the standalone iterate client (`scripts/iterate-client.js`).

For Three.js games, expose the `Game` orchestrator instance similarly.

See `test-patterns.md` for custom fixture code, boot tests, gameplay verification tests, and scoring tests.

See `gameplay-invariants.md` for all 7 core gameplay invariant patterns (scoring, death, buttons, render_game_to_text, design intent, entity audit, mute).

## When Adding QA to a Game

1. Copy the helpers: `cp <plugin-root>/scripts/cdp.mjs <plugin-root>/scripts/browser-test.mjs scripts/` (needs Node 22+ and Google Chrome)
2. Create `browser.config.mjs` with the game's dev server port
3. Expose `window.__GAME__`, `window.__GAME_STATE__`, `window.__EVENT_BUS__` in `main.js`
4. Create `tests/fixtures/game-test.js` with the `gamePage` fixture
5. Create `tests/helpers/seed-random.js` for deterministic behavior
6. Write tests in `tests/e2e/`:
   - `game.spec.js` — boot, scene flow, input, scoring, game over
   - `visual.spec.js` — screenshot regression for each scene
   - `perf.spec.js` — load time, FPS budget
7. Add npm scripts: `test`, `test:headed`, `test:update-snapshots`
8. Generate initial baselines: `npm run test:update-snapshots`

## What NOT to Test (Automated)

- **Exact pixel positions** of animated objects (non-deterministic without clock control)
- **Active gameplay screenshots** — moving objects make stable screenshots impossible; use visual inspection (screenshots + Read) instead
- **Audio playback** (the browser helper has no audio inspection; test that audio objects exist via evaluate)
- **External API calls** unless mocked (e.g., Play.fun SDK — mock with `page.route()`)
- **Subjective visual quality** — use visual inspection for "does this look good?" evaluations
Pliki w paczce (8)
  • SKILL.md 9 KB
  • clock-control.md 1 KB
  • gameplay-invariants.md 8 KB
  • iterate-client.md 3 KB
  • mobile-tests.md 2 KB
  • test-patterns.md 3 KB
  • visual-inspection.md 4 KB
  • visual-regression.md 4 KB

Wersje

W bazie nie ma innych skilli o nazwie game-qa.

Migawka bazy z 13.11.2026 · wersja paczki b723606bc01a (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100qa-game
    Dodaje do gry w przeglądarce testy wizualnej regresji, weryfikacji rozgrywki i wydajności.
  • 90browser-testing-with-devtools
    Wykorzystuje Chrome DevTools do danych na żywo: inspekcja DOM, logi konsoli, ślady sieci i profilowanie wydajności przy budowaniu i debugowaniu w przeglądarce.
  • 90browser-testing-with-devtools
    Wykorzystuje Chrome DevTools do danych na żywo: inspekcja DOM, logi konsoli, ślady sieci i profilowanie wydajności przy budowaniu i debugowaniu w przeglądarce.
  • 100chrome-devtools-cli
    Pisze skrypty powłoki i uruchamia polecenia do automatyzacji zadań w przeglądarce oraz pracy z Chrome DevTools przez CLI.
  • 100chrome-devtools-cli
    Pisze skrypty powłoki i uruchamia polecenia do automatyzacji zadań w przeglądarce oraz pracy z Chrome DevTools przez CLI.
  • 95browser-testing-with-devtools
    Testuje w prawdziwych przeglądarkach przez Chrome DevTools MCP: DOM, błędy konsoli, sieć, wydajność i wygląd wyników.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.