源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)

apps/desktop/tests/smoke.md

@@ -0,0 +1,85 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# Desktop smoke runbook
+
+Use the narrowest deterministic check that covers the change, then add live-window evidence or a Storybook story when the risk requires it. Scenario inventories and check identifiers live in the scripts and fixtures, not in this document.
+
+## Automated desktop checks
+
+Run the desktop test suite for main-process, IPC, fixture, or contract changes:
+
+```bash
+npm run build:test
+npm --workspace @maka/desktop run test:dist
+```
+
+For a journey across renderer and main, extend the existing Playwright E2E suite and run:
+
+```bash
+npm --workspace @maka/desktop run e2e
+```
+
+Keep these runs on the fake backend and use deterministic fixtures.
+
+## Real Electron window smoke
+
+Screenshots and DOM checks do not prove native resize, drag regions, modal focus, or a healthy live renderer. Changes to the shell, sidebar, modal backdrop, window drag regions, or top-level renderer lifecycle must run:
+
+```bash
+npm --workspace @maka/desktop run smoke:real-window
+```
+
+The script builds the required workspaces, launches Electron with isolated user data, records programmatic checks, and prompts for native OS checks. Confirm that:
+
+- the window launches without a crash or ErrorBoundary;
+- each edge resizes and dragging all four corners resizes diagonally;
+- allowed titlebar regions drag the window while controls do not;
+- the Search modal opens and closes by button, backdrop, and Escape;
+- Tab and Shift+Tab stay inside the modal and return focus afterward;
+- modal-open window edges remain resizable;
+- switching modules after closing the modal leaves the renderer healthy.
+
+Reports are written under `apps/desktop/tests/real-window-smoke/`. A failed or unverified native check must remain visible in the report. A UI-shell PR is not ready to merge until the required report is attached or summarized for review.
+
+For environments that cannot perform native hit testing, run the programmatic layer explicitly and record the limitation:
+
+```bash
+npm --workspace @maka/desktop run smoke:programmatic-window
+```
+
+## Storybook baseline and visual contracts
+
+Storybook is the production-backed design catalog, not a screenshot or desktop E2E harness. Page-level stories (e.g. `apps/desktop/stories/settings/settings-pages.stories.tsx`) render each surface with mocked IPC via `withScopedMakaBridge`; add a story variant for any state the page does not already cover. CI only builds the catalog and mounts every story once without running `play`. Style, layout and interaction invariants belong in focused component contracts or the real Electron E2E harness. Run Storybook with:
+
+```bash
+npm --workspace @maka/desktop run storybook
+```
+
+To inspect a deterministic fixture interactively without touching a real workspace (the same `MAKA_E2E_FIXTURE` mechanism the Playwright E2E suite uses):
+
+```bash
+MAKA_E2E_FIXTURE=all npm --workspace @maka/desktop run dev
+```
+
+Use a scenario name from the fixture registry for a narrower launch.
+
+## Release floor
+
+Before a release, run the full automated suite and real-window smoke on supported desktop platforms. Visual regressions are caught by Storybook stories and computed-style contract tests; record any platform that could not be verified rather than treating absence of evidence as a pass.