spriteforge 0.1.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- spriteforge/__init__.py +1 -0
- spriteforge/__main__.py +3 -0
- spriteforge/agents/__init__.py +0 -0
- spriteforge/agents/assets.py +109 -0
- spriteforge/agents/cancellation.py +12 -0
- spriteforge/agents/director.py +50 -0
- spriteforge/agents/models.py +63 -0
- spriteforge/agents/roles/art-director.md +15 -0
- spriteforge/agents/roles/art-reviewer.md +14 -0
- spriteforge/agents/roles/director.md +14 -0
- spriteforge/agents/roles/game-designer.md +15 -0
- spriteforge/agents/roles/level-tile-designer.md +16 -0
- spriteforge/agents/roles/librarian.md +13 -0
- spriteforge/agents/roles/menu-designer.md +15 -0
- spriteforge/agents/roles/pixel-artist.md +14 -0
- spriteforge/agents/roles/programmer.md +14 -0
- spriteforge/agents/roles/qa-playtester.md +13 -0
- spriteforge/agents/roles/sound-director.md +14 -0
- spriteforge/agents/roles.py +39 -0
- spriteforge/agents/router.py +233 -0
- spriteforge/agents/router_eval.py +145 -0
- spriteforge/agents/routing_state.py +133 -0
- spriteforge/agents/runtime.py +430 -0
- spriteforge/agents/workflow.py +389 -0
- spriteforge/app/__init__.py +0 -0
- spriteforge/app/agents_view.py +248 -0
- spriteforge/app/chat.py +114 -0
- spriteforge/app/extensions.py +115 -0
- spriteforge/app/index.html +279 -0
- spriteforge/app/local_only.py +49 -0
- spriteforge/app/server.py +358 -0
- spriteforge/app/static/assets/index-L2s1wlcp.css +1 -0
- spriteforge/app/static/assets/index-aBfzgLQl.js +71 -0
- spriteforge/app/static/assets/press-start-2p-latin-400-normal-BKfmdmKK.woff +0 -0
- spriteforge/app/static/assets/press-start-2p-latin-400-normal-xj9lRvVs.woff2 +0 -0
- spriteforge/app/static/index.html +13 -0
- spriteforge/app/static/press-start-2p-LICENSE.txt +93 -0
- spriteforge/app/studio.py +278 -0
- spriteforge/app/workers.py +73 -0
- spriteforge/cli.py +241 -0
- spriteforge/config.py +193 -0
- spriteforge/config.yaml +157 -0
- spriteforge/core/__init__.py +0 -0
- spriteforge/core/acting.py +16 -0
- spriteforge/core/cost.py +236 -0
- spriteforge/core/credentials.py +24 -0
- spriteforge/core/demo.py +79 -0
- spriteforge/core/forms.py +20 -0
- spriteforge/core/gates.py +175 -0
- spriteforge/core/security.py +42 -0
- spriteforge/core/state.py +222 -0
- spriteforge/core/team.py +15 -0
- spriteforge/core/usage.py +68 -0
- spriteforge/game/__init__.py +0 -0
- spriteforge/game/actors.py +377 -0
- spriteforge/game/agent_tools.py +178 -0
- spriteforge/game/art.py +2097 -0
- spriteforge/game/art_checks.py +190 -0
- spriteforge/game/art_review.py +518 -0
- spriteforge/game/build.py +134 -0
- spriteforge/game/bundle.py +1178 -0
- spriteforge/game/cli.py +119 -0
- spriteforge/game/codegen.py +433 -0
- spriteforge/game/codeinfo.py +154 -0
- spriteforge/game/dbsource.py +137 -0
- spriteforge/game/design.py +342 -0
- spriteforge/game/export.py +62 -0
- spriteforge/game/gamedb.py +191 -0
- spriteforge/game/image_cache.py +61 -0
- spriteforge/game/lessons.py +259 -0
- spriteforge/game/level_gen.py +118 -0
- spriteforge/game/level_preview.py +97 -0
- spriteforge/game/levels.py +934 -0
- spriteforge/game/loops.py +38 -0
- spriteforge/game/menus.py +712 -0
- spriteforge/game/mock_game.js +109 -0
- spriteforge/game/mock_platformer.js +58 -0
- spriteforge/game/motion.py +881 -0
- spriteforge/game/pipeline.py +1768 -0
- spriteforge/game/plan.py +502 -0
- spriteforge/game/playtest.py +318 -0
- spriteforge/game/qa.py +664 -0
- spriteforge/game/qa_checks.py +223 -0
- spriteforge/game/qa_runtime.py +565 -0
- spriteforge/game/reach.py +807 -0
- spriteforge/game/record.py +138 -0
- spriteforge/game/research.py +262 -0
- spriteforge/game/revision.py +225 -0
- spriteforge/game/sdk/API.md +104 -0
- spriteforge/game/sdk/FLOW.md +19 -0
- spriteforge/game/sdk/LEVELS.md +65 -0
- spriteforge/game/sdk/sf.js +418 -0
- spriteforge/game/sdk/sfflow.js +442 -0
- spriteforge/game/sdk/sflevel.js +683 -0
- spriteforge/game/sdk/sfsound-editor.js +225 -0
- spriteforge/game/sdk/sfsound.js +260 -0
- spriteforge/game/sdk/sounds.html +67 -0
- spriteforge/game/sounds.py +793 -0
- spriteforge/game/story.py +188 -0
- spriteforge/game/structure.py +98 -0
- spriteforge/game/team_reports.py +394 -0
- spriteforge/game/tilesets.py +70 -0
- spriteforge/game/title_art.py +186 -0
- spriteforge/genres/__init__.py +0 -0
- spriteforge/library/__init__.py +15 -0
- spriteforge/library/cli.py +126 -0
- spriteforge/library/describe.py +242 -0
- spriteforge/library/looks.py +154 -0
- spriteforge/library/models.py +79 -0
- spriteforge/library/store.py +422 -0
- spriteforge/library/tilesets/README.md +32 -0
- spriteforge/library/tilesets/gandalf-seasons.json +111 -0
- spriteforge/library/tilesets/pixel-crawler-dungeon.json +66 -0
- spriteforge/mcp/__init__.py +0 -0
- spriteforge/mcp/cli.py +58 -0
- spriteforge/mcp/client.py +57 -0
- spriteforge/mcp/filesystem_read.py +32 -0
- spriteforge/mcp/gamedb.py +56 -0
- spriteforge/mcp/library.py +179 -0
- spriteforge/mcp/memory.py +37 -0
- spriteforge/mcp/pixel_tools.py +145 -0
- spriteforge/mcp/registry.py +145 -0
- spriteforge/mcp/service.py +224 -0
- spriteforge/mcp/templates/context7.json +6 -0
- spriteforge/mcp/templates/fetch.json +6 -0
- spriteforge/mcp/templates/filesystem-read.json +6 -0
- spriteforge/mcp/templates/pixel-tools.json +6 -0
- spriteforge/memory/README.md +10 -0
- spriteforge/memory/__init__.py +0 -0
- spriteforge/memory/cli.py +131 -0
- spriteforge/memory/okf/__init__.py +1 -0
- spriteforge/memory/okf/catalog.py +331 -0
- spriteforge/memory/okf/codec.py +63 -0
- spriteforge/memory/okf/git.py +104 -0
- spriteforge/memory/okf/indexes.py +50 -0
- spriteforge/memory/okf/models.py +114 -0
- spriteforge/memory/okf/search.py +53 -0
- spriteforge/memory/okf/seed.py +81 -0
- spriteforge/memory/okf/seeds/genres.yaml +121 -0
- spriteforge/memory/okf/seeds/other.yaml +150 -0
- spriteforge/memory/okf/store.py +402 -0
- spriteforge/memory/okf/validate.py +115 -0
- spriteforge/pixel/__init__.py +17 -0
- spriteforge/pixel/atlas.py +110 -0
- spriteforge/pixel/grid.py +174 -0
- spriteforge/pixel/palette.py +156 -0
- spriteforge/pixel/palettes/dungeon.json +9 -0
- spriteforge/pixel/postprocess.py +170 -0
- spriteforge/pixel/preview.py +40 -0
- spriteforge/pixel/schemas.py +139 -0
- spriteforge/pixel/source.py +237 -0
- spriteforge/pixel/terrain.py +48 -0
- spriteforge/pixel/validate.py +138 -0
- spriteforge/prompts/anim_frame.txt +1 -0
- spriteforge/prompts/character.txt +1 -0
- spriteforge/prompts/item.txt +1 -0
- spriteforge/prompts/tile.txt +1 -0
- spriteforge/prompts/ui.txt +1 -0
- spriteforge/providers/__init__.py +0 -0
- spriteforge/providers/base.py +97 -0
- spriteforge/providers/http.py +38 -0
- spriteforge/providers/mock.py +111 -0
- spriteforge/providers/muse_image.py +60 -0
- spriteforge/providers/muse_search.py +91 -0
- spriteforge/providers/muse_spark.py +66 -0
- spriteforge/skills/__init__.py +0 -0
- spriteforge/skills/builtin/LICENSE-awesome-gamedev-agent-skills.txt +201 -0
- spriteforge/skills/builtin/NOTICE-awesome-gamedev-agent-skills.txt +15 -0
- spriteforge/skills/builtin/THIRD_PARTY.md +21 -0
- spriteforge/skills/builtin/audio-design/SKILL.md +190 -0
- spriteforge/skills/builtin/game-feel/SKILL.md +174 -0
- spriteforge/skills/builtin/game-ui-ux/SKILL.md +167 -0
- spriteforge/skills/builtin/level-design/SKILL.md +169 -0
- spriteforge/skills/builtin/phaser-arcade-physics/SKILL.md +17 -0
- spriteforge/skills/builtin/physics-tuning/SKILL.md +164 -0
- spriteforge/skills/builtin/pixel-art-prompting/SKILL.md +12 -0
- spriteforge/skills/builtin/platformer/SKILL.md +153 -0
- spriteforge/skills/builtin/puzzle/SKILL.md +143 -0
- spriteforge/skills/builtin/sprite-animation-frames/SKILL.md +11 -0
- spriteforge/skills/builtin/tileset-design/SKILL.md +10 -0
- spriteforge/skills/catalog.py +200 -0
- spriteforge/skills/cli.py +41 -0
- spriteforge/stages/__init__.py +0 -0
- spriteforge/stages/asset_context.py +301 -0
- spriteforge/stages/asset_models.py +192 -0
- spriteforge/stages/asset_render.py +366 -0
- spriteforge/stages/asset_review.py +140 -0
- spriteforge/stages/asset_store.py +94 -0
- spriteforge/stages/chat_changes.py +236 -0
- spriteforge/stages/concept.py +42 -0
- spriteforge/stages/game.py +1699 -0
- spriteforge/stages/game_confirm.py +112 -0
- spriteforge/stages/game_final.py +220 -0
- spriteforge/stages/game_record.py +246 -0
- spriteforge/stages/gameplay.py +218 -0
- spriteforge/stages/intake.py +372 -0
- spriteforge/stages/preview_assets.py +212 -0
- spriteforge/stages/preview_models.py +167 -0
- spriteforge/stages/preview_render.py +169 -0
- spriteforge/stages/preview_repair.py +61 -0
- spriteforge/stages/preview_review.py +169 -0
- spriteforge/stages/production.py +170 -0
- spriteforge/stages/references.py +105 -0
- spriteforge/stages/rewind.py +128 -0
- spriteforge/stages/workflow.py +440 -0
- spriteforge/templates/phaser/audit.js +45 -0
- spriteforge/templates/phaser/font.png +0 -0
- spriteforge/templates/phaser/font.xml +1 -0
- spriteforge/templates/phaser/preview.html +9 -0
- spriteforge/templates/phaser/room.js +49 -0
- spriteforge/templates/phaser/vendor/LICENSE.md +20 -0
- spriteforge/templates/phaser/vendor/phaser.min.js +1 -0
- spriteforge-0.1.1.dist-info/METADATA +364 -0
- spriteforge-0.1.1.dist-info/RECORD +218 -0
- spriteforge-0.1.1.dist-info/WHEEL +5 -0
- spriteforge-0.1.1.dist-info/entry_points.txt +2 -0
- spriteforge-0.1.1.dist-info/licenses/LICENSE +27 -0
- spriteforge-0.1.1.dist-info/top_level.txt +1 -0
spriteforge/game/qa.py
ADDED
|
@@ -0,0 +1,664 @@
|
|
|
1
|
+
"""QA tests: written from the design (not the code), played with real key presses, exported.
|
|
2
|
+
|
|
3
|
+
The QA Playtester (Muse Spark) writes `QATests` from the design, its checks and controls:
|
|
4
|
+
movement with real input, the level-up menu, the lose path, restart after losing and the HUD
|
|
5
|
+
state changing. Each test is a list of steps (data, never code) that `qa_runtime` plays in a
|
|
6
|
+
real browser while stepping game time; the bot playtest cannot find these bugs, because the bot
|
|
7
|
+
never presses a key, opens a menu by hand or restarts.
|
|
8
|
+
|
|
9
|
+
Strict JSON schema mode wants every field required, so a `Step` is one flat record: `do` says
|
|
10
|
+
what it is and the fields it does not use stay empty (cleared on validation). Limits: 12 tests,
|
|
11
|
+
40 steps and 120 game seconds per test, whitelisted keys, bounded values.
|
|
12
|
+
|
|
13
|
+
`run_qa` plays a list of tests against a build; `qa_failures` is their part of the repair
|
|
14
|
+
prompt; `export_tests` writes `tests/test_game_qa.py` (pytest + Playwright, self-contained: the
|
|
15
|
+
runtime is copied in and the tests are JSON inside one string literal built with `repr`, so no
|
|
16
|
+
model text can become code); `merge_suite` keeps earlier versions' tests as a regression suite
|
|
17
|
+
minus the ones feedback dropped.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
import json
|
|
21
|
+
import re
|
|
22
|
+
from pathlib import Path
|
|
23
|
+
from typing import Literal
|
|
24
|
+
|
|
25
|
+
from playwright.sync_api import Error as PlaywrightError
|
|
26
|
+
from playwright.sync_api import sync_playwright
|
|
27
|
+
from pydantic import Field, model_validator
|
|
28
|
+
|
|
29
|
+
from spriteforge.agents.models import Contract
|
|
30
|
+
|
|
31
|
+
from . import qa_runtime
|
|
32
|
+
from .design import GameDesign
|
|
33
|
+
from .qa_runtime import KEYS, MAX_TEST_SECONDS, MENU_WAIT, PRESS_FRAMES, describe_step, serve
|
|
34
|
+
|
|
35
|
+
MAX_TESTS, MAX_STEPS, MAX_SUITE = 12, 40, 24
|
|
36
|
+
MAX_LEVELS = 8 # a game's levels (structure.MAX_LEVELS); code adds one test per level (L2.6)
|
|
37
|
+
StepKind = Literal[
|
|
38
|
+
"hold", "press", "wait", "choose", "expect_event", "expect_state", "expect_no_errors",
|
|
39
|
+
"screenshot", "expect_menu", "select", "reload",
|
|
40
|
+
] # fmt: skip
|
|
41
|
+
Key = Literal[tuple(KEYS)]
|
|
42
|
+
Op = Literal["==", "!=", "<", "<=", ">", ">=", ""]
|
|
43
|
+
EVENT = re.compile(r"^[a-z][a-z0-9_]{0,39}$")
|
|
44
|
+
PATH = re.compile(r"^[A-Za-z_]\w{0,30}(\.[A-Za-z_]\w{0,30}){0,3}$")
|
|
45
|
+
LABEL = re.compile(r"^[A-Za-z0-9][A-Za-z0-9 _-]{0,39}$")
|
|
46
|
+
# Events every build has: the SDK emits boot, restart, menu and choice; games emit win/lose.
|
|
47
|
+
SDK_EVENTS = ("boot", "restart", "menu", "choice", "win", "lose")
|
|
48
|
+
# A build with menus (L2.5): the SDK's flow emits these too, and sf.state has the difficulty.
|
|
49
|
+
FLOW_EVENTS = ("title", "menu_open", "menu_select", "pause", "resume", "level_start",
|
|
50
|
+
"level_complete", "level_failed", "game_complete") # fmt: skip
|
|
51
|
+
STATE_KEYS = ("hp", "x", "y", "time", "level", "score")
|
|
52
|
+
MENU_TEXT = re.compile(r"^[A-Za-z0-9][\w .,:'!?&+-]{0,39}$")
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def need(ok: bool, message: str) -> None:
|
|
56
|
+
if not ok:
|
|
57
|
+
raise ValueError(message)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class Step(Contract):
|
|
61
|
+
do: StepKind = Field(description="what the step does (see the task)")
|
|
62
|
+
buttons: list[Key] = Field(
|
|
63
|
+
description="hold: 1-4 keys held together; press: exactly 1; else [] (named buttons: the "
|
|
64
|
+
"artifact store blanks any field named like key)"
|
|
65
|
+
)
|
|
66
|
+
seconds: float = Field(description="hold, wait: game seconds (at most 60); else 0")
|
|
67
|
+
index: int = Field(description="choose: 0-based option of the open menu; else 0")
|
|
68
|
+
event: str = Field(description="expect_event: the event name; else ''")
|
|
69
|
+
min_count: int = Field(description="expect_event: at least this many since the test began")
|
|
70
|
+
within_seconds: float = Field(description="expect_event: game seconds to wait (0 = now)")
|
|
71
|
+
path: str = Field(description="expect_state: dotted path in sf.state, e.g. 'hp'; else ''")
|
|
72
|
+
op: Op = Field(description="expect_state: comparison; else ''")
|
|
73
|
+
value: str = Field(
|
|
74
|
+
description="expect_state: a number, true/false, text, or '@start' (the value when the "
|
|
75
|
+
"test began); else ''"
|
|
76
|
+
)
|
|
77
|
+
label: str = Field(description="screenshot: a short label; else ''")
|
|
78
|
+
menu: str = Field(
|
|
79
|
+
description="expect_menu: the screen id (title, main, pause, settings, results, "
|
|
80
|
+
"game_over, victory ...); select: the item's label as shown; else ''"
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
@model_validator(mode="before")
|
|
84
|
+
@classmethod
|
|
85
|
+
def older(cls, data):
|
|
86
|
+
"""Steps saved before menus existed (L2.5) have no `menu`."""
|
|
87
|
+
if isinstance(data, dict) and "menu" not in data:
|
|
88
|
+
data = {**data, "menu": ""}
|
|
89
|
+
return data
|
|
90
|
+
|
|
91
|
+
@model_validator(mode="after")
|
|
92
|
+
def check(self):
|
|
93
|
+
do, blank = self.do, {"buttons": [], "seconds": 0.0, "index": 0, "event": "",
|
|
94
|
+
"min_count": 0, "within_seconds": 0.0, "path": "", "op": "",
|
|
95
|
+
"value": "", "label": "", "menu": ""} # fmt: skip
|
|
96
|
+
used = {"hold": {"buttons", "seconds"}, "press": {"buttons"}, "wait": {"seconds"},
|
|
97
|
+
"choose": {"index"}, "expect_event": {"event", "min_count", "within_seconds"},
|
|
98
|
+
"expect_state": {"path", "op", "value"}, "screenshot": {"label"},
|
|
99
|
+
"expect_menu": {"menu"}, "select": {"menu"}}.get(do, set()) # fmt: skip
|
|
100
|
+
if do == "hold":
|
|
101
|
+
need(1 <= len(self.buttons) <= 4, "hold needs 1 to 4 keys")
|
|
102
|
+
need(
|
|
103
|
+
0 < self.seconds <= 60,
|
|
104
|
+
f"hold seconds must be above 0 and at most 60, not {self.seconds}",
|
|
105
|
+
)
|
|
106
|
+
elif do == "press":
|
|
107
|
+
need(len(self.buttons) == 1, "press needs exactly one key")
|
|
108
|
+
elif do == "wait":
|
|
109
|
+
need(
|
|
110
|
+
0 < self.seconds <= 60,
|
|
111
|
+
f"wait seconds must be above 0 and at most 60, not {self.seconds}",
|
|
112
|
+
)
|
|
113
|
+
elif do == "choose":
|
|
114
|
+
need(0 <= self.index <= 8, "choose index must be 0-8")
|
|
115
|
+
elif do == "expect_event":
|
|
116
|
+
self.event = self.event.strip().lower()
|
|
117
|
+
need(bool(EVENT.match(self.event)), f"bad event name {self.event!r}")
|
|
118
|
+
need(1 <= self.min_count <= 10000, "min_count must be 1-10000")
|
|
119
|
+
need(0 <= self.within_seconds <= MAX_TEST_SECONDS, "within_seconds must be 0-120")
|
|
120
|
+
elif do == "expect_state":
|
|
121
|
+
self.path, self.value = self.path.strip(), self.value.strip()
|
|
122
|
+
need(bool(PATH.match(self.path)), f"bad state path {self.path!r}")
|
|
123
|
+
need(self.op != "", "expect_state needs an op")
|
|
124
|
+
need(0 < len(self.value) <= 40, "expect_state needs a value (at most 40 characters)")
|
|
125
|
+
elif do == "screenshot":
|
|
126
|
+
self.label = self.label.strip()
|
|
127
|
+
need(bool(LABEL.match(self.label)), f"bad screenshot label {self.label!r}")
|
|
128
|
+
elif do in ("expect_menu", "select"):
|
|
129
|
+
self.menu = self.menu.strip()
|
|
130
|
+
if do == "expect_menu":
|
|
131
|
+
self.menu = self.menu.lower().replace(" ", "_")
|
|
132
|
+
need(bool(MENU_TEXT.match(self.menu)), f"{do} needs a menu (a screen id or an item label)")
|
|
133
|
+
for name, empty in blank.items(): # what the step does not use stays empty
|
|
134
|
+
if name not in used:
|
|
135
|
+
setattr(self, name, empty)
|
|
136
|
+
return self
|
|
137
|
+
|
|
138
|
+
def game_seconds(self) -> float:
|
|
139
|
+
"""The most game time this step can take."""
|
|
140
|
+
return {
|
|
141
|
+
"hold": self.seconds,
|
|
142
|
+
"wait": self.seconds,
|
|
143
|
+
"expect_event": self.within_seconds,
|
|
144
|
+
"press": (PRESS_FRAMES + 1) / 30,
|
|
145
|
+
"choose": MENU_WAIT + (PRESS_FRAMES + 1) / 30,
|
|
146
|
+
"expect_menu": MENU_WAIT,
|
|
147
|
+
"select": MENU_WAIT + 10 * (PRESS_FRAMES + 1) / 30,
|
|
148
|
+
}.get(self.do, 0.0)
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
class QATest(Contract):
|
|
152
|
+
name: str = Field(description="short unique name, e.g. 'restart after losing'")
|
|
153
|
+
purpose: str = Field(description="what it proves, from the design, in one sentence")
|
|
154
|
+
god: bool = Field(
|
|
155
|
+
description="true: the player cannot die (hurt, but HP stays >= 1); false for the lose "
|
|
156
|
+
"path and restart after losing"
|
|
157
|
+
)
|
|
158
|
+
start: Literal["play", "title"] = Field(
|
|
159
|
+
description="play: the test starts in play, in `level` (the title is skipped); title: "
|
|
160
|
+
"on the title screen (tests of the menus)"
|
|
161
|
+
)
|
|
162
|
+
level: int = Field(
|
|
163
|
+
description="start play: the level the test starts in (1 = the first); a game with "
|
|
164
|
+
"several levels can test each one directly. Ignored with start title"
|
|
165
|
+
)
|
|
166
|
+
steps: list[Step]
|
|
167
|
+
|
|
168
|
+
@model_validator(mode="before")
|
|
169
|
+
@classmethod
|
|
170
|
+
def older(cls, data):
|
|
171
|
+
"""Tests saved before menus existed (L2.5) start in play; before L2.6, in level 1."""
|
|
172
|
+
if isinstance(data, dict):
|
|
173
|
+
data = {"start": "play", "level": 1, **data}
|
|
174
|
+
return data
|
|
175
|
+
|
|
176
|
+
@model_validator(mode="after")
|
|
177
|
+
def check(self):
|
|
178
|
+
self.name, self.purpose = self.name.strip(), self.purpose.strip()[:240]
|
|
179
|
+
need(0 < len(self.name) <= 60, "a test needs a name of at most 60 characters")
|
|
180
|
+
need(1 <= self.level <= MAX_LEVELS, f"level must be 1-{MAX_LEVELS}, not {self.level}")
|
|
181
|
+
if self.start == "title":
|
|
182
|
+
self.level = 1
|
|
183
|
+
need(1 <= len(self.steps) <= MAX_STEPS, f"a test has 1 to {MAX_STEPS} steps")
|
|
184
|
+
total = sum(s.game_seconds() for s in self.steps)
|
|
185
|
+
need(total <= MAX_TEST_SECONDS, f"test {self.name!r} needs {total:g} game seconds; "
|
|
186
|
+
f"at most {MAX_TEST_SECONDS}") # fmt: skip
|
|
187
|
+
return self
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
class QATests(Contract):
|
|
191
|
+
tests: list[QATest]
|
|
192
|
+
|
|
193
|
+
@model_validator(mode="after")
|
|
194
|
+
def check(self):
|
|
195
|
+
need(1 <= len(self.tests) <= MAX_TESTS, f"write 1 to {MAX_TESTS} tests")
|
|
196
|
+
names = [t.name.casefold() for t in self.tests]
|
|
197
|
+
need(len(set(names)) == len(names), "test names must be unique")
|
|
198
|
+
return self
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
class QASuite(Contract):
|
|
202
|
+
"""The tests one build runs (game/vN/qa-tests.json): its design's tests plus earlier
|
|
203
|
+
versions' tests (a regression suite), minus those feedback dropped."""
|
|
204
|
+
|
|
205
|
+
tests: list[QATest]
|
|
206
|
+
# The build version each test was first run in, in the order of `tests`. (Not a dict keyed
|
|
207
|
+
# by test name: the artifact store blanks dict keys that look like secrets, e.g. "keys".)
|
|
208
|
+
versions: list[int]
|
|
209
|
+
dropped: list[str]
|
|
210
|
+
notes: list[str]
|
|
211
|
+
|
|
212
|
+
def since(self, name: str) -> int | None:
|
|
213
|
+
return next((v for t, v in zip(self.tests, self.versions, strict=True) if t.name == name),
|
|
214
|
+
None) # fmt: skip
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
# --- writing the tests ----------------------------------------------------------------------
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def menu_lines(menus: dict) -> str:
|
|
221
|
+
"""The SDK's screens and their items as a QA Playtester reads them."""
|
|
222
|
+
return "\n".join(
|
|
223
|
+
f"* {sid}: " + ", ".join(f"'{i['label']}' ({i['action']})" for i in screen["items"])
|
|
224
|
+
for sid, screen in menus["screens"].items()
|
|
225
|
+
)
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def menus_part(menus: dict | None) -> str:
|
|
229
|
+
if not menus:
|
|
230
|
+
return ""
|
|
231
|
+
levels = len(menus.get("levels", [])) or 1
|
|
232
|
+
between = " and between levels 'results'" if levels > 1 else ""
|
|
233
|
+
several = (
|
|
234
|
+
f"\nThe game has {levels} levels (" + ", ".join(f"{lv['n']}. {lv['name']}" for lv in
|
|
235
|
+
menus["levels"]) + "). A test with start \"play\" and `level` n starts in level n "
|
|
236
|
+
"(sf.state.level is n); code already adds one test per level that it starts, the player "
|
|
237
|
+
"moves and nothing fails, so write level tests only for what a level itself promises."
|
|
238
|
+
if levels > 1 else ""
|
|
239
|
+
) # fmt: skip
|
|
240
|
+
return f"""
|
|
241
|
+
Menus (the SDK draws and runs them; they are data, the same in every build of this game):
|
|
242
|
+
the game opens on its title screen. A test with start "play" skips it and starts in `level`;
|
|
243
|
+
start "title" begins on the title screen. Every test starts with no saved progress.
|
|
244
|
+
* expect_menu: the screen `menu` (a screen id below) is open, waiting up to {MENU_WAIT:g} s
|
|
245
|
+
* select: moves the highlight to the item whose label (or action) is `menu` with the arrow
|
|
246
|
+
keys and presses Enter (waits up to {MENU_WAIT:g} s for a menu screen)
|
|
247
|
+
* reload: opens the page again on the title screen; saved progress (levels unlocked, best
|
|
248
|
+
results, settings) is kept; event counts start again
|
|
249
|
+
Escape pauses play (the pause screen; game time stops) and goes back in menus (on pause it
|
|
250
|
+
resumes). Screens and items:
|
|
251
|
+
{menu_lines(menus)}
|
|
252
|
+
Flow events: {", ".join(FLOW_EVENTS)}. sf.state.difficulty is easy, normal or hard (the
|
|
253
|
+
settings item cycles normal -> hard -> easy). After 'lose' the game_over screen opens
|
|
254
|
+
(about a second later); after the last level 'victory'{between}.
|
|
255
|
+
Selecting an item emits menu_select; opening a screen emits menu_open.{several}
|
|
256
|
+
"""
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def qa_prompt(design: GameDesign, menus: dict | None = None) -> str:
|
|
260
|
+
"""`menus`: the build's menus (`menus.menus_script`), when the game has them."""
|
|
261
|
+
events = sorted({c.event for c in design.checks} | set(SDK_EVENTS)
|
|
262
|
+
| (set(FLOW_EVENTS) if menus else set())) # fmt: skip
|
|
263
|
+
flow = (
|
|
264
|
+
"\n6. the menus: from the title (start title) to play (expect_menu title, press enter, "
|
|
265
|
+
"expect_menu main, select the start item, expect level_start), pause and resume with "
|
|
266
|
+
"Escape (expect_menu pause, then expect resume), and a setting that shows in sf.state "
|
|
267
|
+
"(difficulty); with a way to lose, game_over opens after losing and its retry item "
|
|
268
|
+
"restarts."
|
|
269
|
+
if menus
|
|
270
|
+
else ""
|
|
271
|
+
)
|
|
272
|
+
return f"""Write QA tests for this game from its design alone (you do not see the code).
|
|
273
|
+
A harness plays each test in a real browser: it presses real keys, steps game time exactly,
|
|
274
|
+
and reads what the game exposes. Each test opens a fresh game.
|
|
275
|
+
|
|
276
|
+
Steps (fields a step does not use stay empty or 0):
|
|
277
|
+
* hold: the keys in `buttons` held together for `seconds` of game time (at most 60)
|
|
278
|
+
* press: the one key in `buttons`, pressed briefly
|
|
279
|
+
* wait: `seconds` of game time with no keys
|
|
280
|
+
* choose: pick option `index` (0-based) of the open menu (sf.choose, e.g. level-up upgrades);
|
|
281
|
+
it waits up to {MENU_WAIT:g} s for the menu to open
|
|
282
|
+
* expect_event: `event` happened at least `min_count` times since the test began, waiting up to
|
|
283
|
+
`within_seconds` of game time (0 = must already have happened)
|
|
284
|
+
* expect_state: sf.state `path` `op` `value`; value '@start' means its value when the test began
|
|
285
|
+
* expect_no_errors: no runtime errors so far
|
|
286
|
+
* screenshot: a picture named `label`
|
|
287
|
+
{menus_part(menus)}
|
|
288
|
+
Keys: {", ".join(KEYS)}. Arrows/WASD move; Space/Z/J are the action key; X/K/Shift the second
|
|
289
|
+
action (follow the design's controls).
|
|
290
|
+
|
|
291
|
+
What every build exposes:
|
|
292
|
+
* sf.state: hp (player health), x and y (player position in pixels), time (seconds since this
|
|
293
|
+
run began; a restart resets it), and level and score when the design has them.
|
|
294
|
+
* events: {", ".join(events)}. 'menu' is emitted when an sf.choose menu opens, 'choice' when an
|
|
295
|
+
option is picked, 'restart' when the game restarts, 'win'/'lose' when a run ends.
|
|
296
|
+
* After win or lose, Enter restarts the game.
|
|
297
|
+
* god true: the player is hurt but never dies (use it in every test but the lose path).
|
|
298
|
+
|
|
299
|
+
Write 5 to 8 tests, at most {MAX_STEPS} steps and {MAX_TEST_SECONDS} game seconds each (holds +
|
|
300
|
+
waits + within_seconds). They must include:
|
|
301
|
+
1. movement with real input: hold arrow keys, then expect x or y to differ from '@start';
|
|
302
|
+
2. the level-up or upgrade menu if the design has one: play until 'menu' happens (hold keys that
|
|
303
|
+
move the player through the action), choose an option, expect 'choice', play on, expect no
|
|
304
|
+
errors;
|
|
305
|
+
3. the lose path: god false, the player idle (or walking into danger); expect 'lose' within the
|
|
306
|
+
time the design implies (at most {MAX_TEST_SECONDS - 20} s);
|
|
307
|
+
4. restart after losing: god false; expect 'lose'; press enter; expect 'restart' within 3 s;
|
|
308
|
+
expect time < 5; move and expect no errors;
|
|
309
|
+
5. the HUD state changing: e.g. time grows, hp drops after being hurt, score rises.{flow}
|
|
310
|
+
Test only what the design promises; do not invent numbers it does not state. Use only the
|
|
311
|
+
event names and sf.state keys listed above.
|
|
312
|
+
|
|
313
|
+
Design:
|
|
314
|
+
{design.model_dump_json(indent=1)}"""
|
|
315
|
+
|
|
316
|
+
|
|
317
|
+
def blank_step(**fields) -> Step:
|
|
318
|
+
base = {"buttons": [], "seconds": 0, "index": 0, "event": "", "min_count": 0,
|
|
319
|
+
"within_seconds": 0, "path": "", "op": "", "value": "", "label": "", "menu": ""} # fmt: skip
|
|
320
|
+
return Step(**{**base, **fields})
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
def label_of(menus: dict, screen: str, action: str) -> str | None:
|
|
324
|
+
"""The action when the screen has an item for it (`select` finds items by their action
|
|
325
|
+
too, so these tests survive new labels)."""
|
|
326
|
+
items = (menus["screens"].get(screen) or {}).get("items", [])
|
|
327
|
+
return next((action for i in items if i["action"] == action), None)
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
VALUE_SUFFIX = re.compile(r"\s*[:=-]?\s*\(?\b(easy|normal|hard|on|off)\b\)?\s*$", re.IGNORECASE)
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
def bind_selects(tests: list[QATest], menus: dict | None) -> list[QATest]:
|
|
334
|
+
"""`select` steps name the item's action instead of the label it had in `menus` (the menus
|
|
335
|
+
the tests were written against), so a menu revision that renames an item keeps them
|
|
336
|
+
working. Live 2026-11-02: "New Adventure" renamed to "Start" failed a test, and the
|
|
337
|
+
Programmer, asked to fix it, rewrote the SDK's menus from game code."""
|
|
338
|
+
if not menus:
|
|
339
|
+
return list(tests)
|
|
340
|
+
actions = {}
|
|
341
|
+
for screen in menus["screens"].values():
|
|
342
|
+
for item in screen["items"]:
|
|
343
|
+
actions.setdefault(item["label"].strip().lower(), item["action"])
|
|
344
|
+
known = {i["action"] for s in menus["screens"].values() for i in s["items"]}
|
|
345
|
+
out = []
|
|
346
|
+
for test in tests:
|
|
347
|
+
steps = []
|
|
348
|
+
for step in test.steps:
|
|
349
|
+
if step.do == "select":
|
|
350
|
+
want = step.menu.strip().lower()
|
|
351
|
+
bare = VALUE_SUFFIX.sub("", want)
|
|
352
|
+
action = (want.replace(" ", "_") if want.replace(" ", "_") in known
|
|
353
|
+
else actions.get(want) or actions.get(bare)) # fmt: skip
|
|
354
|
+
if action and action != step.menu:
|
|
355
|
+
step = step.model_copy(update={"menu": action})
|
|
356
|
+
steps.append(step)
|
|
357
|
+
out.append(test.model_copy(update={"steps": steps}))
|
|
358
|
+
return out
|
|
359
|
+
|
|
360
|
+
|
|
361
|
+
def flow_tests(design: GameDesign, menus: dict) -> list[QATest]:
|
|
362
|
+
"""Tests of the SDK's menus and flow."""
|
|
363
|
+
s = blank_step
|
|
364
|
+
start, settings = label_of(menus, "main", "start"), label_of(menus, "main", "settings")
|
|
365
|
+
resume = label_of(menus, "pause", "resume")
|
|
366
|
+
tests = []
|
|
367
|
+
if start and resume:
|
|
368
|
+
tests.append(QATest(
|
|
369
|
+
name="title to play, pause and resume", god=True, start="title",
|
|
370
|
+
purpose="The title leads to play; Escape pauses (time stops) and Resume goes on.",
|
|
371
|
+
steps=[s(do="expect_menu", menu="title"), s(do="press", buttons=["enter"]),
|
|
372
|
+
s(do="expect_menu", menu="main"), s(do="select", menu=start),
|
|
373
|
+
s(do="expect_event", event="level_start", min_count=1, within_seconds=2),
|
|
374
|
+
s(do="wait", seconds=1), s(do="press", buttons=["escape"]),
|
|
375
|
+
s(do="expect_menu", menu="pause"),
|
|
376
|
+
s(do="expect_event", event="pause", min_count=1, within_seconds=0),
|
|
377
|
+
s(do="screenshot", label="paused"), s(do="select", menu=resume),
|
|
378
|
+
s(do="expect_event", event="resume", min_count=1, within_seconds=1),
|
|
379
|
+
s(do="hold", buttons=["right"], seconds=0.5), s(do="expect_no_errors")])) # fmt: skip
|
|
380
|
+
difficulty = label_of(menus, "settings", "difficulty")
|
|
381
|
+
if start and settings and difficulty:
|
|
382
|
+
tests.append(QATest(
|
|
383
|
+
name="difficulty setting", god=True, start="title",
|
|
384
|
+
purpose="Settings changes the difficulty the game reads, and it is kept.",
|
|
385
|
+
steps=[s(do="press", buttons=["enter"]), s(do="select", menu=settings),
|
|
386
|
+
s(do="expect_menu", menu="settings"), s(do="select", menu=difficulty),
|
|
387
|
+
s(do="expect_state", path="difficulty", op="==", value="hard"),
|
|
388
|
+
s(do="reload"), s(do="expect_menu", menu="title"),
|
|
389
|
+
s(do="expect_state", path="difficulty", op="==", value="hard"),
|
|
390
|
+
s(do="expect_no_errors")])) # fmt: skip
|
|
391
|
+
retry = label_of(menus, "game_over", "retry")
|
|
392
|
+
if retry and design.lose.strip():
|
|
393
|
+
tests.append(QATest(
|
|
394
|
+
name="game over and retry", god=False, start="play",
|
|
395
|
+
purpose="Losing opens game over; Retry starts the level again.",
|
|
396
|
+
steps=[s(do="expect_event", event="lose", min_count=1, within_seconds=100),
|
|
397
|
+
s(do="expect_menu", menu="game_over"), s(do="screenshot", label="game over"),
|
|
398
|
+
s(do="select", menu=retry),
|
|
399
|
+
s(do="expect_event", event="restart", min_count=1, within_seconds=2),
|
|
400
|
+
s(do="expect_state", path="time", op="<", value="5"),
|
|
401
|
+
s(do="expect_no_errors")])) # fmt: skip
|
|
402
|
+
return tests
|
|
403
|
+
|
|
404
|
+
|
|
405
|
+
def level_tests(menus: dict | None) -> list[QATest]:
|
|
406
|
+
"""One test per level of a game with several (L2.6): it starts in that level, which
|
|
407
|
+
begins, moves with real keys and runs without errors. Code adds them to every build's
|
|
408
|
+
suite (`merge_suite`), so every build checks every level with real input (the bot's run
|
|
409
|
+
is the other half)."""
|
|
410
|
+
levels = (menus or {}).get("levels", [])
|
|
411
|
+
if len(levels) < 2:
|
|
412
|
+
return []
|
|
413
|
+
s = blank_step
|
|
414
|
+
return [QATest(
|
|
415
|
+
name=f"level {lv['n']} starts and plays", god=True, start="play", level=lv["n"],
|
|
416
|
+
purpose=f"Level {lv['n']} ({lv['name']}) starts on its own and the player moves in it.",
|
|
417
|
+
steps=[s(do="expect_event", event="level_start", min_count=1, within_seconds=2),
|
|
418
|
+
s(do="expect_state", path="level", op="==", value=str(lv["n"])),
|
|
419
|
+
s(do="hold", buttons=["right"], seconds=1.5),
|
|
420
|
+
s(do="expect_state", path="x", op=">", value="@start"),
|
|
421
|
+
s(do="screenshot", label=f"level {lv['n']}"), s(do="expect_no_errors")],
|
|
422
|
+
) for lv in levels[:MAX_LEVELS]] # fmt: skip
|
|
423
|
+
|
|
424
|
+
|
|
425
|
+
def with_level_tests(tests: list[QATest], menus: dict | None) -> list[QATest]:
|
|
426
|
+
"""`tests` plus the per-level tests code writes (a test of the same name is kept)."""
|
|
427
|
+
names = {t.name.casefold() for t in tests}
|
|
428
|
+
return [*tests, *(t for t in level_tests(menus) if t.name.casefold() not in names)]
|
|
429
|
+
|
|
430
|
+
|
|
431
|
+
def fallback_qa(design: GameDesign, menus: dict | None = None) -> QATests:
|
|
432
|
+
"""Offline QA Playtester: tests every design can take (movement, no errors, the HUD clock,
|
|
433
|
+
the first timed check, losing and restarting), and with menus the flow (title to play,
|
|
434
|
+
pause, a setting kept over a reload, game over and retry)."""
|
|
435
|
+
s = blank_step
|
|
436
|
+
# A side view moves down by falling, not by a key: there, Space jumps (y gets smaller).
|
|
437
|
+
vertical = ([s(do="hold", buttons=["space"], seconds=0.25),
|
|
438
|
+
s(do="expect_state", path="y", op="<", value="@start")]
|
|
439
|
+
if design.camera == "side-view" else
|
|
440
|
+
[s(do="hold", buttons=["down"], seconds=1),
|
|
441
|
+
s(do="expect_state", path="y", op=">", value="@start")]) # fmt: skip
|
|
442
|
+
tests = [
|
|
443
|
+
QATest(name="moves with the arrow keys", god=True,
|
|
444
|
+
purpose="Real key presses move the player.",
|
|
445
|
+
steps=[s(do="hold", buttons=["right"], seconds=1.5),
|
|
446
|
+
s(do="expect_state", path="x", op=">", value="@start"),
|
|
447
|
+
*vertical,
|
|
448
|
+
s(do="expect_no_errors")]),
|
|
449
|
+
QATest(name="plays without errors", god=True,
|
|
450
|
+
purpose="Moving in every direction and both action keys cause no errors.",
|
|
451
|
+
steps=[s(do="hold", buttons=["left", "up"], seconds=2), s(do="press", buttons=["space"]),
|
|
452
|
+
s(do="hold", buttons=["d"], seconds=2), s(do="press", buttons=["x"]),
|
|
453
|
+
s(do="wait", seconds=3), s(do="expect_no_errors"),
|
|
454
|
+
s(do="screenshot", label="playing")]),
|
|
455
|
+
QATest(name="hud time advances", god=True, purpose="The run's time grows with play.",
|
|
456
|
+
steps=[s(do="wait", seconds=3),
|
|
457
|
+
s(do="expect_state", path="time", op=">=", value="2")]),
|
|
458
|
+
] # fmt: skip
|
|
459
|
+
timed = next((c for c in design.checks if c.by_second and c.event not in SDK_EVENTS
|
|
460
|
+
and c.by_second <= MAX_TEST_SECONDS - 20), None) # fmt: skip
|
|
461
|
+
if timed:
|
|
462
|
+
tests.append(QATest(name=f"{timed.id} in time", god=True, purpose=timed.description[:200],
|
|
463
|
+
steps=[s(do="hold", buttons=["left"], seconds=1),
|
|
464
|
+
s(do="expect_event", event=timed.event,
|
|
465
|
+
min_count=min(timed.min_count, 10000),
|
|
466
|
+
within_seconds=timed.by_second)])) # fmt: skip
|
|
467
|
+
if design.lose.strip():
|
|
468
|
+
lose = s(do="expect_event", event="lose", min_count=1, within_seconds=100)
|
|
469
|
+
tests += [
|
|
470
|
+
QATest(name="loses when idle", god=False, purpose=f"The lose path: {design.lose}"[:200],
|
|
471
|
+
steps=[lose, s(do="screenshot", label="lost")]),
|
|
472
|
+
QATest(name="restarts after losing", god=False,
|
|
473
|
+
purpose="Enter restarts the run after a loss and it starts over.",
|
|
474
|
+
steps=[lose, s(do="press", buttons=["enter"]),
|
|
475
|
+
s(do="expect_event", event="restart", min_count=1, within_seconds=3),
|
|
476
|
+
s(do="expect_state", path="time", op="<", value="5"),
|
|
477
|
+
s(do="hold", buttons=["right"], seconds=1),
|
|
478
|
+
s(do="expect_state", path="hp", op=">", value="0"),
|
|
479
|
+
s(do="expect_no_errors")]),
|
|
480
|
+
] # fmt: skip
|
|
481
|
+
if menus:
|
|
482
|
+
tests += flow_tests(design, menus)
|
|
483
|
+
return QATests(tests=tests[:MAX_TESTS])
|
|
484
|
+
|
|
485
|
+
|
|
486
|
+
# --- running them ------------------------------------------------------------------------------
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
def run_qa(build_dir: Path, tests: list, fps: int = 30) -> list[dict]:
|
|
490
|
+
"""Play every test against the build, each in a fresh page. Results as `run_test` returns
|
|
491
|
+
them, plus "purpose" and "god"; screenshots are PNG bytes (pop them before saving JSON).
|
|
492
|
+
`tests` may hold code checks (qa_checks.CodeCheck, L2.8) too: run with `run_check`."""
|
|
493
|
+
results = []
|
|
494
|
+
with serve(Path(build_dir)) as url, sync_playwright() as pw:
|
|
495
|
+
browser = pw.chromium.launch(headless=True)
|
|
496
|
+
try:
|
|
497
|
+
for test in tests:
|
|
498
|
+
context = browser.new_context(viewport={"width": 320, "height": 180})
|
|
499
|
+
try:
|
|
500
|
+
data = test.model_dump()
|
|
501
|
+
run = qa_runtime.run_check if "code" in data else qa_runtime.run_test
|
|
502
|
+
result = run(context.new_page(), url, data, fps)
|
|
503
|
+
except PlaywrightError as exc:
|
|
504
|
+
result = {"name": test.name, "passed": False, "failed_step": None,
|
|
505
|
+
"failure": f"the browser failed: {str(exc).splitlines()[0][:200]}",
|
|
506
|
+
"steps": [], "state": {}, "events": {}, "errors": [],
|
|
507
|
+
"game_seconds": 0.0, "screenshots": []} # fmt: skip
|
|
508
|
+
finally:
|
|
509
|
+
context.close()
|
|
510
|
+
results.append({**result, "purpose": test.purpose, "god": test.god})
|
|
511
|
+
finally:
|
|
512
|
+
browser.close()
|
|
513
|
+
return results
|
|
514
|
+
|
|
515
|
+
|
|
516
|
+
def qa_failures(results: list[dict]) -> str:
|
|
517
|
+
"""The failed QA tests, for the Programmer's repair prompt."""
|
|
518
|
+
failed = [r for r in results if not r["passed"] and r.get("kind") != "check"]
|
|
519
|
+
if not failed:
|
|
520
|
+
return ""
|
|
521
|
+
lines = [
|
|
522
|
+
(
|
|
523
|
+
"QA tests failed. They press real keys (not the bot), were written from the design "
|
|
524
|
+
"without seeing the code, and rely on the SDK contract: sf.state hp/x/y/time "
|
|
525
|
+
"(level/score), Enter restarts after win or lose, sf.choose menus picked with digit "
|
|
526
|
+
"keys. Fix the game wherever it breaks the design or that contract:"
|
|
527
|
+
)
|
|
528
|
+
]
|
|
529
|
+
for r in failed:
|
|
530
|
+
where = (f"at step {r['failed_step']} of {len(r['steps'])} "
|
|
531
|
+
f"({r['steps'][-1]['step']})" if r["failed_step"] else "") # fmt: skip
|
|
532
|
+
done = "; ".join(f"{i}. {s['step']} ({'ok' if s['ok'] else 'FAILED'})"
|
|
533
|
+
for i, s in enumerate(r["steps"], 1)) # fmt: skip
|
|
534
|
+
lines.append(
|
|
535
|
+
f"* QA test '{r['name']}' ({r.get('purpose', '')}) failed {where}: {r['failure']}. "
|
|
536
|
+
f"Steps: {done}. sf.state then: {json.dumps(r['state'])[:300]}"
|
|
537
|
+
+ (f". Errors: {' | '.join(map(str, r['errors'][:2]))}" if r["errors"] else "")
|
|
538
|
+
)
|
|
539
|
+
return "\n".join(lines)
|
|
540
|
+
|
|
541
|
+
|
|
542
|
+
def without_pictures(results: list[dict]) -> list[dict]:
|
|
543
|
+
return [{k: v for k, v in r.items() if k != "screenshots"} for r in results]
|
|
544
|
+
|
|
545
|
+
|
|
546
|
+
def slug(text: str) -> str:
|
|
547
|
+
return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")[:40] or "test"
|
|
548
|
+
|
|
549
|
+
|
|
550
|
+
def screenshot_files(results: list[dict]) -> dict[str, bytes]:
|
|
551
|
+
"""{"<test>-<label>.png": png} for every QA screenshot (names unique)."""
|
|
552
|
+
out: dict[str, bytes] = {}
|
|
553
|
+
for r in results:
|
|
554
|
+
for shot in r["screenshots"]:
|
|
555
|
+
name, n = f"{slug(r['name'])}-{slug(shot['label'])}", 2
|
|
556
|
+
while f"{name}.png" in out:
|
|
557
|
+
name, n = f"{slug(r['name'])}-{slug(shot['label'])}-{n}", n + 1
|
|
558
|
+
out[f"{name}.png"] = shot["png"]
|
|
559
|
+
shot["file"] = f"{name}.png"
|
|
560
|
+
return out
|
|
561
|
+
|
|
562
|
+
|
|
563
|
+
# --- the regression suite ------------------------------------------------------------------------
|
|
564
|
+
|
|
565
|
+
|
|
566
|
+
def merge_suite(
|
|
567
|
+
previous: QASuite | None,
|
|
568
|
+
new: list[QATest] | None,
|
|
569
|
+
version: int,
|
|
570
|
+
drop: list[str] = (),
|
|
571
|
+
notes: list[str] = (),
|
|
572
|
+
) -> QASuite:
|
|
573
|
+
"""Earlier tests (minus `drop`, matched by name) plus `new` ones (a same-named new test
|
|
574
|
+
replaces the old); at most MAX_SUITE, newest kept."""
|
|
575
|
+
dropped = {d.casefold().strip() for d in drop if d.strip()}
|
|
576
|
+
tests: dict[str, QATest] = {}
|
|
577
|
+
since: dict[str, int] = {}
|
|
578
|
+
for t in previous.tests if previous else []:
|
|
579
|
+
if t.name.casefold() not in dropped:
|
|
580
|
+
tests[t.name.casefold()] = t
|
|
581
|
+
since[t.name] = previous.since(t.name) or version
|
|
582
|
+
for t in new or []:
|
|
583
|
+
if t.name.casefold() not in dropped:
|
|
584
|
+
old = tests.pop(t.name.casefold(), None)
|
|
585
|
+
if old is not None:
|
|
586
|
+
since.pop(old.name, None)
|
|
587
|
+
tests[t.name.casefold()] = t
|
|
588
|
+
since[t.name] = version
|
|
589
|
+
kept = sorted(tests.values(), key=lambda t: -since[t.name])[:MAX_SUITE]
|
|
590
|
+
kept = [t for t in tests.values() if t in kept]
|
|
591
|
+
gone = sorted({*(previous.dropped if previous else []), *(d for d in drop if d.strip())})
|
|
592
|
+
return QASuite(tests=kept, versions=[since[t.name] for t in kept], dropped=gone,
|
|
593
|
+
notes=list(notes)) # fmt: skip
|
|
594
|
+
|
|
595
|
+
|
|
596
|
+
# --- exporting them --------------------------------------------------------------------------------
|
|
597
|
+
|
|
598
|
+
EXPORT_HEADER = """# QA tests for this game build: written by the SpriteForge QA Playtester from the game's
|
|
599
|
+
# design and played by the harness before you saw the build.
|
|
600
|
+
#
|
|
601
|
+
# pip install pytest playwright && python -m playwright install chromium
|
|
602
|
+
# pytest tests (from the build folder, or pass the path of this folder)
|
|
603
|
+
#
|
|
604
|
+
# Everything below up to "The tests" is the SpriteForge QA runtime, copied unchanged. The tests
|
|
605
|
+
# themselves are data (JSON in one string): steps are interpreted; a code check's JavaScript
|
|
606
|
+
# runs only inside the game's browser page, never in Python.
|
|
607
|
+
"""
|
|
608
|
+
|
|
609
|
+
EXPORT_GLUE = """
|
|
610
|
+
|
|
611
|
+
# ---------------------------------------------------------------------------------------------
|
|
612
|
+
# The tests: data written by the QA Playtester, played by the runtime above.
|
|
613
|
+
import pathlib # noqa: E402
|
|
614
|
+
|
|
615
|
+
import pytest # noqa: E402
|
|
616
|
+
from playwright.sync_api import sync_playwright # noqa: E402
|
|
617
|
+
|
|
618
|
+
BUILD = pathlib.Path(__file__).resolve().parents[1]
|
|
619
|
+
DATA = json.loads(DATA_JSON)
|
|
620
|
+
|
|
621
|
+
|
|
622
|
+
@pytest.fixture(scope="module")
|
|
623
|
+
def site():
|
|
624
|
+
with serve(BUILD) as url:
|
|
625
|
+
yield url
|
|
626
|
+
|
|
627
|
+
|
|
628
|
+
@pytest.fixture(scope="module")
|
|
629
|
+
def browser():
|
|
630
|
+
with sync_playwright() as pw:
|
|
631
|
+
chromium = pw.chromium.launch(headless=True)
|
|
632
|
+
yield chromium
|
|
633
|
+
chromium.close()
|
|
634
|
+
|
|
635
|
+
|
|
636
|
+
@pytest.mark.parametrize("qa", DATA["tests"], ids=[t["name"] for t in DATA["tests"]])
|
|
637
|
+
def test_qa(qa, site, browser):
|
|
638
|
+
context = browser.new_context(viewport={"width": 320, "height": 180})
|
|
639
|
+
try:
|
|
640
|
+
run = run_check if "code" in qa else run_test # a code check runs in the page (L2.8)
|
|
641
|
+
result = run(context.new_page(), site, qa, DATA["fps"])
|
|
642
|
+
finally:
|
|
643
|
+
context.close()
|
|
644
|
+
assert result["passed"], "step %s: %s" % (result["failed_step"], result["failure"])
|
|
645
|
+
"""
|
|
646
|
+
|
|
647
|
+
|
|
648
|
+
def export_tests(tests: list, fps: int = 30) -> str:
|
|
649
|
+
"""`tests/test_game_qa.py` for a build: the runtime, then the tests as JSON inside a single
|
|
650
|
+
string literal made by `repr` (model text never becomes code)."""
|
|
651
|
+
runtime = Path(qa_runtime.__file__).read_text(encoding="utf-8")
|
|
652
|
+
data = json.dumps({"fps": fps, "tests": [t.model_dump() for t in tests]}, indent=1)
|
|
653
|
+
return EXPORT_HEADER + runtime + "\n\nDATA_JSON = " + repr(data) + "\n" + EXPORT_GLUE
|
|
654
|
+
|
|
655
|
+
|
|
656
|
+
def write_export(build_dir: Path, tests: list, fps: int = 30) -> Path:
|
|
657
|
+
path = Path(build_dir) / "tests" / "test_game_qa.py"
|
|
658
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
659
|
+
path.write_text(export_tests(tests, fps), encoding="utf-8")
|
|
660
|
+
return path
|
|
661
|
+
|
|
662
|
+
|
|
663
|
+
def step_texts(test: QATest) -> list[str]:
|
|
664
|
+
return [describe_step(s.model_dump()) for s in test.steps]
|