testing-seatmark-local

name	testing-seatmark-local
description	How to run and test SeatMark locally (vite dev server with edge-function middleware, devCode login, admin health check)

Testing SeatMark locally

• cd app && npm install && npm run dev — vite on http://localhost:5173. app/scripts/devApi.mjs runs edge-functions/api/[[default]].js in-process with an in-memory KV, so all /api/* routes work locally without EdgeOne.
• devApi reads process.env for RESEND_API_KEY / TENCENT_SES_* / AUTH_SECRET / ADMIN_EMAILS. If the shell has a real RESEND_API_KEY (Devin secrets inject one), the mail channel becomes resend and /api/auth/code attempts a real Resend call (may 502). To test the unconfigured/none channel, start with env -u RESEND_API_KEY -u TENCENT_SES_SECRET_ID -u TENCENT_SES_SECRET_KEY npm run dev.
• Login: go to /account, enter [e-mail] (default admin, override via ADMIN_EMAILS), click 获取验证码. When no mail channel is configured and host is localhost, the API returns devCode and the UI auto-fills it (toast 邮件服务未接入); click 登录.
• Admin panel: /admin (link 进入管理后台 on /account after admin login). Health check section 环境健康检查 shows KV / 邮件服务 (mail channel) / AUTH_SECRET status; JSON at /api/admin/health (requires admin session cookie — view it in the logged-in browser, not curl).
• npm run test (vitest) and npm run build both run from app/.
• Membership/redeem (post-#308): every new registration gets 7-day pro (pro.until in /api/auth/me; /account badge 专业版会员·日期到期, quota card 不限) — so a "free-tier" account cannot be created via register; the free-quota UI branch needs an expired/legacy account. Invite flow: land on /?ref=<8hex share code> (stored in localStorage sm-invite-ref), then register — invitee +14d total, inviter +7d via deferred write (re-login inviter to confirm). Admin /admin 兑换码管理 generates codes and auto-copies them to clipboard — read them from the shell via xclip -selection clipboard -o (CDP navigator.clipboard.readText() fails). Redeem at /account#redeem: success toast 兑换成功/+N天, same-user retry toast 兑换码已生效 (idempotent), other user inline red 兑换码已被使用, unknown code 兑换码无效, malformed 兑换码格式不正确. Note the account-menu logout item is at a lower position for admins (extra 管理后台 entry) — screenshot the open menu before clicking.
• Redeem hardening (post-#310): the server stores only sha256-hashed redeem keys (redeem:<sha256('redeem-code:'+code)>); plaintext codes appear ONLY in the POST /api/admin/codes response and a one-time amber box on /admin — capture them immediately (textarea or clipboard), refresh loses them and the batch list shows only 末4位 masks. To test legacy plaintext-key migration locally, temporarily seed redeem:SM-XXXX-XXXX-XXXX into devKvStore in app/scripts/devApi.mjs (revert after). For concurrent-settle testing, register two users via curl (cookie jars) and fire two parallel POST /api/redeem with the same code — expect exactly one 200 and one 409. Post-#311 this is fixed: GET /api/admin/users returns only whitelisted fields (email/createdAt/lastLoginAt/loginCount/templateCount/proUntil/inviteCount/invitedBy; keys with no value are omitted from the JSON) — verify by grepping the raw response body for passwordHash/passwordSetAt/pbkdf2.
• Avoid pkill -f vite inside the same exec call that restarts vite — it can match/kill your own shell command; kill via fuser -k 5173/tcp in a separate call, then start the server in a dedicated background shell.
• Useful DEV localStorage keys for browser testing: seatmark.dev.force-export-fail = '1' forces PDF export page-render failure (DEV builds only; toast must say quota not consumed); anonymous watermark-free quota lives in seatmark.clean-export-usage.v1; Edit One hint dismissal in seatmark.edit-one-hint-dismissed.v1 (clear it to re-show the first-visit hint bubble in Studio preview).
• To test export cancellation, make the export slow enough: in Studio set 行数 (rows) to 1 with demo data → ~8 pages, then click 取消 on the progress overlay immediately. A 3-page export finishes too fast to cancel reliably. Chain the choose-export click and the 取消导出 click in one computer-use action batch (~1.5s apart) — inserting a screenshot between them adds ~10s and the export finishes first; a late click can land on a preview label and open the 单张覆写 dialog instead.
• PNG export (图片 PNG button): eink800 template defaults to 精确像素 800×480 + 纯黑白; verify outputs with Pillow (exact size, gray values ⊆ {0,255}, distinct md5 per page). Note: in 纯黑白 mode the semi-transparent DOM watermark is erased by binarization; the exporter re-stamps a pure-black 「SeatMark 座签 · seatmark.cn」 line at the bottom (then re-binarizes at threshold 200), so watermarked-mono PNGs stay pure {0,255} but differ from clean-mono ones — assert pixel diff > 0 and visible bottom text. Reset anonymous quota between runs via localStorage.removeItem('seatmark.clean-export-usage.v1') + reload.
• To test the share short-code failure dialog, override fetch in the page console to return a 545 for /api/share/tpl (DevTools request blocking also works); restore afterwards to verify recovery.
• Responsive checks at 390/768 need Chrome DevTools device mode (Chrome window min width ≈532px on Linux); assert document.documentElement.scrollWidth <= window.innerWidth per route. Always type full URLs (http://localhost:5173/...) with ctrl+l — bare localhost:5173/x can be misparsed as a chrome:// URL in some address-bar states.
• Cloud template sync testing (r303): create templates via /studio 新建模板 designer (保存 keeps the same id — edit an objective field like 标签高 as the update marker; renaming via the designer name field may not visibly apply, don't rely on it). /account buttons 同步到云端 (PUT /api/account/templates, resp {ok,count}) and 从云端找回 (GET; toast 云端共 N 个模板，新增 M 个到本设备; both buttons are disabled when local=0 and cloud=0 — that disabled state is itself the isolation evidence for a fresh account). Simulate a new device via CDP Network.clearBrowserCookies + Storage.clearDataForOrigin(origin,'all') (connect with suppress_origin=True to avoid 403). To prove a restored template is usable, load demo data (先用演示数据看看效果), select the restored template card, and run a watermark-free 图片版 PDF export.
• Refreshing /studio can clear in-memory demo data (0 pages); re-load via 先用演示数据看看效果.
• Studio export downloads land in ~/Downloads — page-level Browser.setDownloadBehavior does NOT redirect them; just watch that directory for new files.
• The PNG export dialog's 成图单位/输出尺寸 controls are custom dropdowns: click the current-value button to expand, then click the target option, then re-read the button text to confirm the selection took.
• NEVER run git checkout <ref> -- . in the shared working tree — it silently wipes uncommitted test-report/skill increments. git stash first or commit report files before switching refs.
• To verify PNG indexed color / bit depth, parse the PNG IHDR bytes directly (offset 16–26: bitdepth + colortype, 3 = Palette); identify %z reports 8 for 1-bit palette PNGs and is ambiguous.
• The Studio Excel import page has two hidden file inputs (the 1st accepts .json, the 2nd is the .xlsx one) — pick the right index for CDP DOM.setFileInputFiles.
• The export-choice dialog's 无水印/带水印 options are two stacked rows that export immediately on click — screenshot and verify the target row's text/coordinates before clicking (a misclick silently exports the other watermark path).
• To objectively determine which watermark path an export took: inspect the output's bottom edge for the watermark badge (pdftoppm / unpack PNG) and read seatmark.clean-export-usage.v1.
• After the anonymous watermark-free quota is exhausted the export badge shows 「带水印免费」, not 「剩余 0 次」 — this is by design, don't flag it.
• Start background Chromium with setsid nohup chromium ... </dev/null & — without setsid the browser is killed when the launching exec session ends (it exits silently).
• /tmp is wiped on VM restarts: CDP helper scripts and unpacked export baselines kept there are lost. Keep helper scripts and any baseline artifacts needed for cross-round size/quality comparisons under ~/ (e.g. ~/seatmark-test/), and expect to regenerate baselines if only /tmp copies existed.
• To check whether the production backend storage is actually bound, read the x-seatmark-storage response header on any /api/* request: kv/blob = persistent; memory = all KV-backed features (share short codes, share credits, login codes, team reservations) are non-persistent and will fail across requests.
• QR code verification: crop the QR region from a screenshot and decode with zbarimg -q <img>; short-code QRs encode /?s=<10-hex>, long-link QRs encode /studio#tpl=v1.….
• Photo pipeline testing: on a photo template (e.g. withPhoto), pick the match column in 照片匹配 first, then upload images whose filenames equal/contain the matched column values (e.g. 张伟.jpg) — mismatched names silently match 0 rows.
• On mobile (<768px) the Studio is a 设置/预览 two-tab layout; export buttons live inside the 预览 tab, not the settings tab.
• The 单张覆写 (per-card override) entry point is a single click on any label card in the preview (.label-field__content), not a double-click.
• Studio preview shows a first-visit 「小技巧：单张覆写」hint bubble that can swallow clicks on label cards — dismiss it before clicking preview cards.
• Native controls (e.g. the multi-sheet 工作表 dropdown) can be driven by setting .value + dispatchEvent('change') — same handler as a user pick; verify by re-reading the value and resulting state. Lighthouse audits: CHROME_PATH=/opt/.devin/playwright_browsers/chromium-1097/chrome-linux/chrome npx --yes lighthouse <url> --chrome-flags="--headless=new --no-sandbox" --output=json (add --preset=desktop for desktop); don't pkill chrome first (kills your CDP session); CLS culprits are in JSON audits['layout-shifts'].details.items[].node.selector. Print capture: the /seating and studio print hosts mount only during a print click (~1.2s delayed mount, unmounted after afterprint), so a bare Page.printToPDF yields blank pages. Stub window.print=()=>{}, click the real print button, then call Page.printToPDF({preferCSSPageSize:true}) within the 1.3–2.5s window. Auth hardening (post-#324: captcha + confirm password + password reset) Register/login/reset-code all require the arithmetic captcha (GET /api/auth/captcha, question like 4 + 8 = ?); wrong answer → HTTP 400 with 「验证码不正确或已过期，请重试」 and the frontend auto-fetches a new question; a 换一题 button also refreshes it. Register and reset show a confirm-password field with inline red 「两次输入的密码不一致」; mismatched submit sends no network request (verify via performance.getEntriesByType('resource') counts; r.responseStatus gives HTTP codes for asserting 400/401 without devtools). Password reset: 忘记密码？ on the login form → email + captcha → 发送重置验证码 (POST /api/auth/reset-code, anti-enumeration toast, 60s resend cooldown). With no mail channel configured (start dev with env -u RESEND_API_KEY -u TENCENT_SES_SECRET_ID -u TENCENT_SES_SECRET_KEY npm run dev) the response includes devCode which the UI auto-fills into the 邮件验证码 input. Then new password ×2 → 重置密码并登录 auto-logs in; old password afterwards returns 401 邮箱或密码不正确. Since #324 the edge function rev is r314 (check any /api response header x-seatmark-rev). Image captcha (post-#326, rev r316) GET /api/auth/captcha returns {image: "data:image/svg+xml;base64,...", token} (4 chars, charset excludes 0/O/1/I/L; answer is case-insensitive; server keeps only a hash, answer never sent to client). To answer in tests, decode the page's current img src and extract chars in order: atob(document.querySelector('form img').src.split(',')[1]) then regex />([2-9A-Z])<\/text>/g. Must read the SAME img the page holds (token must match). Refresh paths: 「换一张」button AND clicking the image itself both refresh; a wrong answer (e.g. "0000", impossible since charset lacks 0) returns 400 and the frontend auto-swaps the image. Note: after an error message appears, the submit button shifts down ~25px — re-locate it before clicking.