@1game/test
v1.27.0
Published
Vitest gameplay helpers for 1Game (gamePlayer.createGame + GameLocator + 1gamerecord artifacts)
Readme
@1game/test
Vitest logic-only gameplay helpers for 1Game — gamePlayer.createGame / Game / locators, with the test process captured as a .1gamerecord (frame comments + optional scene pins). Replay via 1gameplay bundle-player-html or 1game test ui.
Peer 版本范围以安装包的 package.json 为准;玩法测试使用 Vitest。
Install
pnpm add -D @1game/test vitestScaffold:
1game init my-game --with-e2e # empty dir → then: pnpm install && pnpm test:gameplay
1game test init # existing project (add --force to overwrite)Quick start
import { test, expect } from '@1game/test';
test('store advances', async ({ gamePlayer }) => {
const game = await gamePlayer.createGame('./src/game.tsx');
await expect(game).toMatchStore({ count: 0 });
await game.tick(10);
const plus = game.locator({ text: '+1' });
await expect(plus).toBeVisible();
await plus.click();
await expect(game).toMatchStore({ count: 1 });
});vitest.config.ts:
import { define1gameConfig } from '@1game/test/config';
export default define1gameConfig({
record: { outDir: 'test-results/records', keep: 'always' },
});After pnpm test:gameplay:
1game test ui
# serves http://127.0.0.1:<port>/ until Ctrl+C (Chrome can iframe the replay). --no-open only writes files.查询与断言
Fixture 与方法签名以发布类型为准。gamePlayer.createGame 构建入口,openGame 打开归档;render-tree locator 使用 text/name/uid,必须唯一匹配,不是 CSS selector。主入口提供 test/expect,配置从 @1game/test/config 导入;非 Vitest 脚本使用 @1game/test/session。
openGame(path, { refreshSceneUids: false }) 只从归档解析活动分支的 HEAD 身份,不启动 Worker,也不填充场景缓存;后续渲染或推进游戏时仍校验对应的可执行资源。默认打开流程会渲染并刷新场景缓存。
expect (auto frame_comments)
expect(game) / expect(locator) from @1game/test always enqueue a comment (authorId: 1game-test). Plain expect(1).toBe(1) does not.
| Matcher | Anchor |
| --------------------------------------------------------- | ------------------------------ |
| toMatchStore(partial) | none |
| toHitAt(x, y, expected?) | click point |
| toHaveLoggedError(expected?) | none (frame that logged it) |
| toBeVisible / toHaveText / toHaveName (unique node) | node bbox center scene_point |
| toBeHidden (no node) | none |
Actions also comment: tick, locator.click, input.click / keypress. Locator click uses the same scene pin.
game.assertionFrameId is the frame addressed by the latest create, step or query, and is the
default target for later assertion comments. game.annotate(body, { at }) can attach a historical
comment without changing that context. Assertion records expose frameId; identity numbers do
not describe path order.
Scenes
Events carry the scene they were stamped as, and the engine decides top-scene absorption and
pointerPassThrough forwarding from it. Omitting it stamps the first scene (the base scene in a
base + overlay layout), which is what single-scene games want. Name the scene to target an overlay:
const toastUid = game.sceneStableUids[game.sceneStableUids.length - 1]!;
await game.input.click(240, 220, { sceneStableUid: toastUid });game.input.keypress and game.hit(x, y, { sceneStableUid }) take the same option.
locator.click() stamps the matched node's scene (inspect.anchor.sceneStableUid), not the first cached scene.
Console output
game.logs({ level?, fromSeq?, toSeq? }) reads captured console.* across every frame on the
active branch path, so an error from tick 3 is still assertable after tick 5. Each row carries the
frameId it was logged on — the same coordinate as frame query --at.
Which levels get archived is decided while stepping, not while reading: createGame(entry, { captureConsole })
defaults to warn (keeps warn + error). Pass 'all' to assert on console.log, or 'off' to capture
nothing. createGame itself does not capture, so anything logged during the first render is not in the archive.
const game = await gamePlayer.createGame(ENTRY, { captureConsole: 'all' });
await game.tick(5);
await expect(game).toHaveLoggedError(/failed to load/);
const chatter = await game.logs({ level: 'log' });Record artifacts
Default keep: 'always'. Each vitest run writes test-results/records/<runId>/ plus a LATEST pointer. index.json lists tests for 1game test ui. on-failure / never remain available.
game.recordAssertion() accepts an omitted kind as an assertion. Queued records returned by game.takeAssertions() always carry the resolved kind; annotation comment bodies and manifest counts use the same captured record.
| Env | Role |
| -------------------------- | -------------------------------------------------------------- |
| ONEGAME_TEST_WORKERS | Vitest maxWorkers |
| ONEGAME_TEST_RECORD_DIR | Artifact directory (run folder when using define1gameConfig) |
| ONEGAME_TEST_RECORD_KEEP | always / on-failure / never |
| CI | Runner policy via define1gameConfig |
Requirements
- Pass the
bindStorereturned bycreateGameStoretorenderGame(..., { bindStore }). Gameplay recording does not require the game to setenableHistory: true. - Locators must match exactly one node.
