first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,77 @@
|
||||
## Context
|
||||
|
||||
The architecture stream now has API-backed platform, run, platform_web, and plugin proof, plus a documented local debug workspace that can start the real stack, seed `game.example`, create `server-local-debug`, and verify a manual browser walkthrough. The remaining gap is repeatability: browser acceptance currently lives as task evidence and operator procedure, so regressions can slip in when route text, auth behavior, local fixture setup, plugin marketplace data, lifecycle operation surfaces, or safety redaction drift.
|
||||
|
||||
The automated suite should preserve the existing architecture boundaries. Browser checks must exercise platform_web through platform-owned API routes, not direct run or plugin transports. Fixture setup should reuse the local debug scripts and safe dev plugin manifest instead of inventing a second seed path. The suite should be useful locally and in CI-like verification while staying scoped to the game server management platform.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Provide one automated browser acceptance command that verifies the API-backed local debug console path end to end.
|
||||
- Reuse or orchestrate the documented local debug stack and smoke fixture so acceptance data matches the manual proof path.
|
||||
- Verify login and required first-party routes: 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
|
||||
- Verify server detail and core plugin/server operation surfaces, including plugin marketplace data, lifecycle controls or operation-history proof, and log/artifact references.
|
||||
- Fail when platform_web uses local/demo fallback data, when required API-backed evidence is missing, or when visible content exposes forbidden sensitive fragments.
|
||||
- Record deterministic evidence that can be cited from OpenSpec tasks.
|
||||
|
||||
**Non-Goals:**
|
||||
- Do not change product behavior, visual direction, authorization semantics, or plugin/runtime contracts.
|
||||
- Do not implement a cloud, billing, host marketplace, or unrelated SaaS workflow.
|
||||
- Do not require Docker-only infrastructure, real game binaries, raw credentials, raw AI keys, direct sockets, or plugin/browser direct access to run.
|
||||
- Do not replace unit, API, manifest, or local-debug smoke tests; this suite complements those checks by verifying browser-visible behavior.
|
||||
- Do not broaden acceptance into full visual regression testing or screenshot comparison.
|
||||
|
||||
## Decisions
|
||||
|
||||
1. Reuse the local debug workspace as the acceptance fixture.
|
||||
|
||||
The suite should either self-start the documented local debug stack or require an explicit command that does so, then run `scripts/local-debug-smoke.sh` to seed and verify the platform/run/plugin fixture before browser checks. This keeps the browser acceptance data aligned with `docs/local-debug-workspace.md` and avoids parallel fixture drift.
|
||||
|
||||
Alternative considered: seed browser acceptance through a separate frontend-only mock. That would make the suite faster but would not prove real platform/run/plugin integration or prevent demo-only regressions.
|
||||
|
||||
2. Put the acceptance harness near platform_web but keep stack orchestration at repository script level.
|
||||
|
||||
Browser route assertions are frontend-facing and should live with platform_web tests or a clearly named acceptance harness. Starting platform, run, smoke, and frontend should remain in scripts so contributors can run one documented command without learning test internals.
|
||||
|
||||
Alternative considered: hide all service orchestration inside a test file. That makes local failures harder to diagnose because logs, ports, and reset behavior become less visible than the existing local debug workflow.
|
||||
|
||||
3. Assert stable user-visible and route-level signals, not screenshots.
|
||||
|
||||
The suite should inspect URLs, visible text, buttons/links, and API-backed markers such as `数据已加载`, `账号 API 已连接`, `game.example`, `server-local-debug`, `run-local-debug`, lifecycle controls, and marketplace bridge actions. It should avoid brittle pixel assertions and should not depend on decorative theme details beyond preserving the existing UI test/build gates.
|
||||
|
||||
Alternative considered: screenshot or visual diff acceptance. That is higher maintenance and better suited for a later design-polish workflow.
|
||||
|
||||
4. Centralize fallback and forbidden-fragment scanning.
|
||||
|
||||
Every route check should run a shared scanner for fallback/demo indicators and forbidden fragments: `/Users/`, `/private/`, `unix://`, `tcp://`, `Bearer `, `sk-`, `password=`, `apiKeyRef`, `rawApiKey`, run session tokens, direct run URLs, and plugin-owned transport details. Keeping this scanner shared makes new route coverage safer to add.
|
||||
|
||||
Alternative considered: duplicate string checks per page. That is easy to start but likely to drift and miss new route surfaces.
|
||||
|
||||
5. Produce machine-readable and human-readable evidence.
|
||||
|
||||
The acceptance command should print concise pass/fail output and write an evidence artifact, such as JSON or markdown, listing routes visited, assertions passed, stack URLs, seed evidence directory, and any failure details. OpenSpec tasks should cite that evidence after the command actually runs.
|
||||
|
||||
Alternative considered: rely only on terminal output. Terminal output is useful but too easy to lose during long stream handoffs.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Port collisions -> Allow configurable local debug ports and make the acceptance command print resolved URLs and log paths.
|
||||
- Browser automation flakiness -> Use deterministic local data, stable route URLs, bounded waits for specific page states, and concise route assertions rather than long click chains.
|
||||
- Long-running service cleanup -> Reuse `scripts/local-debug-reset.sh` and ensure self-started acceptance runs stop tracked processes on success and failure.
|
||||
- False positives from sensitive text inside docs or forms -> Scan only visible browser content and acceptance evidence intended for users, while still treating sensitive visible strings as failures.
|
||||
- Fixture drift from smoke data -> Run or require `scripts/local-debug-smoke.sh` before browser assertions and fail if expected local debug IDs are missing.
|
||||
- Sandbox limitations around localhost listeners or browser tooling -> Document when elevated permissions are needed for local listener tests, while keeping the suite command itself explicit and reproducible.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Add the browser acceptance harness and repository command wrapper.
|
||||
2. Reuse the local debug smoke fixture and add evidence output for route assertions and forbidden-fragment scanning.
|
||||
3. Run the new acceptance command against a clean local debug root.
|
||||
4. Run frontend typecheck/tests/build, relevant local debug smoke checks, `scripts/check-structure.sh`, and strict OpenSpec validation.
|
||||
5. Update stream evidence and next pointer after the change is implemented.
|
||||
|
||||
Rollback is straightforward: remove the acceptance harness and command wrapper if it proves unstable; no product runtime state or persisted user data model changes are introduced.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- None currently. During implementation, follow existing platform_web test tooling and local debug script conventions rather than adding a new browser framework if a suitable one already exists in the repository.
|
||||
Reference in New Issue
Block a user